# Argus core

ARGUS_ENV=development

ARGUS_LOG_LEVEL=INFO

# ── Quick Start ──────────────────────────────────────────────────────

# Argus works with ZERO configuration — DuckDuckGo, Yahoo, and GitHub

# are free tier-0 providers that need no API keys and no Docker.

# Just install and run:

# pip install argus-search

# argus search -q "python web frameworks"

#

# To unlock more providers, add API keys below. Free monthly tiers:

# Brave (2k/mo), Tavily (1k/mo), Exa (1k/mo), Linkup (1k/mo)

#

# SearXNG (self-hosted) is disabled by default — it requires Docker.

# ────────────────────────────────────────────────────────────────────

# Database

ARGUS_DB_URL=postgresql+psycopg2://postgres:postgres@localhost:5432/argus

# Optional runtime corpus root. If unset, Argus uses the platformdirs user-data location.

# ARGUS_DATA_ROOT=/absolute/path/to/argus-data

# Broker behavior

ARGUS_CACHE_TTL_HOURS=168

ARGUS_DISABLE_PROVIDER_AFTER_FAILURES=5

ARGUS_PROVIDER_COOLDOWN_MINUTES=60

ARGUS_DEFAULT_MAX_RESULTS=10

# ── Topology ────────────────────────────────────────────────────────

# ARGUS_NODE_ROLE: primary, worker, caller, or dev (default: primary)

# ARGUS_EGRESS_TYPE: residential, datacenter, or unknown (default: unknown)

# ARGUS_MACHINE_NAME: optional name of this machine for traces

# ARGUS_RESIDENTIAL_POLICY: off, fallback, prefer_on_datacenter, prefer_for_domains, always (default: fallback)

# ────────────────────────────────────────────────────────────────────

# SearXNG (self-hosted — requires Docker. Disabled by default.)

# Enable ONLY if you have a running SearXNG instance:

# docker run -d -p 8080:8080 searxng/searxng

ARGUS_SEARXNG_ENABLED=false

ARGUS_SEARXNG_BASE_URL=http://127.0.0.1:8080

# Optional: remote residential SearXNG (e.g. over Tailscale)

# ARGUS_SEARXNG_RESIDENTIAL_BASE_URL=http://100.112.130.100:8080

ARGUS_SEARXNG_TIMEOUT_SECONDS=12

# Brave (monthly recurring: 2,000 queries/month free tier)

ARGUS_BRAVE_ENABLED=true

ARGUS_BRAVE_API_KEY=

ARGUS_BRAVE_MONTHLY_BUDGET_USD=2000

ARGUS_BRAVE_TIMEOUT_SECONDS=15

# Serper (one-time signup: 2,500 credits — lifetime cap, never refills)

ARGUS_SERPER_ENABLED=true

ARGUS_SERPER_API_KEY=

ARGUS_SERPER_MONTHLY_BUDGET_USD=2500

ARGUS_SERPER_TIMEOUT_SECONDS=15

# Tavily (monthly recurring: 1,000 queries/month free tier)

ARGUS_TAVILY_ENABLED=true

ARGUS_TAVILY_API_KEY=

ARGUS_TAVILY_MONTHLY_BUDGET_USD=1000

ARGUS_TAVILY_TIMEOUT_SECONDS=20

# Exa (monthly recurring: 1,000 queries/month free tier)

ARGUS_EXA_ENABLED=true

ARGUS_EXA_API_KEY=

ARGUS_EXA_MONTHLY_BUDGET_USD=1000

ARGUS_EXA_TIMEOUT_SECONDS=20

# Optional providers

ARGUS_SEARCHAPI_ENABLED=false

ARGUS_SEARCHAPI_API_KEY=

ARGUS_SEARCHAPI_MONTHLY_BUDGET_USD=0

# You.com ($100 free credit, $5/1k search calls — ~20,000 queries, lifetime cap)

ARGUS_YOU_ENABLED=false

ARGUS_YOU_API_KEY=

ARGUS_YOU_MONTHLY_BUDGET_USD=20000

# You.com Contents API for extraction ($1/1k pages, uses same key)

# ARGUS_YOU_CONTENTS_ENABLED=true

# Parallel (one-time signup: 16,000 credits — lifetime cap, never refills)

ARGUS_PARALLEL_ENABLED=false

ARGUS_PARALLEL_API_KEY=

ARGUS_PARALLEL_MONTHLY_BUDGET_USD=16000

ARGUS_PARALLEL_TIMEOUT_SECONDS=15

# Linkup (monthly recurring: 1,000 queries/month free tier)

ARGUS_LINKUP_ENABLED=false

ARGUS_LINKUP_API_KEY=

ARGUS_LINKUP_MONTHLY_BUDGET_USD=1000

ARGUS_LINKUP_TIMEOUT_SECONDS=15

# Valyu ($10 free credit, ~$0.001/search call — ~10,000 queries, lifetime cap)

ARGUS_VALYU_ENABLED=false

ARGUS_VALYU_API_KEY=

ARGUS_VALYU_MONTHLY_BUDGET_USD=10000

ARGUS_VALYU_TIMEOUT_SECONDS=15

# GitHub (free, 10 req/min unauthenticated, 30/min with token)

ARGUS_GITHUB_ENABLED=true

ARGUS_GITHUB_API_KEY=

ARGUS_GITHUB_TIMEOUT_SECONDS=15

# Yahoo (free, scraped — no API key needed, fragile)

# Auto-disabled by health tracker if Yahoo HTML structure changes.

ARGUS_YAHOO_ENABLED=true

ARGUS_YAHOO_TIMEOUT_SECONDS=15

# WolframAlpha LLM API (monthly: 2,000 free calls/month)

# Get a free key at https://developer.wolframalpha.com/

# Also accepted: WOLFRAM_APP_ID env var or via secrets vault

ARGUS_WOLFRAM_ENABLED=true

ARGUS_WOLFRAM_API_KEY=

ARGUS_WOLFRAM_MONTHLY_BUDGET_USD=2000

ARGUS_WOLFRAM_TIMEOUT_SECONDS=15

# Crawl4AI (self-hosted extractor, no API key needed)

# ARGUS_CRAWL4AI_ENABLED=true

# Obscura headless browser (optional, https://github.com/h4ckf0r0day/obscura)

# No API key, no rate limit — self-hosted binary, Apache 2.0.

# Two independent modes (either or both can be active):

#

# Mode 1 — CLI extraction step: just install the binary on PATH.

# Argus auto-detects it via `which obscura`. No config needed.

# Install: https://github.com/h4ckf0r0day/obscura/releases

#

# Mode 2 — CDP backend for Playwright: run Obscura as a persistent server,

# then point Playwright at it. Playwright gains stealth + 30MB vs 200MB memory.

# Start server: obscura serve --stealth --port 9222

# ARGUS_OBSCURA_CDP_URL=ws://127.0.0.1:9222

#

# Timeout for CLI subprocess calls (default: 20s)

# ARGUS_OBSCURA_TIMEOUT_SECONDS=20

# Firecrawl (external extractor, 1 credit/page)

# ARGUS_FIRECRAWL_API_KEY=

# API / service

# Bind to loopback by default. For containerized/Tailscale deployments, widen this explicitly.

ARGUS_HOST=127.0.0.1

ARGUS_PORT=8000

ARGUS_BIND_HOST=127.0.0.1

# Optional interfaces

ARGUS_ALLOW_MCP=false

ARGUS_ALLOW_WEB_UI=false

# Logging / debug

ARGUS_LOG_FULL_RESULTS=false

ARGUS_LOG_PROVIDER_PAYLOADS=false

# Budget persistence (SQLite file path — needed for token balance tracking)

ARGUS_BUDGET_DB_PATH=argus_budgets.db

# API rate limiting (requests per window, per client IP)

ARGUS_RATE_LIMIT=60

ARGUS_RATE_LIMIT_WINDOW=60

# Caller auth for remote HTTP and remote MCP access.

# Local loopback callers can omit this; remote clients must send it as

# `Authorization: Bearer ...` or `X-API-Key: ...`.

# ARGUS_API_KEY=

# URL of a remote Argus server (e.g. on a homelab). Used by `argus mcp init`

# to generate remote streamable-http client configs instead of local stdio.

# Set this on client machines, not on the server itself.

# ARGUS_REMOTE_URL=http://argus-server:8271

# Optional stronger key for privileged admin routes such as:

# `/api/admin/health/detail`, `/api/admin/budgets`, `/api/admin/test-provider`,

# and `/api/admin/cookies/health`.

# If unset, admin routes fall back to ARGUS_API_KEY.

# ARGUS_ADMIN_API_KEY=

# Optional browser-facing origins. Leave unset for no CORS exposure by default.

# ARGUS_CORS_ORIGINS=https://argus.example.com,https://admin.example.com

# Content extraction

ARGUS_EXTRACTION_TIMEOUT_SECONDS=10

# Extraction cache TTL (hours) — avoids re-extracting the same URL

ARGUS_EXTRACTION_CACHE_TTL_HOURS=168

# Domain rate limiting (max requests per domain per window)

ARGUS_EXTRACTION_DOMAIN_RATE_LIMIT=10

ARGUS_EXTRACTION_DOMAIN_WINDOW_SECONDS=60

# Jina Reader API key (optional — Jina works without a key but rate-limited)

# ARGUS_JINA_API_KEY=

# Cookie auth storage and per-domain request pacing

# ARGUS_COOKIE_DIR=~/.config/argus/cookies

# ARGUS_AUTH_RATE_LIMIT=10

# Residential extraction (optional — routes extraction through remote residential workers)

# Multiple endpoints tried in order with per-endpoint circuit breakers (60s cooldown).

# Falls back to local extraction if all endpoints unreachable.

# If ARGUS_EGRESS_TYPE=residential is set, Argus prefers local extraction and skips remote workers.

#

# Deploy: see argus/extraction/residential_service.py

#

ARGUS_RESIDENTIAL_ENDPOINTS=http://homelab:8124,http://macmini:8123

# Legacy single-endpoint fallback, still accepted by the client.

# ARGUS_RESIDENTIAL_EXTRACTOR_URL=http://macmini:8123

# Residential worker bind address and request timeout.

# ARGUS_BIND_HOST=127.0.0.1

# ARGUS_RESIDENTIAL_TIMEOUT_SECONDS=25

# Required shared bearer secret between Argus and the residential worker.

# Remote residential extraction is disabled unless this is set on both sides.

# ARGUS_RESIDENTIAL_SHARED_SECRET=replace-with-long-random-secret

# Optional caller allowlist for the worker service. Keep the Tailscale/private defaults

# unless you have a specific reason to widen them.

# ARGUS_RESIDENTIAL_ALLOWED_CIDRS=127.0.0.1/32,::1/128,100.64.0.0/10,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16

# ARGUS_RESIDENTIAL_EXTRACTOR_TIMEOUT_SECONDS=30