> ## 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.

# Router FAQ

> Answers to the questions teams ask most before and during a Weave Router rollout

## General

<AccordionGroup>
  <Accordion icon="circle-question-mark" title="What is Weave Router, in one sentence?">
    A hosted endpoint your coding agents call instead of a model provider, which picks the best model for each individual request and forwards it upstream.
  </Accordion>

  <Accordion icon="git-compare" title="How is the router different from the Weave Claude Code plugin?">
    The [plugin](/tutorials/weave-plugin-installation) is telemetry — it observes Claude Code sessions and enriches Weave reports. The router changes which model serves each request. Different products, installed differently; you can run both. If a developer sees "Weave Router" in their session but you meant to install the plugin, they went through the wrong flow — see [troubleshooting](/router/troubleshooting).
  </Accordion>

  <Accordion icon="github" title="Is this the same thing as the open-source router repo?">
    The public repo is the self-hostable distribution: you run it, you supply provider keys, you operate the infrastructure. The managed service is hosted by Weave and runs Weave's production routing model, which is not the policy published in the repo. Benchmarks you run against the open-source policy will not match managed behavior — ask your Weave contact for current benchmark data.
  </Accordion>

  <Accordion icon="plug" title="Which clients are supported?">
    Claude Code, Codex CLI, opencode, and pi have one-line installers. Cursor works by overriding its OpenAI base URL (early beta). Anything speaking the Anthropic Messages, OpenAI Chat Completions, or Gemini `generateContent` API can call the router directly.
  </Accordion>

  <Accordion icon="monitor" title="Can I use Claude Code Remote Control with the router?">
    Remote Control requires direct access to the Anthropic API and is unavailable while Weave Router's custom base URL is active, even with a claude.ai subscription login. See [Remote Control troubleshooting](/router/troubleshooting#claude-code-remote-control) for the reversible routing toggle and restart instructions.
  </Accordion>

  <Accordion icon="user-plus" title="Do engineers need a Weave analytics seat?">
    No. Teams that only use the router can sign in at [router.workweave.ai](https://router.workweave.ai) for the dashboard and settings. If you also use Weave for engineering analytics, the router lives inside the same app.
  </Accordion>
</AccordionGroup>

## Setup and rollout

<AccordionGroup>
  <Accordion icon="key-round" title="How do engineers authenticate?">
    With a router key (`rk_…`) issued by an org admin and installed on their machine. The dashboard itself supports GitHub, Google, and SSO sign-in. Registering your own OIDC issuer or exchanging an identity-provider token for a router credential is not supported today — provision keys through your secret manager for VM and CI environments and set `WEAVE_ROUTER_KEY`.
  </Accordion>

  <Accordion icon="users" title="One shared key or one key per engineer?">
    One per engineer. Per-engineer keys give you per-key spend caps, per-engineer cost reporting, and the ability to revoke one person without disrupting everyone.
  </Accordion>

  <Accordion icon="folder-git-2" title="Can we install per repository instead of per machine?">
    Yes — `--scope project` writes the config into the repo. Each teammate still runs the installer once for their own key; the router key is never committed.
  </Accordion>

  <Accordion icon="undo" title="How do we back out?">
    `npx @weave-os/router off --claude` returns a client to its provider while keeping the config, and `--uninstall` removes the config entirely. Revoking keys in settings cuts off access for everyone immediately.
  </Accordion>

  <Accordion icon="clipboard-check" title="What does a good proof of concept look like?">
    Pick a team, issue per-engineer keys, set a per-engineer spend limit and your approved model list up front, and run normal work for a couple of weeks. Compare the Router report's cost and savings against the same period before the install, and use `/router-feedback` whenever a decision looks wrong so Weave can tune it. Talk to your Weave contact before you start — they will help size credits and baseline the comparison.
  </Accordion>
</AccordionGroup>

## Billing

<AccordionGroup>
  <Accordion icon="credit-card" title="Does installing the router put me on per-API billing?">
    No. The `rk_…` key is not a provider API key; it identifies you to Weave and travels in its own header. Your Claude or ChatGPT subscription credentials pass through and keep paying for plan-covered turns. If you end up on per-API billing, check that `ANTHROPIC_API_KEY` is not set in your environment — Claude Code prefers it over your `CLAUDE_CODE_OAUTH_TOKEN`.
  </Accordion>

  <Accordion icon="wallet" title="Why isn't our credit balance going down?">
    Because those turns are running on your subscription, which costs no credits. That is expected. Switch subscription routing to **Use prepaid credits only** if you want to measure the workload as if the subscription weren't there.
  </Accordion>

  <Accordion icon="receipt" title="What exactly do credits pay for?">
    The upstream cost of turns Weave serves through its own provider accounts. Weave's margin is charged on top-up (5.5%, minimum \$0.80) rather than per call. Self-serve top-ups run from \$5 to \$10,000; larger commitments and invoicing go through your Weave contact.
  </Accordion>

  <Accordion icon="key" title="Can we use our own provider keys?">
    Yes. Add them under **Billing & spend → Your provider keys**. Inference then bills your provider account and Weave debits a 5% platform fee from your credit balance, so a bring-your-own-keys (BYOK) org still needs a funded balance.
  </Accordion>

  <Accordion icon="server" title="Can the router use our own inference endpoints?">
    Yes, per provider key. Add the key under **Billing & spend → Your provider keys** and set **Advanced → Custom endpoint** to your own deployment's base URL — see [custom endpoints](/router/billing#custom-endpoints). The endpoint has to be an HTTPS address Weave can reach; for anything private, talk to your Weave contact.
  </Accordion>

  <Accordion icon="split" title="Can each sandbox or agent run bill to its own capped upstream key?">
    Not per upstream key. The equivalent control today is per-key spend caps and per-engineer monthly limits on Weave Router keys, which cap spend per key rather than per provider token.
  </Accordion>

  <Accordion icon="bell" title="Can we get alerts at spend thresholds?">
    Spend limits are hard stops on paid spend — requests are refused at the cap rather than alerting first. If you want notifications before a threshold, ask your Weave contact; it isn't self-serve yet.
  </Accordion>
</AccordionGroup>

## Routing behavior

<AccordionGroup>
  <Accordion icon="repeat" title="Is routing per prompt, or per request?">
    Per request. In an agentic loop that means every tool call, and subagents — which carry their own context — are routed independently too.
  </Accordion>

  <Accordion icon="arrow-up" title="Will the router upgrade to a more expensive model on its own?">
    Yes. When a turn needs a stronger model, the router moves up a tier regardless of the extra cost. The quality-versus-price dial changes how eagerly it does so.
  </Accordion>

  <Accordion icon="list-ordered" title="Can we set a strict model priority order?">
    No. Routing is scored per request rather than resolved down a fixed ladder, so there is no hard promote that locks a model out. You can bias the router toward specific models with **Preferred models** or exclude models entirely.
  </Accordion>

  <Accordion icon="database" title="What happens to the prompt cache when the model changes?">
    Switching evicts the provider-side cache, so the router prices that eviction into the decision and stays on the current model when switching wouldn't pay off. Anthropic's cache is modelled at a one-hour time to live (TTL), other providers at five minutes. The router does not do proactive cache management — no keep-alive pings, pattern-based warming, or scheduled refreshes.
  </Accordion>

  <Accordion icon="gauge" title="What does the context indicator measure?">
    **Context 58%** comes from Claude Code's native usage report and matching window. **last Router ctx est. \~72k/128k** is an approximate per-request estimate and the served model's window, not a client percentage. Codex shows this estimate in its terminal title; its current hooks do not expose native context usage or an inline status bar. Missing or stale snapshots are omitted. A route change does not itself compact history; `/compact` belongs to Claude Code.
  </Accordion>

  <Accordion icon="scroll" title="What if my context is larger than the target model's window?">
    The router estimates each request and filters models using provider-specific windows plus an output reserve. If that conservative estimate excludes every model, the widest eligible candidates remain available for the provider to decide actual fit. The client handles compaction when a genuine overflow is returned. See [context indicators](/router/models-and-routing#context-indicators) for the difference between client usage and a Router estimate.
  </Accordion>

  <Accordion icon="pin" title="Can I force one model for a session?">
    Yes — `/force-model <model-id>` in Claude Code (`/fm` in pi), cleared with `/unforce-model`. Programmatic clients can send the `x-weave-force-model` header.
  </Accordion>

  <Accordion icon="file-check" title="Can we require a written justification before an expensive model is used?">
    No. The routing decision is a scored, model-driven choice rather than a rule with a written reason attached, so there is nothing to gate on. Use model exclusions, preferred models, and spend limits for control, and the Router report for after-the-fact audit.
  </Accordion>

  <Accordion icon="calendar-plus" title="A model just launched — when will the router use it?">
    Weave adds models to the roster shortly after release, and new entries are enabled by default. If a model you need is missing, ask Weave. If you keep an approved-model allowlist, re-check the model list after major releases.
  </Accordion>
</AccordionGroup>

## Reporting and visibility

<AccordionGroup>
  <Accordion icon="eye" title="How do I see which model served a given turn?">
    Live, in the client: the in-band `✦ Weave Router → <model>` marker and, in Claude Code, the status line. Historically: the [Router report](/router/reporting), or the [analytics export](/router/analytics-export) for request-by-request rows.
  </Accordion>

  <Accordion icon="calculator" title="How is “cost saved” calculated?">
    The same tokens are priced on the model your agent requested and on the model that actually served the turn; the difference is the saving. It is not a comparison against another vendor or tool, and it does not account for a cheaper model needing more turns.
  </Accordion>

  <Accordion icon="user-round-search" title="Can we get per-engineer and per-model cost?">
    Yes — the Router report breaks spend down by engineer, model, and date, and the charts support drilldown. The `router_cost` metric is also available through the [Weave MCP server](/integrations/mcp).
  </Accordion>

  <Accordion icon="timer" title="Is there a lag in spend numbers?">
    Normally under an hour.
  </Accordion>
</AccordionGroup>

## Security and data

<AccordionGroup>
  <Accordion icon="lock" title="What does Weave see?">
    The router receives each request in order to route and forward it, along with routing metadata such as model, token counts, cost, and session ID. For data handling, retention, and data processing agreement (DPA) specifics, contact [support@workweave.ai](mailto:support@workweave.ai).
  </Accordion>

  <Accordion icon="shield" title="How are provider keys stored?">
    Encrypted at rest and decrypted only to sign upstream calls. Only org admins can view or change them.
  </Accordion>

  <Accordion icon="user-cog" title="Who can change router settings?">
    Org admins issue keys, manage credits and limits, and change models and routing. Other members see the settings read-only.
  </Accordion>

  <Accordion icon="building" title="Can we self-host instead?">
    The open-source distribution is self-hostable, but it is a different deployment with its own operational burden and does not run Weave's production routing model. Talk to your Weave contact about which fits your requirements.
  </Accordion>
</AccordionGroup>


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