Ghost Agent

Ghost Agent wraps an upstream OpenAI-compatible LLM endpoint (llama.cpp / Ollama / vLLM) with a full agentic stack: a hierarchical task planner, a six-tier memory subsystem backed by ChromaDB and SQLite, a Docker-API container sandbox for code execution, a swarm router for fanning work out across specialised LLM pools, and three separate user-facing interfaces (web UI, Slack bot, desktop "Clockwork Ghost").

This documentation set was reverse-engineered directly from the source under src/ghost_agent/ and interface/. Use the navigation on the left to drill into individual modules, or follow the links below for a guided tour.

Quick links

Source map

Conceptual model

Ghost Agent is best understood as five concentric layers:

1. Interface layer — web/Slack/desktop clients that talk HTTP/SSE to the FastAPI core.
2. API layer — Ollama-compatible HTTP routes that authenticate (X-Ghost-Key) and stream agent responses.
3. Reasoning core — GhostAgent drives a streaming chat loop, parses tool calls from <tool_call> XML, dispatches tools, and re-injects results.
4. Memory + planning — six memory tiers fused via Reciprocal Rank Fusion, plus a hierarchical TaskTree with postcondition gating, MCTS lookahead, and uncertainty tracking.
5. Execution substrate — Docker containers for tool calls, swarm/worker LLM pools for parallel inference, and Tor for anonymous outbound traffic.

The Architecture page contains the full diagram.

Anonymity & Tor routing

Ghost Agent treats Tor as the default transport for outbound traffic — not as an optional flag. The proxy endpoint is declared once via the TOR_PROXY env var (canonical value: socks5h://127.0.0.1:9050) and is honoured by every HTTP-touching tool in the codebase. The --anonymous CLI switch is enabled by default and additionally routes web_search through DuckDuckGo, which keeps no query logs.

The fetch pipeline

Every outbound call funnels through utils/helpers.helper_fetch_url_content(), which wraps curl_cffi and httpx with:

• SOCKS5h routing — DNS is resolved over Tor, not by the local resolver, so the operator's DNS server never sees the target hostname.
• SSRF guards — private, link-local, and loopback ranges are refused before the SOCKS layer is touched. A tool call can't become a host-network scanner.
• 5 MB body cap and 20 s timeout — bounds the damage a hostile exit node or target server can do by serving slow or unbounded bodies.
• 3-retry budget — transient failures are retried with a fresh Tor identity between attempts.

Identity rotation (NEWNYM)

request_new_tor_identity() in utils/helpers.py is the agent's circuit-burn primitive. Mechanically, it speaks the Tor control protocol to the local daemon and issues a SIGNAL NEWNYM: Tor marks the current circuit dirty, and every subsequent stream opens through a brand-new entry-guard / middle / exit chain. The agent's previous exit node is no longer reachable from the next hop.

Rotation fires:

• Automatically on HTTP 401 / 403 / 503 from web_search — a gateway or exit refusal usually clears on a different chain.
• Between retries in check_weather (3 attempts with identity refresh) and any tool that elects to re-enter the pool rather than hammer the same circuit.
• Between parallel reformulations in deep_research — the N parallel queries do not all emerge from the same exit.
• On explicit agent intent — the agent can invoke rotation as a tool step when a task's anonymity posture demands it (e.g. before re-visiting a site that just saw traffic).

What is and isn't routed through Tor

Sanity check & failure mode

The check_health tool probes the configured circuit on demand and reports whether check.torproject.org sees the request as Tor traffic, plus the current exit-node country. The probe is part of the default health readout — if the circuit is down or leaking to clearnet, the tool surfaces it loudly rather than silently degrading.