Switchboard

Self-hosted AI gateway & model router. One OpenAI/Anthropic-compatible API for every model provider you use — with routing policies, per-key quotas, multi-tenant teams, usage analytics and a built-in model playground.

English | 中文文档

Why Switchboard

• Your keys stay on your machine. Self-hosted BYOK gateway: provider keys are AES-256-GCM encrypted at rest, business API keys are stored hashed, and prompts/responses are never written to logs.
• Routing, not just proxying. Six strategies — fixed, failover, weighted, latency-first, keyword rules and cost-first — with circuit breaking, timeouts and model-level fallback across providers.
• A real console, not a CLI puzzle. Providers, models, policies, playground, people, audit and pricing in one web UI; also ships as a macOS desktop app with zero Docker/Node requirements.
• Small and auditable. A single Node.js process with only two runtime dependencies (ws, marked). No message queue, no heavyweight framework, no telemetry. Full source is reviewable in an afternoon.

Quick start (5 minutes)

Requirements: Docker + Compose, and Node.js ≥ 22.18 (only used to generate the initial .env).

git clone https://github.com/chensl139-ok/switchboard-ai-router.git
cd switchboard-ai-router
npm run setup                 # generates ADMIN_TOKEN / GATEWAY_TOKEN once, never overwrites
docker compose up -d --build

Open http://127.0.0.1:3100, enter the ADMIN_TOKEN from .env and create the owner account. Then:

1. Providers & Models — add an upstream base URL + API key, fetch its model list, enable the models you want to expose.
2. Routing — pick the default provider, candidate order, strategy and attempt budget. Route preview is computed locally and never calls upstreams.
3. Model Lab — test a call, compare 2–4 models side by side, run image/audio/video tasks.
4. API Keys — issue a business key with expiry and quota for your applications.

Call it like any OpenAI-compatible endpoint:

curl http://127.0.0.1:3100/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_BUSINESS_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"model":"auto","messages":[{"role":"user","content":"hello"}]}'

Responses carry x-router-provider, x-router-model, x-router-protocol, x-router-attempt headers so you always know which model actually answered. Point any OpenAI-compatible client (Cherry Studio, NextChat, LobeChat, …) at http://127.0.0.1:3100/v1 with your business key.

No Docker? npm ci && npm run setup && npm start. Prefer not to build? Pull the multi-arch image from GHCR. On Apple Silicon Macs there is also a zero-dependency desktop app.

How it works

  Cherry Studio · Claude Code · curl · your app · your agents
                    │   one base_url + one API key
                    ▼
  ┌──────────────────────── Switchboard ────────────────────────┐
  │  auth · tenants · API-key quotas · rate limits · audit      │
  │  ─────────────────────────────────────────────────────────  │
  │  router · fixed / failover / weighted / latency / rules /   │
  │           cost     (+ circuit breaking, timeouts)           │
  │  ─────────────────────────────────────────────────────────  │
  │  protocols · OpenAI Chat / Responses / Completions          │
  │              Anthropic Messages · SSE · WebSocket           │
  │              media: image · audio · video · embed · rerank  │
  └────┬──────────┬──────────┬──────────┬───────────┬───────────┘
       ▼          ▼          ▼          ▼           ▼
   DeepSeek    OpenAI    Anthropic    Gemini     Qwen · OpenRouter
                                        · any OpenAI/Anthropic-compatible upstream

Feature map

Comparison

Snapshot October 2026 — check each project's latest docs, and please PR corrections.

When Switchboard is not the right pick: you need 100+ exotic providers out of the box (LiteLLM), you run a public key-reselling storefront with redemption codes (one-api / new-api), or you want a personal CLI shim for one coding agent (claude-code-router). Switchboard is built for individuals and teams who self-host one governed gateway for many providers.

Deployment & security notes

• Single-instance by design: config in files, usage in SQLite, rate limiting in-process. Never share one data/ directory between processes; put it behind an HTTPS reverse proxy and back it up regularly (including master.key).
• SSRF guard: non-HTTPS upstreams and private/reserved hosts are refused by default; allow-list explicitly if you must.
• Hardened Compose profile: read-only rootfs, no-new-privileges, tmpfs /tmp, health checks, graceful shutdown.
• Pre-built linux/amd64 + linux/arm64 images on GHCR, tagged 2.1.x / 2.1 / latest; releases ship offline OCI tarballs with SHA256SUMS.

Full details: TENANCY.md (roles & Feishu/Lark SSO), API.md (endpoints, media APIs, SDK notes), ARCHITECTURE.md (module boundaries), CHANGELOG.md. Some deep-dive docs are currently in Chinese — translations are very welcome.

Development

npm ci
npm run check    # syntax, TypeScript/Vue types, web build
npm test         # 170+ automated tests
npm start        # build web assets and serve locally

Push a v* tag to cut a release: CI runs checks and tests, builds multi-arch GHCR images, and generates release notes with offline bundles.

Disclaimer

Switchboard is a neutral routing tool. You are responsible for complying with each model provider's terms of service and applicable laws/regulations, and you must not use this project to offer AI services to the public without authorization.

Star history

If Switchboard saves you a deployment, a debugging session or a surprise bill — a ⭐ is the best fuel for the next release.

License

MIT © 2026 chensl139-ok