Overlord

A self-hosted AI agent orchestrator. Bring your own model.

npx overlord-ai        # → http://localhost:3131

One head Director model plans a task, calls MCP tools, and delegates subtasks to worker models — in parallel — running on any model you point it at. Attach any MCP server from the official registry in one click (npx for npm, uvx for Python, or remote HTTP). Any OpenAI-compatible provider works: Anthropic, OpenAI, OpenRouter, Groq, xAI, DeepSeek, local models via Ollama, or any endpoint you add yourself.

Add a demo GIF here — see LAUNCH.md for what to record and the launch copy.

Why Overlord (vs agent IDEs like Antigravity)

• No quotas, no lockouts — bring your own keys, endpoints, or local models. Nobody can throttle you; switch providers mid-conversation.
• Not an IDE — a universal orchestrator: any MCP tool, any domain, not just code.
• Remote control — expose on LAN and drive it from your phone. An IDE can't leave the desk.
• Transparent cost — live token meter and a hard budget cap per run, not opaque "credits".
• Yours — 3 source files, self-hosted, state in one JSON file. No telemetry.

Run

Desktop app — native macOS window via Tauri (system WebView, no Chromium):

npm install
npm run desktop        # dev: builds the sidecar + launches the app
npm run desktop:build  # builds Overlord.app + a .dmg installer

Needs the Rust toolchain (rustup) and Xcode Command Line Tools. The Node server is bundled as a self-contained sidecar binary (Node SEA) — the app needs no system Node.

Web / server mode (same app in your browser, no Rust needed):

npm start          # → http://localhost:3131

Docker: docker build -t overlord . && docker run -p 3131:3131 -v overlord-state:/app overlord (the token auth gate protects all non-localhost requests; grab the token from the container's .env).

Develop

npm test           # node --test suite (no framework)

CI runs the suite on Node 20 + 22 via GitHub Actions.

Phone: enable "Expose on local network" in Settings, open the tokenized URL on your phone, then "Add to Home Screen" — Overlord installs as an app (PWA).

VS Code: see vscode-extension/ for a thin panel extension — you keep real VS Code and the real Marketplace.

Chats, attached MCP servers, and settings persist in state.json and survive restarts (servers reattach automatically on boot).

Sign in vs API keys

Two ways to connect a model, your choice:

• Sign in with OpenRouter (Settings → "Sign in with OpenRouter"): OAuth login, no key to paste. Uses your own OpenRouter credits and fronts Claude, GPT, Gemini, Llama and more — full control, and nothing routed through the app owner.
• Paste an API key in ⚙︎ Settings (saved to .env), or set env vars before starting: ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, GROQ_API_KEY, XAI_API_KEY, DEEPSEEK_API_KEY. Ollama needs no key — just run it.

Note: a ChatGPT Plus / Claude Pro subscription is separate from those APIs and can't be used by third-party apps — so Overlord doesn't ask for those logins. OpenRouter sign-in is the sanctioned "use your plan without a key" path.

Custom providers

Settings → Custom providers: add any OpenAI-compatible endpoint by name + base URL (+ optional key) — Gemini, DeepSeek, Mistral, Together, LM Studio, vLLM, anything. Then use it as <name>/<model>. Keyless local endpoints work (no auth header sent).

Extras

• Custom / CLI attach: any stdio MCP command (npx -y pkg, uvx pkg, your own binary) or a streamable-http URL.
• Sandbox (macOS): attach dialogs default to a checked "🛡 Sandbox" option that runs stdio servers under sandbox-exec, blocking file writes outside temp/caches (no dotfile tampering, no persistence). Reads are not blocked — this stops tampering, not exfiltration. Not available outside macOS.
• HTTPS on LAN: when you expose Overlord on your local network, it also opens an HTTPS listener one port up (e.g. :3132) with a self-signed cert generated on first use. Accept the browser's self-signed warning once — it encrypts your token in transit on the shared network.
• Shell tool: Settings has an off-by-default toggle that gives the director a run_command tool on your machine. Enable it knowingly.
• Local models: a big model that doesn't fit in RAM crashes Ollama's runner and yields empty responses — Overlord surfaces that as an error. Keep a small tool-capable model (e.g. qwen3:1.7b) for grunt work.

Model ids

provider/model, e.g. anthropic/claude-opus-4-8, openai/gpt-5.2, ollama/qwen3-coder:30b, openrouter/deepseek/deepseek-chat.

• Director: receives your message, plans, calls tools, reviews.
• Worker: gets subtasks via the director's delegate tool. The director may also override the model per task.
• Token budget: hard cap per run; the director is told to wrap up when hit.

⚠️ Security

Attaching an npm MCP server runs third-party code on your machine (npx -y <pkg>). The confirm dialog shows the exact command — only attach servers you trust.