Weave Router is a proxy that selects a model for each API request. It works with Anthropic, OpenAI, and Gemini APIs, so you can use it with coding tools or your own application. You can use the hosted router or run it yourself with your own provider keys. For the best experience, use the managed router hosted by Weave.
The router uses an HMM classifier policy to choose from enabled models. It supports streaming, tool calls, and vision.
For the hosted router, run the installer and follow the setup prompts:
npx @weave-os/routerYou'll need Node 18 or later. The hosted setup page can help you get a router key; you can also create one in the Weave dashboard under Settings → API keys. To choose a tool directly, use one of these commands:
npx @weave-os/router --claude
npx @weave-os/router --codex
npx @weave-os/router --copilot
npx @weave-os/router --opencode
npx @weave-os/router --piThe installer configures your selected tool to use Weave. For Copilot, it adds
Weave Router to the model picker; you can also start it with
copilot --model weave/auto.
For example, to switch Codex back to its previous provider, run
npx @weave-os/router off --codex. Use on --codex to switch back to Weave,
or --uninstall --codex to remove the configuration. See the installation guide for
what changes for each tool, project-level setup, and all available options.
For client-specific setup, connection checks, switching back, and uninstall, see the Router quickstart, Claude Code guide, and Codex CLI guide.
You'll need Docker, Go 1.26 or later, a provider API key, and a local checkout. For example, with an OpenRouter key:
git clone https://github.com/weave-os/router.git
cd router
echo 'OPENROUTER_API_KEY=sk-or-v1-...' >> .env.local
echo 'ROUTER_ADMIN_PASSWORD=replace-with-a-strong-password' >> .env.local
make full-setupThis starts the router and Postgres, creates a router key, and offers to set up
Claude Code. The router listens at http://localhost:8080 and the dashboard is
at http://localhost:8080/ui/. The router key (rk_...) is printed during
setup; use it to authenticate clients. Your provider key is separate and stays in
.env.local. Without an admin password, inference still works but dashboard
administration is disabled.
To connect another supported tool to the local router, add --local to its
installer command, for example:
npx @weave-os/router --codex --localCursor routes its Agent and Ask chats through the router. Cursor calls the base
URL from its own servers, not from your machine, so a localhost router is
unreachable: use the hosted router or a publicly reachable self-hosted URL. In
Cursor, open Settings → Models, turn on OpenAI API Key with your rk_...
router key, set Override OpenAI Base URL to <base-url>/v1, and add a custom
model named weave-auto (the router rejects other weave- names). Tab
completion and Apply stay on Cursor's own models, and BYOK needs a paid Cursor
seat.
The self-hosted router sends prompts to your configured provider. It also supports OpenTelemetry for tracing. For configuration, deployment details, and other provider options, see the configuration reference.
The optional self-hosted HMM is a barebones, frozen version of the policy. It
doesn't include the managed service's training, online learning, or registry.
For the best experience, use the Weave-managed router. The
self-hosted stack defaults to it (hmm_embedding). The local compose stack
boots on a stub classifier (smoke/hmmstub) that puts every turn in one
routing group; make up-hmm swaps in the real sidecar. See the
HMM guide for setup.
The router, HMM policy sidecar, database, and dashboard run locally. Requests go from the router to your configured model provider; you can also send traces to an OpenTelemetry collector. The HMM sidecar uses a compatible embedding service; its default configuration calls Google's embedding API.
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"]
hmm["HMM policy sidecar :8093<br/>stub by default, 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 -->|"classify the turn"| hmm
router -->|"auth, config, usage"| pg
pg --> ui
router -->|"provider key from env or BYOK"| providers
router -.->|"spans and usage logs"| otel
classDef external fill:#f4f4f5,stroke:#a1a1aa,color:#3f3f46
class providers,otel external
Multi-replica deployments also need Pub/Sub for cache invalidation; Docker Compose runs an emulator locally.
The router accepts Anthropic Messages (/v1/messages), OpenAI Chat Completions
(/v1/chat/completions), and Gemini requests (/v1beta/models/:action). To
inspect a routing decision without sending a request to a model, use
POST /v1/route. The endpoint reference covers health
checks, response costs, and the other endpoints.
For example, using the local router:
curl http://localhost:8080/v1/chat/completions \
-H 'Authorization: Bearer rk_...' \
-H 'Content-Type: application/json' \
-d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hi"}]}'See the configuration reference for router settings, the analytics guide for exporting routing decisions, and the session cost guide for usage and savings.
For the rest of the documentation, including routing terminology and policy integration, see the documentation index.
See CONTRIBUTING.md for development setup and tests. The architecture guide describes the package layout and the benchmark guide covers the evaluation harness.
Apache License 2.0. See NOTICE and
THIRD_PARTY.md for attribution and third-party licenses.
The Apache-2.0 release line begins with router-v0.2.24; earlier releases
retain the licenses they shipped with.