Argus

Retrieval platform for AI agents. Argus routes search across 14 providers, recovers dead URLs, captures important site content, builds local docs-plus-research packs, and persists everything with traceable local artifacts.

Features at a glance:

• Topology-aware acquisition — Argus knows if it's on a residential IP or datacenter, routing search and extraction automatically to avoid blocks and minimize network hops.
• 14 providers, one API — free-first tier routing, budget-exhausted providers skipped automatically
• Zero-key start — pip install argus-search gives you DuckDuckGo + Yahoo immediately, no accounts needed
• SearXNG self-host = 70+ engines — Google, Bing, Yahoo, Startpage, Ecosia, Qwant and more via one Docker container
• 12-step content extraction — returns full page text with quality gates, not just links
• Opinionated retrieval workflows — recover dead articles, capture important pages from a site, and build local docs-plus-research packs
• Argus-owned corpus storage — runtime data goes to a writable user data directory, not your repo checkout
• Multi-turn sessions — pass session_id for conversational context across searches
• Score attribution — optionally show which providers contributed to each fused RRF score
• Usage dashboard — inspect provider budgets, recent query volume, and machine-level usage at /dashboard
• 4 search modes — discovery, research, recovery, grounding
• Dead URL recovery — /recover-url with Wayback Machine and archive fallbacks
• 4 integration paths — HTTP API, CLI, MCP server, Python SDK

Built for AI agent builders, RAG pipelines, and ops teams who need reliable search, capture, and local evidence without stitching APIs together.

Status: beta. The retrieval workflows and corpus model are production-oriented, but still maturing.

Status: see the public status page. Authorized maintainers can use the private argus-ops README for the latest dated reports.

Current production checkpoint — September 7, 2026: The authenticated HTTP API and MCP adapter are operational, and sampled free search works through SearXNG, Yahoo, and GitHub. DuckDuckGo is intermittent and fails closed after acquisition-policy blocks. Production readiness is ready=true, degraded; paid providers are not currently admitted until their non-secret credential-version and account-scope bindings are recorded. Browser capability and recovery metadata evidence remain open. See the current status matrix before relying on a provider.

Contents

• Quickstart
• Development
• Where Argus Writes Data
• Opinionated Workflows
• Providers
• HTTP API
• Dashboard
• Integration
  • CLI
  • MCP
  • Python
• Content Extraction
• Architecture
• Configuration
• When Not To Use Argus
• FAQ

Quickstart

Mode 1: Local CLI (zero config)

pip install argus-search && argus search -q "python web frameworks"

That's it. DuckDuckGo handles the search — no accounts, no keys, no containers. You get unlimited free search from your laptop right now. Add API keys whenever you want more providers, or don't.

argus extract -u "https://example.com/article"       # extract clean text from any URL
argus recover-article -u "https://example.com/dead-post"
argus capture-site -u "https://docs.example.com"
argus build-research-pack -t "example sdk" --official-url "https://docs.example.com"

Works on any machine with Python 3.11+ — laptop, Mac Mini, Raspberry Pi, cloud VM. Nothing to host.

For MCP (Claude Code, Codex, OpenCode, Cursor, VS Code):

pipx install argus-search[mcp]
export ARGUS_MCP_STANDALONE=true  # explicit development-only local broker
argus mcp init --global --client all

That writes native config for Claude Code, Codex CLI, OpenCode, and Cursor. Restart the client after configuration. For manual stdio setup:

{"mcpServers": {"argus": {"command": "argus", "args": ["mcp", "serve"], "env": {"ARGUS_MCP_STANDALONE": "true"}}}}

Or install from the MCP Registry:

{
  "mcpServers": {
    "argus": {
      "registryType": "pypi",
      "identifier": "argus-search",
      "runtimeHint": "uvx",
      "env": {"ARGUS_MCP_STANDALONE": "true"}
    }
  }
}

Standalone development needs no server or keys, but it must be explicitly enabled. Production MCP always delegates to an authenticated HTTP authority.

See MCP Client Setup for exact config files, verification commands, remote HTTP setup, and troubleshooting.

Mode 2: Full Stack Server

Got a Raspberry Pi running Pi-hole? A Mac Mini on your desk? An old laptop? That's enough to run the full stack — SearXNG (your own private search engine, disabled by default) plus local JS-rendering content extraction.

# Optional: tell Argus it has residential egress to optimize routing
export ARGUS_EGRESS_TYPE=residential
ARGUS_SEARXNG_ENABLED=true docker compose up -d    # SearXNG + Argus

What you have	What you get
Any machine with Python 3.11+	DuckDuckGo + API providers (no server)
Home server / old laptop (4GB+)	Everything — SearXNG, all providers, Crawl4AI, Obscura
Mac Mini M1+ (8GB+)	Full stack with headroom
Free cloud VM (1GB)	SearXNG + search providers (use residential workers for extraction)

SearXNG takes 512MB of RAM and gives you a private Google-style search engine (disabled by default — set ARGUS_SEARXNG_ENABLED=true) that nobody can rate-limit, block, or charge for. It runs alongside Pi-hole on hardware millions of people already own.

Where Argus Writes Data

Argus code and Argus runtime data are different things.

• Code lives wherever you install or clone Argus.
• Runtime corpus data lives in a writable user data directory resolved by platformdirs, or in ARGUS_DATA_ROOT if you override it.

Inspect the exact paths on your machine:

argus paths

By default Argus writes:

• official docs cache under the resolved docs/cache/
• research packs under docs/research/
• workflow run state under workflows/runs/
• versioned workflow snapshots under snapshots/

This means Argus does not require a sibling ../docs-cache checkout. If you have an older docs-cache tree, import it once with:

argus corpus import-docs-cache -s /path/to/docs-cache

Opinionated Workflows

These workflows build local artifacts, not just transient JSON responses.

Recover A Dead Article

argus recover-article -u "https://example.com/old-post" -t "Example Post"

Argus searches for recovery candidates, extracts the best result, saves the recovered sources locally, and writes a citation-backed report plus manifest.

Capture The Important Parts Of A Site

argus capture-site -u "https://docs.example.com"

Argus stays on-domain, uses sitemap-assisted discovery plus heuristic link scoring, saves the important pages it finds, and writes a detailed summary with references.

Build A Docs + Research Pack

argus build-research-pack -t "example sdk"
argus build-research-pack -t "example sdk" --official-url "https://docs.example.com"

Argus captures official docs into its local docs cache, adds non-official supporting sources from search, and writes a combined research pack with traceable artifacts.

Development

Repo development is pinned to Python 3.12. The package runtime floor is Python 3.11, the production image runs Python 3.12.3, and Python 3.13 is the compatibility CI lane. Required CI passes all three; contributors should use the uv workflow below so local verification matches the canonical lane and does not accidentally use an older system interpreter.

uv sync --python 3.12 --extra dev --extra mcp
uv run pytest tests/ -v --tb=short

The repo includes .python-version with 3.12 so uv, pyenv, and similar tools pick the right interpreter by default. More contributor guidance lives in CONTRIBUTING.md.

Providers

Provider	Credit type	Free capacity	Setup
DuckDuckGo	Free (scraped)	Unlimited	None
Yahoo	Free (scraped)	Unlimited	None — fragile, auto-skipped if broken
SearXNG	Free (self-hosted, off by default)	Unlimited — 70+ engines¹	Docker
GitHub	Free (API)	Unlimited	None (token for higher rate limit)
WolframAlpha	Free (API key)	2,000 queries/month	free key
Brave Search	Monthly recurring	2,000 queries/month	dashboard
Tavily	Monthly recurring	1,000 queries/month	signup
Exa	Monthly recurring	1,000 queries/month	signup
Linkup	Monthly recurring	1,000 queries/month	signup
Parallel AI	Monthly recurring	$5 credit with card on file, up to 5,000 searches/month	signup
Serper	One-time signup	2,500 credits	signup
You.com	One-time signup	$20 credit	platform
Valyu	One-time signup	$10 credit	platform

¹ SearXNG aggregates Google, Bing, Yahoo, Startpage, Ecosia, Qwant, Wikipedia, and 60+ more — all behind a single self-hosted endpoint. Run docker compose up -d on any machine with 512MB of free RAM.

² WolframAlpha returns computed answers (math, unit conversions, factual lookups), not web search results. It only activates in grounding and research modes. Queries it can't compute (general web searches) return empty — no error, no health penalty.

7,000+ free queries/month from recurring free-tier providers with API keys (WolframAlpha 2k + Brave 2k + Tavily 1k + Exa 1k + Linkup 1k), or up to 12,000+ when Parallel's monthly credit is available to an eligible account with a card on file. DuckDuckGo, Yahoo, and GitHub have no monthly cap. SearXNG is disabled by default (enable in .env). Routing priority: Tier 0 (free: SearXNG*, DuckDuckGo, Yahoo, GitHub, WolframAlpha) → Tier 1 (monthly recurring: Brave, Tavily, Exa, Linkup, Parallel) → Tier 3 (one-time: Serper, You.com, Valyu, SearchAPI). Budget-exhausted providers are skipped automatically.

These are package-level provider tiers and advertised quotas, not proof of current production availability. The production authority fails closed for a credentialed provider until its registration fingerprint, account scope, budget, and approved test evidence are present. A protected key value alone does not prove that the current key works; see docs/STATUS.md for the live classification.

HTTP API

All endpoints prefixed with /api. OpenAPI docs at http://localhost:8000/docs.

Local loopback calls can use the API without auth. Remote HTTP callers must send ARGUS_API_KEY as either Authorization: Bearer ... or X-API-Key: .... Privileged routes under /api/admin/* require ARGUS_ADMIN_API_KEY (or fall back to ARGUS_API_KEY if no separate admin key is configured).

# Search
curl -X POST http://localhost:8000/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "python web frameworks", "mode": "discovery", "max_results": 5}'

# Search with score attribution
curl -X POST http://localhost:8000/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "python web frameworks", "include_attribution": true}'

# Multi-turn search (conversational refinement)
curl -X POST http://localhost:8000/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "what about async?", "session_id": "my-session"}'

# Extract content from a working URL
curl -X POST http://localhost:8000/api/extract \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/article"}'

# Recover a dead or moved URL
curl -X POST http://localhost:8000/api/recover-url \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/old-page", "title": "Example Article"}'

# Network-free process liveness (container health target)
curl http://localhost:8000/api/live

# Public minimal startup and cached readiness
curl http://localhost:8000/api/startup
curl http://localhost:8000/api/ready

# Authenticated operator status, health compatibility, and budgets
curl -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/status
curl -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/budgets
curl -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/maya-outbox/status
curl -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/maya-outbox/dead-letters
# After correcting the cause of a permanent rejection:
curl -X POST -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/maya-outbox/DELIVERY_ID/recover

/api/health remains a 200 liveness compatibility route. It intentionally does not check PostgreSQL, providers, Maya, or the browser, so a dependency outage cannot cause container restart storms. See production operations for the canonical topology and operator procedures, and operational status for endpoint semantics, readiness classification, observation expiry, and safe telemetry.

Search modes

Mode	Use for	Example
discovery	Related pages, canonical sources	"Find the official docs for X"
research	Broad exploratory retrieval	"Latest approaches to Y?"
recovery	Finding moved/dead content	"This URL is 404"
grounding	Fact-checking with live sources	"Verify this claim about Z"

Tier-based routing always applies first. Within each tier, the mode selects provider order.

Response format

{
  "query": "python web frameworks",
  "mode": "discovery",
  "results": [
    {
      "url": "https://fastapi.tiangolo.com",
      "title": "FastAPI",
      "snippet": "Modern Python web framework",
      "provider": "duckduckgo",
      "score": 0.0164,
      "score_attribution": {"duckduckgo": 0.0164},
      "egress": "unknown",
      "machine": null
    }
  ],
  "total_results": 1,
  "cached": false,
  "traces": [
    {"provider": "duckduckgo", "status": "success", "results_count": 5, "latency_ms": 312}
  ]
}

Each result includes url, title, snippet, domain, provider, and score. The traces array shows which providers were called and their outcomes.

When include_attribution is true, each result also includes score_attribution: a provider-to-score map that decomposes the result's Reciprocal Rank Fusion score. RRF is additive, so each provider's attribution is exactly its own rank contribution, and the values sum to score. Attribution is off by default and cached separately from non-attributed searches.

Budgets

{
  "budgets": {
    "brave": {"remaining": 1847, "monthly_usage": 153, "usage_count": 153, "exhausted": false},
    "duckduckgo": {"remaining": 0, "monthly_usage": 0, "usage_count": 42, "exhausted": false}
  },
  "token_balances": {"jina": 9833638}
}

Each provider tracks usage. Tier 1 (monthly) uses a 30-day rolling window; tier 3 (one-time) uses a lifetime counter that never resets. When a provider hits its budget, Argus skips it and moves to the next. Free providers (DuckDuckGo, GitHub) have no limit. SearXNG is free but disabled by default. Set ARGUS_*_MONTHLY_BUDGET_USD to enforce custom limits per provider.

Dashboard

Run the HTTP server and open /dashboard:

argus serve
# http://127.0.0.1:8000/dashboard

The dashboard shows provider budget burn, over-pace and exhausted providers, query volume for the last 30 days, usage by machine, and recent provider activity. Budget cards refresh automatically.

Set ARGUS_ADMIN_API_KEY to require dashboard login. If no admin key is set, the dashboard is open to anyone who can reach the server, which is suitable only for trusted local use.

For subpath deployment behind a reverse proxy, set ARGUS_ROOT_PATH to the external path prefix:

ARGUS_ROOT_PATH=/argus argus serve

That makes dashboard redirects, links, and HTMX fragment URLs work when the proxy serves Argus at a path such as https://khamel.com/argus/.

For direct public HTTPS, the repo includes a Caddy profile:

ARGUS_DOMAIN=argus.example.com ACME_EMAIL=you@example.com \
  docker compose --profile proxy up -d

For an existing Authentik/nginx deployment, keep authentication at the proxy layer and set ARGUS_ROOT_PATH to the public prefix.

Integration

CLI

argus search -q "python web framework"              # zero-config, uses DuckDuckGo
argus search -q "python web framework" --mode research -n 20
argus search -q "python web framework" --free        # free providers only (no paid API calls)
argus search -q "python web framework" --attribution # show per-provider score attribution
argus search -q "fastapi" --session my-session       # multi-turn context
argus extract -u "https://example.com/article"       # extract clean text
argus extract -u "https://example.com/article" -d nytimes.com  # auth extraction
argus recover-url -u "https://dead.link" -t "Title"
argus doctor                                         # full setup diagnostics
argus health                                         # provider status
argus budgets                                        # budget + token balances
argus mcp check                                      # validate MCP setup
argus set-balance -s jina -b 9833638                 # track token balance
argus test-provider -p brave                         # smoke-test a provider
argus serve                                          # start API server
argus mcp serve                                      # start MCP server
argus mcp init                                       # add MCP config to project

All commands support --json for structured output.

Pass session_id to any search call. Argus stores each query and extracted URL through the same SQLAlchemy repository used by the retrieval ledger (ARGUS_DB_URL, PostgreSQL in production and SQLite for direct local use). Reusing the same session_id gives the broker context from prior queries — follow-up searches are automatically refined using earlier conversation context. Sessions persist across restarts. Omit session_id for stateless, one-shot searches.

Legacy sessions from the former budget SQLite database can be reconciled without mutating the target first:

argus ledger reconcile-sessions \
  --source sqlite:///argus_budgets.db \
  --target "$ARGUS_DB_URL"
# Review source/imported/skipped/conflicting, then repeat with --apply.

The import is idempotent: an identical existing session is skipped and a different session with the same ID is reported as conflicting.

MCP

MCP is a stateless execution adapter over the authenticated HTTP API. It does not construct providers or a broker and does not own browser, database, budget, session, health, or outbox state. Configure the adapter process with:

export ARGUS_AUTHORITY_URL=http://argus-api:8000
export ARGUS_AUTHORITY_TOKEN=replace-with-a-scoped-caller-token

The deployed production endpoint supports both the verified MCP 2025-11-25 compatibility contract and the MCP 2026-07-28 stateless transport revision. The newer path is one-shot and does not require an initialize handshake or Mcp-Session-Id; durable policy, budgets, sessions, and evidence remain owned by the HTTP authority. See docs/research/2026-08-11-mcp-stateless-production-authority.md for the source-backed boundary and required no-spend probes.

Option A — Local adapter (stdio)

Install the adapter on the same machine as your MCP client:

{
  "mcpServers": {
    "argus": {
      "command": "argus",
      "args": ["mcp", "serve"]
    }
  }
}

Use the full path if argus isn't on PATH: "/home/you/.local/bin/argus". The adapter inherits ARGUS_AUTHORITY_URL and ARGUS_AUTHORITY_TOKEN from the client process. To run a local broker instead, development environments must explicitly set ARGUS_MCP_STANDALONE=true; production rejects it.

Works with Claude Code, Codex CLI, OpenCode, Cursor, and any stdio-based MCP client. Use argus mcp init --global --client all to write native client configs for the current machine.

Detailed client setup and verification commands live in docs/mcp-clients.md.

Option B — Remote MCP adapter (clients over Tailscale)

Run Argus on one machine, connect every client over the network. No local install on clients.

On the adapter host:

export ARGUS_API_KEY=replace-with-a-long-random-secret
export ARGUS_AUTHORITY_URL=http://argus-api:8000
export ARGUS_AUTHORITY_TOKEN="$ARGUS_API_KEY"
argus mcp serve --transport streamable-http --host YOUR_TAILSCALE_IP --port 8001

Remote MCP credentials must also be valid scoped credentials at the HTTP authority because the adapter forwards each authenticated bearer token unchanged. For stdio, ARGUS_AUTHORITY_TOKEN is the caller credential.

To keep the HTTP API and remote MCP service running after reboot on a systemd host:

cat >mcp.env <<'EOF'
ARGUS_AUTHORITY_URL=http://argus-api:8000
ARGUS_AUTHORITY_TOKEN=replace-with-scoped-caller-token
ARGUS_API_KEY=replace-with-the-same-scoped-caller-token
EOF
chmod 600 mcp.env
ARGUS_MCP_ENV_FILE="$PWD/mcp.env" scripts/install-systemd.sh
systemctl status argus argus-mcp --no-pager

The installer validates the minimal adapter environment, installs it as root-only /etc/argus/mcp.env, then installs and starts both units. The MCP unit never loads the authority's .env, provider vaults, database settings, browser paths, or writable data volumes.

On each client: