Skip to main content
Setting up the managed Weave Router takes two things: a router key issued from your Weave organization, and a one-line installer on each engineer’s machine. Nothing is deployed on your side.

​
Prerequisites

  • An org admin to connect the organization and issue keys
  • Node.js 18 or later (for npx), plus bash on macOS and Linux. On Windows, Git Bash is used when present; without it, a built-in Node.js installer handles install and --uninstall only (no status line, hooks, or slash commands), and the other commands need Git Bash or WSL
  • jq for the Claude Code, opencode, and pi installs and their on/off toggles, which merge those clients’ JSON configs. If it isn’t on PATH, the installer downloads a checksum-verified copy to ~/.weave/bin on macOS and Linux (x86_64 or arm64) and Windows Git Bash (x86_64); elsewhere, install it yourself. Codex installs don’t need it
  • Either prepaid router credits, an active Claude or ChatGPT (Codex) subscription, or your own provider keys

​
Connect your organization

1

Open the router settings

Go to Organization settings → Weave Router in the Weave app. If your team doesn’t use the Weave analytics product, sign in at router.workweave.ai with GitHub, Google, or SSO and open Settings — it is the same configuration surface.
2

Connect

Click Get started. Weave provisions the router installation for your organization and issues your first API key. Only org admins can connect, issue, rotate, or revoke keys.
3

Copy the key and install command

The key (rk_…) and the ready-to-run install commands are shown once, at issuance. Store the key in your password manager or secret store. If you lose it, rotate the key and re-run the installer.
Issue one key per engineer (or per environment) rather than sharing one. Keys can carry an individual spend cap, and revoking a leaked key then only affects one person.

​
Install on a machine

Run the copied command, which has the key inlined. The generic forms are below — the installer prompts for the key, or reads WEAVE_ROUTER_KEY from the environment.
Add --scope project to configure the current repository instead of the machine. Add --non-interactive for CI and provisioning scripts (it requires WEAVE_ROUTER_KEY).
On npm 6 and older, the bundled npx mis-parses the package name. Use npx --package @weave-os/router -y -- weave-router --claude, or upgrade with npm i -g npm@latest.

​
What the installer writes

Patches ~/.claude/settings.json (or <repo>/.claude/settings.json for project scope) with the router base URL in ANTHROPIC_BASE_URL, your key in ANTHROPIC_CUSTOM_HEADERS, a status line, and Claude Code attribution. Your normal Anthropic login is untouched, so plan-covered turns still bill to your plan. Project scope keeps the key in the gitignored settings.local.json so the committed settings file carries no secret.
Adds a managed [model_providers.weave] block plus model_provider = "weave" to ~/.codex/config.toml, between begin/end markers. Everything outside the markers is preserved. Project scope writes a gitignored <repo>/.codex/config.toml; run Codex from the repo with CODEX_HOME=.codex codex.
Merges a provider.weave entry into ~/.config/opencode/opencode.json (or a gitignored <repo>/opencode.json). The installer makes weave/auto the active model and parks your previous default so off and uninstall can restore it; the router chooses the upstream model for each turn. Requires OpenCode 2. Your other providers and settings are left alone.
Registers a weave provider in ~/.pi/agent/models.json and installs the router extension, which adds the persistent route and savings display and the /fm and /ufm model-pin commands. Project scope writes a gitignored .pi/; launch with PI_CODING_AGENT_DIR=.pi pi.
Cursor has no config file the installer owns. In Settings → Models, add a model named weave-router, enable Override OpenAI Base URL and set it to https://router.workweave.ai/v1, then paste your rk_… key into the OpenAI API key field. Cursor support is early beta.
Claude Code Remote Control is unavailable while Claude Code uses Weave Router’s custom ANTHROPIC_BASE_URL: it requires direct access to the Anthropic API. Your claude.ai subscription login can remain configured for ordinary routed requests, but it does not remove this restriction. To use Remote Control, turn routing off for Claude Code, fully quit and reopen it, and use your eligible claude.ai sign-in. Turn routing back on and restart Claude Code to resume routed requests. See the scope-specific commands and troubleshooting.

​
Verify the install

Claude Code — start a session and issue one turn. The status line shows WEAVE ROUTER · response model: <model> · selected: <selected-model>, and adds · est. cost difference $X once the router can estimate the session’s cost difference. /router-status reports whether the client is on the router. Codex — confirm the # >>> weave-router managed (do not edit between markers) >>> block exists in your config, run a turn, and check that the provider is Weave Router. opencode — confirm provider.weave exists in your config and weave/auto is the selected model, then run a turn. The first routed response in a session, and any response where the serving model changes, also carries an in-band marker (✦ Weave Router → <model>) unless the client suppresses it. Every decision appears in the Router report within about an hour.

​
Roll out to your team

  • Per-machine install. Each engineer runs the installer once with their own key. That’s what makes per-engineer cost and spend limits work.
  • Per-repo install. --scope project in a shared repo configures the client for that repo; teammates still run the installer for their own key.
  • Set guardrails first. Configure spend limits and credits and your enabled models before a wide rollout, so nobody discovers a model or a bill you didn’t intend.

​
Turn it off, or uninstall

Toggle a client between the router and its provider without discarding the config:
Inside Claude Code, /router-off, /router-on, and /router-status do the same. Claude Code reads its router setting at launch, so quit and reopen it after a toggle. Codex and opencode pick it up on the next run. To remove the router config entirely:
The uninstaller removes only what the installer added. To cut off access for everyone at once, revoke the keys in router settings — the tokens stop working immediately.
Last modified on October 17, 2026