router

# Weave Router **One endpoint. Every model. Always the right one.** Weave Router is a drop-in proxy for Anthropic, OpenAI, and Gemini that automatically picks the best model for every request. Instead of using a vibes-based prompt, it uses a tiny on-box embedder with a cluster scorer derived from the [Avengers-Pro](https://arxiv.org/abs/2508.12631) research paper to route each request to the right model from your enabled providers. ## Key Features - **Routes per action** — A cluster scorer picks the right model for every upstream API request, routing per action rather than per turn. - **Speaks everyone's API** — Supports Anthropic Messages, OpenAI Chat Completions, and Gemini native APIs, including streaming, tools, and vision. - **Knows OSS too** — DeepSeek, Kimi, GLM, Qwen, Llama, and Mistral via OpenRouter or any OpenAI-compatible endpoint. - **BYOK by default** — Provider keys stay on your box, encrypted at rest. - **Observable** — OTLP traces out of the box, viewable in the Weave dashboard or any OTLP-compatible collector like Honeycomb, Datadog, or Grafana. ## Quickstart The fastest way to get started is with the hosted Weave Router: ```bash npx @weave-os/router ``` The installer asks which tool (Claude Code, Codex, opencode, or pi), walks you through scope (user vs. project), grabs a router key, and wires the right config file. Other flavors include: ```bash npx @weave-os/router --claude # skip the picker, Claude Code npx @weave-os/router --codex # skip the picker, OpenAI Codex CLI npx @weave-os/router --opencode # skip the picker, opencode npx @weave-os/router --pi # skip the picker, pi + Loom UI npx @weave-os/router --scope project # per-repo, commits settings.json npx @weave-os/router --local # self-hosted localhost:8080 npx @weave-os/router --base-url https://router.acme.internal npx @weave-os/router@0.1.0 # pin a version ``` Requires Node ≥ 18. Full flag reference is in [install/npm/README.md](install/npm/README.md). ## Self-Hosting To run the router and dashboard on your own box: ```bash # 1. Drop a provider key in. OpenRouter is the recommended baseline. echo "OPENROUTER_API_KEY=sk-or-v1-..." >> .env.local # 2. Set a dashboard password. echo "ROUTER_ADMIN_PASSWORD=replace-with-a-strong-password" >> .env.local # 3. Boot Postgres + router on :8080 and seed an rk_ key. make full-setup ``` The router is up at http://localhost:8080, the dashboard at http://localhost:8080/ui/, and your `rk_...` key prints in the logs. ### Example API Calls ```bash # Call it like Anthropic curl -sS http://localhost:8080/v1/messages \ -H "Authorization: Bearer rk_..." \ -d '{"model":"claude-sonnet-4-5","max_tokens":256, "messages":[{"role":"user","content":"hi"}]}' # ...or like OpenAI curl -sS http://localhost:8080/v1/chat/completions \ -H "Authorization: Bearer rk_..." \ -d '{"model":"gpt-4o-mini", "messages":[{"role":"user","content":"hi"}]}' # Peek at the routing decision without proxying curl -sS http://localhost:8080/v1/route -H "Authorization: Bearer rk_..." -d '...' ``` ## Architecture Only the grey boxes are off your machine. The router, the scorer, Postgres, and your provider keys all stay local; prompts go from the router straight to the provider you configured, never to Weave. ```mermaid flowchart LR client["Claude Code, Codex, opencode,<br/>pi, Cursor, your own app"] router["Router :8080<br/>/v1/messages · /v1/chat/completions<br/>/v1beta/models · /v1/route"] scorer["Cluster scorer<br/>in-process ONNX embedder"] hmm["HMM policy sidecar :8093<br/>optional, make up-hmm"] pg[("Postgres<br/>installations, rk_ keys,<br/>encrypted BYOK keys, usage")] ui["Dashboard /ui<br/>selfhosted mode only"] providers["Anthropic · OpenAI · Gemini<br/>OpenRouter and any<br/>OpenAI-compatible endpoint"] otel["Your OTLP collector<br/>Honeycomb, Datadog, Grafana"] client -->|"rk_… bearer token,<br/>streamed response back"| router router -->|"embed and score the action"| scorer router -.->|"ROUTER_DEFAULT_STRATEGY=hmm"| hmm router -->|"auth, config, usage"| pg pg --> ui router -->|"provider key from env or BYOK"| providers router -.->|"spans and usage logs"| otel ``` Multi-replica deployments also need Pub/Sub (`PUBSUB_*`) for cache invalidation; `docker compose` runs the emulator for you. ## Optional: HMM Policy Sidecar The default stack uses the in-process cluster scorer. To run the frozen HMM policy as a companion container, add a Google API key and use the opt-in target: ```bash echo 'GOOGLE_API_KEY=...' >> .env.local make up-hmm ``` This does not change the default strategy. See [sidecars/hmm/README.md](sidecars/hmm/README.md) for artifact verification, embedding compatibility, and explicit HMM selection. ## Tool Integration **Claude Code.** Run `make install-cc` to wire Claude Code at the local self-hosted router (also invoked automatically at the end of `make full-setup`). For the hosted router, use `npx @weave-os/router` above. **Codex** (OpenAI CLI). `npx @weave-os/router --codex` patches `~/.codex/config.toml` (or `<repo>/.codex/config.toml` with `--scope project`) with a managed `[model_providers.weave]` block and sets `model_provider = "weave"`. The provider preserves Codex's existing ChatGPT OAuth login while the router key rides in an `X-Weave-Router-Key` HTTP header. ## License Licensed under the Elastic License v2 (ELv2). --- *Built by [Weave](https://www.workweave.ai): The #1 engineering intelligence platform, loved by Robinhood, PostHog, Reducto, and hundreds of others.*