┌────────────┐    POST /search    ┌──────────────────────────────┐
│  HTTP CLI  │ ─────────────────▶ │                              │
└────────────┘                    │   oxe (FastAPI + uvicorn)    │
                                  │                              │
┌────────────┐    MCP /mcp/       │  ┌────────────────────────┐  │
│  Claude /  │ ─────────────────▶ │  │  SQLite (WAL) cache    │  │
│  Hermes /  │                    │  │  + ddgs (DuckDuckGo)   │  │
│  Cursor    │                    │  └────────────────────────┘  │
└────────────┘                    │                              │
                                  │  Preact SPA (ui/dist)        │
┌────────────┐  browser           │  + SSE /answer streaming     │
│  You, via  │ ─────▶ /  ────────▶│  + sendBeacon /click         │
│  browser   │                    └──────────────────────────────┘
└────────────┘

• oxe/cache.py — SQLite WAL, gzip values, TTL eviction.
• oxe/exa_compat.py — Exa request/response to ddgs translation.
• oxe/search.py — shared do_search(cache, req) used by HTTP and MCP.
• oxe/server/ — FastAPI app split into APIRouters per resource group.
• oxe/mcp_server.py — MCP server with the two tools above.
• oxe/ai.py — provider-backed answer generation with a tool loop over search.
• ui/ workspace (not packaged) — Preact SPA; built bundle served via OXE_UI_DIST.

• RSS: ~22 MB without the ai extra, ~56 MB with oxe[ai] (aisuite imports provider SDKs lazily). 200 MB ceiling.
• Disk: ~/.cache/oxe/cache.db typically under 10 MB; WAL file under 5 MB.
• Network: one DuckDuckGo request per unique cache miss. Cached responses replay instantly.
• Third-party services: none. No API keys, no telemetry.

from oxe.cache import TTLCache
from oxe.search import do_search

cache = TTLCache("/tmp/my-cache.db")
hits = do_search(cache, {"query": "python asyncio", "numResults": 5})

# Or build a standalone app with your own cache/backend/observer:
app = oxe.make_app(cache=cache)

Configuration is via OXE_* env vars (table above).

systemd

# ~/.config/systemd/user/oxe.service
[Unit]
Description=oxe web-search proxy
After=network.target

[Service]
ExecStart=/home/you/.local/bin/oxe
Restart=on-failure
Environment=OXE_PORT=4479

[Install]
WantedBy=default.target

systemctl --user enable --now oxe

launchd (macOS)

<!-- ~/Library/LaunchAgents/local.oxe.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>local.oxe</string>
  <key>ProgramArguments</key>
  <array>
    <string>/Users/you/.local/bin/oxe</string>
  </array>
  <key>EnvironmentVariables</key>
  <dict>
    <key>OXE_PORT</key><string>4479</string>
  </dict>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
</dict>
</plist>

launchctl load ~/Library/LaunchAgents/local.oxe.plist

Do not point multiple devices at the same cache.db on a network filesystem. SQLite in WAL mode is explicitly documented as not safe over NFS or SMB:

"WAL does not work over a network filesystem. This is because WAL requires all processes to share a small amount of memory and processes on separate host machines obviously cannot share memory with each other." — sqlite.org/wal.html

Three patterns that work:

1. Run one oxe on your router or a home server, every device hits it. Simplest and recommended: http://router.lan:4479/search from everywhere.
2. Per-device cache with Litestream replication to S3/R2 if you want a mergeable, disaster-recoverable history.
3. One central writer, many readers via the HTTP API. Devices never touch SQLite directly; they POST to the central oxe.

Note that oxe does not require auth today: binding it to a shared interface means anyone on that network can search through you. Run it behind a reverse proxy with a bearer token, or on a trusted LAN only.

http://127.0.0.1:4479/ is fine most of the time. A real hostname with TLS is nicer for per-origin browser permissions, bookmarkable history pages, and MCP clients anywhere on your LAN.

With portless installed, pin a hostname to the port oxe already listens on (one-time; the alias survives restarts):

portless alias search 4479
curl https://search.localhost/health

Then register https://search.localhost/search?q=%s as a browser search engine. If you would rather let portless supervise the process, use OXE_PORT=4479 portless run --name search --app-port 4479 oxe (flags before the command; oxe reads OXE_PORT, not the generic PORT). To undo the alias: portless alias --remove search.

The live process exposes GET /health (liveness, version, cache rows), GET /cache/stats, GET /api/history, and GET /api/stats (searches, cache hit rate, latency, client split). With OXE_DEV=1 it emits structured JSON events on stdout.

Every search (HTTP, MCP, web UI) also writes a row to the search_log SQLite table: query text + hash, cache vs network, result count, latency in ms, and the client. Rows are pruned to OXE_SEARCH_LOG_RETENTION_DAYS (default 30).

For a shareable static report, build the dashboard:

oxe stats --db ~/.cache/oxe/cache.db --out ./dist/dashboard --days 30

Emits a single self-contained index.html (six inline-SVG panels, no JavaScript). Opens SQLite read-only, so it is safe against the live cache.

Context for AI coding assistants working with or against oxe:

• Project role: local web-search proxy. Exa-compatible POST /search, GET /search?q= with content negotiation, StreamableHTTP MCP at /mcp/.
• Key invariants: the SQLite cache is shared by HTTP and MCP; cache keys include query, page, and backend name. Empty results are cached with a short negative TTL; backend failures are NOT cached and return _error / _error_kind fields plus a non-2xx-tolerant payload check.
• Search errors vs empty results: _error_kind values include backend_error. Treat presence of _error as retryable; absence with empty results as genuinely empty.
• Click tracking: record agent-driven exploration via POST /click with source: "mcp"; read what the user already explored via the exa_user_history MCP tool before searching.
• Config: AI settings live in $OXE_CONFIG_DIR/config.toml under [ai]; PUT /settings is the supported write path (omit api_key to keep the stored value). String values support {env.NAME} interpolation.
• Testing: mise run test (Python), mise run check for lint/typecheck gates. Do not write tests that hit live DuckDuckGo.