Weave Router

https://github.com/workweave/router
Admin
Weave Router is an open-source, high-performance proxy for Anthropic, OpenAI, and Gemini that...
Tokens:30,574
Snippets:468
Trust Score:7.9
Update:2 months ago
Show doc for...
Tokens:
Raw
### Quickstart Router Installation

Source: https://github.com/workweave/router/blob/main/README.md

Run the router directly using npx without requiring local cloning or Docker.

```bash
npx @workweave/router
```

--------------------------------

### Install via local shell script

Source: https://github.com/workweave/router/blob/main/install/README.md

Run the installation script directly from a repository clone.

```bash
./router/install/install.sh                    # prompts: target, then scope
./router/install/install.sh --claude           # skip picker, Claude Code
./router/install/install.sh --codex            # skip picker, Codex
./router/install/install.sh --opencode         # skip picker, opencode
./router/install/install.sh --scope project    # team install
```

--------------------------------

### Install with custom base URL

Source: https://github.com/workweave/router/blob/main/install/README.md

Point the installer to a custom router URL or development port.

```bash
# Internal deploy with seeded keys (will prompt for the bearer):
./router/install/install.sh --base-url https://router.your-company.internal

# Custom local port, dev mode:
./router/install/install.sh --base-url http://localhost:9000 --dev-mode
```

--------------------------------

### Self-Hosting Setup

Source: https://github.com/workweave/router/blob/main/README.md

Configure environment variables and initialize the stack using the provided Makefile.

```bash
# 1. Drop a provider key in. OpenRouter is the recommended baseline.
echo "OPENROUTER_API_KEY=sk-or-v1-..." >> .env.local

# 2. Boot Postgres + router on :8080 and seed an rk_ key.
make full-setup
```

--------------------------------

### Setup and Test Commands

Source: https://github.com/workweave/router/blob/main/CONTRIBUTING.md

Commands to initialize the development environment and execute the full test suite.

```bash
make full-setup
```

```bash
make check
```

--------------------------------

### GET /readyz

Source: https://github.com/workweave/router/blob/main/docs/POLICY_ROUTER_HARNESS.md

Checks if the artifact and roster are loaded and ready for routing.

```APIDOC
## GET /readyz

### Description
Indicates that the exact artifact and roster are loaded and routing can succeed.

### Method
GET

### Endpoint
/readyz
```

--------------------------------

### Setup self-hosted router with Docker

Source: https://github.com/workweave/router/blob/main/install/README.md

Boot the local stack and configure the router for local development.

```bash
cd router
make full-setup                 # boot the stack and seed a router key
make install-cc                 # → ./install/install.sh --claude --local
claude                          # routes through your local router
```

--------------------------------

### Conventional Commit Examples

Source: https://github.com/workweave/router/blob/main/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification.

```text
feat(proxy): add session pinning for multi-turn coherence
fix(auth): clear API key cache on installation deletion
refactor(translate): extract OpenAI envelope builder
docs: clarify ROUTER_ADMIN_PASSWORD requirement
```

--------------------------------

### Install Weave Router for pi

Source: https://github.com/workweave/router/blob/main/install/pi-router/README.md

Commands to install the Weave Router extension for pi, with an option for local routing.

```bash
WEAVE_ROUTER_KEY=rk_… npx --package @workweave/router -y -- weave-router --pi
WEAVE_ROUTER_KEY=rk_… npx --package @workweave/router -y -- weave-router --pi --local  # local router
```

--------------------------------

### Hot-reload Development Loop

Source: https://github.com/workweave/router/blob/main/CONTRIBUTING.md

Commands to initialize the local database and start the server with hot-reloading.

```bash
make db                                # start Postgres only (port 5433)
echo "DATABASE_URL=postgresql://router:router@localhost:5433/router?sslmode=disable" >> .env.local
make setup                             # init schema + migrate + seed an rk_ key
make dev                               # run the server with hot reload
```

--------------------------------

### Version-pinned installation

Source: https://github.com/workweave/router/blob/main/install/npm/README.md

Use a specific version of the router for reproducible environments.

```bash
npx @workweave/router@0.1.0 --claude --scope project
```

--------------------------------

### Install Weave Router via npx

Source: https://github.com/workweave/router/blob/main/install/README.md

Use npx to install the router for specific tools and scopes. Supports interactive mode or direct flags to skip prompts.

```bash
# Interactive: the installer asks Claude Code / Codex / opencode, then user vs. project
npx @workweave/router

# Skip the target picker:
npx @workweave/router --claude                     # Claude Code, user scope
npx @workweave/router --codex                      # Codex, user scope
npx @workweave/router --opencode                   # opencode, user scope

# Project scope — only when running inside this repo:
npx @workweave/router --claude   --scope project   # Claude Code
npx @workweave/router --codex    --scope project   # Codex
npx @workweave/router --opencode --scope project   # opencode
```

--------------------------------

### Configure local Codex for self-hosted router

Source: https://github.com/workweave/router/blob/main/install/README.md

Use the installation script with the --local flag to point Codex to a self-hosted router.

```bash
./router/install/install.sh --codex --local                    # user scope Codex
./router/install/install.sh --codex --local --scope project    # team scope Codex
```

--------------------------------

### API Interaction Examples

Source: https://github.com/workweave/router/blob/main/README.md

Interact with the router using standard Anthropic or OpenAI API formats, or query routing decisions directly.

```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 '...'
```

--------------------------------

### Embedder Configuration in metadata.yaml

Source: https://github.com/workweave/router/blob/main/internal/router/cluster/artifacts/README.md

Example of the embedder block configuration within a bundle's metadata.yaml file.

```yaml
embedder:
  model: jina-v2-base-code-int8   # or qwen3-embedding-0.6b-int8
  embed_dim: 768                  # 1024 for qwen3
  max_tokens: 256
```

--------------------------------

### Onboarding flow for a new teammate

Source: https://github.com/workweave/router/blob/main/install/README.md

Standard sequence of commands to clone a repository, initialize the router, and set the required environment variable for the target tool.

```bash
git clone <repo>
cd <repo>
npx @workweave/router --claude --scope project   # or --codex / --opencode
export WEAVE_ROUTER_KEY=rk_...                    # in shell rc / dotenv / 1Password
claude                                             # or `CODEX_HOME=.codex codex` / `opencode`
```

--------------------------------

### GET /capabilities

Source: https://github.com/workweave/router/blob/main/docs/POLICY_ROUTER_HARNESS.md

Returns the policy_router_v1 optional-feature declaration.

```APIDOC
## GET /capabilities

### Description
Returns the policy_router_v1 optional-feature declaration.

### Method
GET

### Endpoint
/capabilities

### Response
#### Success Response (200)
- **schema_version** (string) - The version of the policy router schema.
- **reports_outcomes** (boolean) - Whether the router reports outcomes.
- **reports_feedback** (boolean) - Whether the router reports feedback.
- **honors_preferred_models** (boolean) - Whether the router honors preferred models.
- **honors_quality_price_bias** (boolean) - Whether the router honors quality/price bias.
- **supports_debug_route_detail** (boolean) - Whether debug route details are supported.
- **supports_preview** (boolean) - Whether preview is supported.
- **supports_shadow** (boolean) - Whether shadow mode is supported.
- **authoritative_per_turn_selection** (boolean) - Whether selection is authoritative per turn.
```

--------------------------------

### GET /livez

Source: https://github.com/workweave/router/blob/main/docs/POLICY_ROUTER_HARNESS.md

Checks the liveness of the sidecar process.

```APIDOC
## GET /livez

### Description
Returns the liveness status of the sidecar process.

### Method
GET

### Endpoint
/livez
```

--------------------------------

### Build and Test Commands

Source: https://github.com/workweave/router/blob/main/CONTRIBUTING.md

Standard Makefile commands for project maintenance and verification.

```bash
make generate     # regenerate SQLC + statusline (no DB required)
make build        # typecheck the whole module
make test         # run all tests
make check        # generate + build + test (CI-equivalent)
```

--------------------------------

### Run the fixture recording script

Source: https://github.com/workweave/router/blob/main/scripts/record_provider_fixtures/README.md

Execute the script from the repository root with the necessary API keys and the RECORD environment variable set to 1.

```bash
RECORD=1 \
  OPENROUTER_API_KEY=… \
  OPENAI_API_KEY=… \
  GOOGLE_API_KEY=… \
  go run ./scripts/record_provider_fixtures
```

--------------------------------

### Uninstall Workweave Router

Source: https://github.com/workweave/router/blob/main/install/README.md

Commands to remove router configurations for different tools and scopes. This only removes keys or blocks added by the installer.

```bash
npx @workweave/router --uninstall                       # Claude Code, user scope
npx @workweave/router --uninstall --codex               # Codex, user scope
npx @workweave/router --uninstall --opencode            # opencode, user scope
npx @workweave/router --uninstall --scope project       # Claude Code, in the repo
npx @workweave/router --uninstall --codex --scope project
npx @workweave/router --uninstall --opencode --scope project
```

--------------------------------

### Execute Database Migrations

Source: https://github.com/workweave/router/blob/main/CONTRIBUTING.md

Commands to create, edit, and apply database migrations, followed by regenerating SQLC code.

```bash
make migrate-create NAME=add-xyz
$EDITOR db/migrations/<ts>_add-xyz.up.sql
$EDITOR db/migrations/<ts>_add-xyz.down.sql
make migrate-up
make generate     # regenerate SQLC after migration changes
```

--------------------------------

### Run Feedback Integration Check

Source: https://github.com/workweave/router/blob/main/scripts/feedback_integration_check/README.md

Executes the integration check script from the repository root using a specified database connection string.

```bash
ROUTER_TEST_DATABASE_URL="postgres://router:router@localhost:5432/router?search_path=router" \
    go run ./scripts/feedback_integration_check
```

--------------------------------

### Fetch Jina embedder assets for local development

Source: https://github.com/workweave/router/blob/main/docs/CONFIGURATION.md

Downloads the required ONNX model and tokenizer files for the Jina embedder and configures the local environment variable.

```bash
mkdir -p assets/jina-v2-base-code-int8
BASE="https://huggingface.co/jinaai/jina-embeddings-v2-base-code/resolve/516f4baf13dec4ddddda8631e019b5737c8bc250"
curl -L "$BASE/onnx/model_quantized.onnx" -o assets/jina-v2-base-code-int8/model.onnx
curl -L "$BASE/tokenizer.json" -o assets/jina-v2-base-code-int8/tokenizer.json
echo "ROUTER_ONNX_ASSETS_DIR=$(pwd)/assets" >> .env.local
```

--------------------------------

### Router CLI Configuration Flags

Source: https://github.com/workweave/router/blob/main/README.md

Various flags to customize the router installation, including specific tool integration, scoping, and base URL configuration.

```bash
npx @workweave/router --claude              # skip the picker, Claude Code
npx @workweave/router --codex               # skip the picker, OpenAI Codex CLI
npx @workweave/router --opencode            # skip the picker, opencode
npx @workweave/router --pi                  # skip the picker, pi + Loom UI
npx @workweave/router --scope project       # per-repo, commits settings.json (or .codex/ / opencode.json)
npx @workweave/router --local               # self-hosted localhost:8080
npx @workweave/router --base-url https://router.acme.internal
npx @workweave/router@0.1.0                 # pin a version
```

--------------------------------

### Regenerate goldens and review changes

Source: https://github.com/workweave/router/blob/main/scripts/record_provider_fixtures/README.md

Update the test goldens after recording new fixtures and inspect the resulting diff.

```bash
go test ./internal/proxy/ -run TestConformance -update
git diff internal/proxy/testdata/conformance
```

--------------------------------

### Self-Hosting HMM Policy

Source: https://github.com/workweave/router/blob/main/README.md

Optional configuration to run the frozen HMM policy as a companion container.

```bash
echo 'GOOGLE_API_KEY=...' >> .env.local
make up-hmm
```

--------------------------------

### Configure OpenAI-compatible embedding provider

Source: https://github.com/workweave/router/blob/main/sidecars/hmm/README.md

Environment variables required to point the sidecar to an external embedding proxy.

```bash
HMM_EMBEDDING_PROVIDER=openai-compatible
HMM_EMBEDDING_BASE_URL=https://embedding-proxy.example/v1
HMM_EMBEDDING_API_KEY=...
HMM_EMBEDDING_MODEL=google/gemini-embedding-2
```

--------------------------------

### Register Policy Sidecars via Environment Variables

Source: https://github.com/workweave/router/blob/main/docs/POLICY_ROUTER_HARNESS.md

Configure the router to recognize new policy sidecars by setting the required environment variables for endpoints, authentication, and timeouts.

```bash
export ROUTER_POLICY_SIDECARS='{"quality-v2":"https://quality-v2.internal"}'
export ROUTER_POLICY_SIDECAR_AUTH='{"quality-v2":"google-id-token"}'
export ROUTER_POLICY_SIDECAR_TIMEOUT_MS=3000
```

--------------------------------

### POST /v1beta/models/:action

Source: https://github.com/workweave/router/blob/main/README.md

Routes Gemini generateContent requests to the appropriate upstream provider.

```APIDOC
## POST /v1beta/models/:action

### Description
Routes Gemini generateContent requests to the appropriate upstream provider.

### Method
POST

### Endpoint
/v1beta/models/:action

### Parameters
#### Path Parameters
- **action** (string) - Required - The specific Gemini action to perform.
```

--------------------------------

### Enable Weave Router via CLI

Source: https://github.com/workweave/router/blob/main/install/commands/router-on.md

Executes the command to turn on the Weave Router for Claude Code. Requires a full restart of Claude Code after execution for the configuration to take effect.

```bash
npx @workweave/router on --claude{{SCOPE}}
```
Tokens:
Raw