> ## Documentation Index
> Fetch the complete documentation index at: https://docs.weaveos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> One managed endpoint that picks the right model for every request from your coding agent

Weave Router is a hosted endpoint that sits between your coding agents and the model providers. Your agent sends every request to Weave, Weave picks the model that fits that specific request, and forwards it upstream. You get the same agent experience at a lower blended cost, with per-request cost and savings reporting in Weave.

This section documents the **managed** service at `https://router.workweave.ai`. Weave runs and operates it — you do not deploy anything, run Docker, or hold provider infrastructure. (The [open-source router](https://github.com/weave-os/router) is a separate, self-hosted distribution with its own setup instructions.)

<Note>
  Weave Router is not the [Claude Code plugin](/tutorials/weave-plugin-installation). The plugin is telemetry: it observes your Claude Code sessions and feeds Weave reports. The router changes which model serves each request. They are independent — you can run either or both.
</Note>

## Request flow

```mermaid theme={null}
flowchart LR
    agent["Coding agent<br/>Claude Code, Codex,<br/>opencode, pi, Cursor"]
    router["Weave Router<br/>router.workweave.ai"]
    gate{"Router key valid?<br/>Credits and<br/>spend limits OK?"}
    pick["Pick a model<br/>for this call"]
    provider["Anthropic, OpenAI,<br/>Google, and others"]
    refuse["401 for a bad key,<br/>402 for credits or a limit"]
    report["Router report<br/>cost, savings, model mix"]

    agent -->|"request + router key header"| router
    router --> gate
    gate -->|"no"| refuse
    refuse --> agent
    gate -->|"yes"| pick
    pick -->|"your subscription, your provider key,<br/>or Weave prepaid credits"| provider
    provider -->|"streamed response"| agent
    pick -.->|"decision and cost telemetry"| report
```

A subscription turn runs on plan capacity, not credits. The router either passes through the token your client sends or uses an [enrolled subscription](/router/subscription-accounts) (stored as an encrypted refresh token), trying yours first and a teammate's when sharing is on. Turns Weave serves from its own accounts draw down [prepaid credits](/router/billing) at upstream cost, and turns on your own provider keys draw down only Weave's platform fee.

## How it works

<Steps>
  <Step title="Your agent points at Weave">
    The installer rewrites your client config so requests go to `https://router.workweave.ai` instead of directly to Anthropic, OpenAI, or Google. Your Weave Router key rides in an `X-Weave-Router-Key` header, separate from your provider credentials.
  </Step>

  <Step title="Weave scores the request">
    Every LLM call is routed independently — in an agentic loop that means every tool call, not just the first prompt. The scorer weighs what the request needs against price, your quality-vs-price setting, your enabled models, session state, and cache warmth.
  </Step>

  <Step title="Weave forwards it upstream">
    The request goes to the selected model. If you are on a subscription (Claude or ChatGPT/Codex) your credentials pass through untouched so that turn bills to your plan. Otherwise the turn bills against your Weave Router credits or your own provider key.
  </Step>

  <Step title="You see the decision and the cost">
    The routed model is shown in your client (status line, in-band marker, or the pi route display) and every decision lands in the [Router report](/router/reporting) with cost and savings.
  </Step>
</Steps>

## What it changes

* **Cost.** Cheap requests (file reads, small edits, tool plumbing) stop running on your most expensive model. Hard requests still get the strong model — the router allows tier upgrades when a turn needs one.
* **Plan headroom.** With subscription routing on, plan-covered turns keep using your plan, and overflow goes to paid models instead of blocking your engineers at their limit.
* **Visibility.** Per-request model, cost, and savings, broken down by engineer and model.

## What stays the same

* Your agent, your prompts, your workflow. No forked CLI, no wrapper binary.
* Your provider subscriptions. Claude Code and Codex plan credentials pass through to the provider.
* Streaming, tool calls, caching, and the native request format of each client.

## Supported clients

| Client | How it connects |
| - | - |
| Claude Code | Installer patches `settings.json` with the router base URL and key |
| Codex CLI | Installer patches `~/.codex/config.toml` with a `weave` model provider |
| opencode | Installer merges a `provider.weave` entry into your opencode config |
| pi | Installer registers a `weave` provider plus the router extension |
| Cursor | Manual: override the OpenAI base URL in Cursor settings (early beta) |

Anything that speaks the Anthropic Messages, OpenAI Chat Completions, or Gemini `generateContent` API can point at the router directly.

## Where things live

| What you want | Where |
| - | - |
| Keys, install commands, models, billing, limits | [Organization settings → Weave Router](https://app.workweave.ai/organization/settings/weave-router) in the Weave app |
| The same settings without a full Weave seat | [router.workweave.ai/api-keys](https://router.workweave.ai/api-keys) |
| Cost, savings, and model-mix charts | The Router report in Weave, or [router.workweave.ai/dashboard](https://router.workweave.ai/dashboard) |

## Next steps

* [Get started](/router/getting-started) — create a key and install the router
* [Authentication](/router/authentication) — keys, subscriptions, and SSO
* [Billing and credits](/router/billing) — credits, spend limits, and BYOK
* [Models and routing](/router/models-and-routing) — control what the router picks
* [FAQ](/router/faq) — the questions customers ask most


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.