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.

- 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-searchgives 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— passsession_idfor 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-urlwith 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.

- Quickstart
- Development
- Where Argus Writes Data
- Opinionated Workflows
- Providers
- HTTP API
- Dashboard
- Integration

- CLI
- MCP
- Python

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

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"

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"}}}}

{ "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.

SeeMCP Client Setupfor exact config files, verification commands, remote HTTP setup, and troubleshooting.

# 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

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

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

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

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

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

The repo includes.python-versionwith3.12souv,pyenv, and similar tools pick the right interpreter by default. More contributor guidance lives inCONTRIBUTING.md.

# 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/healthremains 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. Seeproduction operationsfor the canonical topology and operator procedures, andoperational statusfor endpoint semantics, readiness classification, observation expiry, and safe telemetry.

{ "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 includesurl,title,snippet,domain,provider, andscore. Thetracesarray shows which providers were called and their outcomes.

Wheninclude_attributionis true, each result also includesscore_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 toscore. Attribution is off by default and cached separately from non-attributed searches.

{ "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. SetARGUS_*_MONTHLY_BUDGET_USDto enforce custom limits per provider.

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.

SetARGUS_ADMIN_API_KEYto 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, setARGUS_ROOT_PATHto the external path prefix:

That makes dashboard redirects, links, and HTMX fragment URLs work when the proxy serves Argus at a path such ashttps://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 setARGUS_ROOT_PATHto the public prefix.

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--jsonfor structured output.

Passsession_idto 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 samesession_idgives the broker context from prior queries — follow-up searches are automatically refined using earlier conversation context. Sessions persist across restarts. Omitsession_idfor 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 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 MCP2025-11-25compatibility contract and the MCP2026-07-28stateless transport revision. The newer path is one-shot and does not require an initialize handshake orMcp-Session-Id; durable policy, budgets, sessions, and evidence remain owned by the HTTP authority. Seedocs/research/2026-08-11-mcp-stateless-production-authority.mdfor the source-backed boundary and required no-spend probes.

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

Use the full path ifargusisn't on PATH:"/home/you/.local/bin/argus". The adapter inheritsARGUS_AUTHORITY_URLandARGUS_AUTHORITY_TOKENfrom the client process. To run a local broker instead, development environments must explicitly setARGUS_MCP_STANDALONE=true; production rejects it.

Works withClaude Code,Codex CLI,OpenCode,Cursor, and any stdio-based MCP client. Useargus mcp init --global --client allto write native client configs for the current machine.

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

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

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

WithTailscale,<server>is your machine's Tailscale IP (e.g.100.x.x.x). One server, every machine on your mesh gets search.