Khamel83/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)
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.
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):**
That writes native config for Claude Code, Codex CLI, OpenCode, and Cursor. Restart the client after configuration. For manual stdio setup:
Or install from the MCP Registry:
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.
| 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.