RelayPlane CLI
A local proxy between AI agents and model providers that prices every run as it happens and cuts off spend above your cap
- 212 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Every agent request passes through the proxy together with keys and prompt text, so a failure or compromise of it exposes them
- Routing swaps the model for a cheaper one by default and can quietly lower the agent's results
- The kill switch and caps return 429 and cut off running jobs
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/relayplaneDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Every agent request passes through the proxy together with keys and prompt text, so a failure or compromise of it exposes them
- Routing swaps the model for a cheaper one by default and can quietly lower the agent's results
- The kill switch and caps return 429 and cut off running jobs
This is third-party code. Review the repository files before installing.
What it does
RelayPlane is the npm package `@relayplane/proxy`. It runs on your machine and replaces the base URL of the Anthropic or OpenAI API. Each request is priced against a rate card and rolled up by run, agent and model. Totals show on a local dashboard at `http://localhost:4100` and in the terminal through `relayplane watch`. The agent's code stays untouched. Spend controls sit on top. Caps can be set per day, hour, request, session or single run, and they can block, downgrade to a cheaper model or just warn. A kill command halts all routed traffic. Optional detectors spot loops and velocity spikes. A run can be tagged with the `X-RelayPlane-Run` and `X-RelayPlane-Agent` headers, and `relayplane run --label nightly-backfill -- ./orchestrate.sh` wraps any script. Complexity routing sends simple requests to cheap models and hard ones to strong models by default. One request can skip it with the `X-RelayPlane-Bypass: true` header. On 429, 503 and 529 responses the proxy fails over to the next provider when keys for two or more are set: Anthropic, OpenAI, Google Gemini, xAI, OpenRouter or local Ollama.
Who it is for. People who run several agents or fan-out jobs on Claude Code and cannot tell which run ate the budget.
Good fit when
- An overnight agent run looped and the API bill grew with no warning
- You need a cost table by agent and by run labels such as `nightly-backfill`
- Every Claude Code run should hit a spend ceiling without stopping the other jobs
- You are testing a cheaper model for the heaviest complexity tier and want to swap it with one config line
- One provider answers 429 or 503 and the run has to move to a backup key
Not a fit when
- You need a cloud gateway for a platform team with per-user budgets: the project targets one machine, and LiteLLM fits that case better
- You need the exact sum from the provider's invoice: dashboard figures come from list prices and can differ from the real bill
- The agent does not let you change the API base URL, so it cannot be pointed at a local port
- A one-off terminal report from Claude Code logs is enough: `ccusage` is simpler
Example request
Install RelayPlane, point Claude Code at the local proxy and set a per-run spend cap of 5 dollarsLimitations
- All amounts are computed from list prices and show a notional cost of the traffic. The provider's invoice may differ.
- Complexity routing is on by default and sends simple requests to cheaper models even when the agent named an expensive one. To pin a model, use the `X-RelayPlane-Bypass: true` header or the `neverDowngrade` policy.
- Failover to another provider currently works for non-streaming responses; streaming is listed as a planned follow-up.
- The Osmosis mesh (anonymized routing signals) and telemetry are off by default and are enabled by `relayplane mesh on` and settings.
How to disable. Stop the proxy and remove `ANTHROPIC_BASE_URL=http://localhost:4100` from the environment or from `.claude/settings.json`: the agent goes straight to the provider again. The package is removed with `npm uninstall -g @relayplane/proxy`. Cost history sits in a local SQLite database and goes away with the settings directory.
FAQ
How do I connect RelayPlane to Claude Code?
Install the package and start the proxy: `npm install -g @relayplane/proxy`, then `relayplane start`. After that run `export ANTHROPIC_BASE_URL=http://localhost:4100` and start `claude`. The dashboard opens at `http://localhost:4100`.
How does RelayPlane differ from claude-code-router and LiteLLM?
RelayPlane runs locally and adds per-run cost tracking, caps and an emergency stop. In the README comparison, claude-code-router estimates cost per request, while LiteLLM is built for platform-team budgets.
How do I cap the spend of one run?
Add the `X-RelayPlane-Run-Cap-Usd` header with an amount in dollars. The run that goes over gets a 429 response while other jobs keep working.
Does my data go to third-party services?
By default no. The proxy forwards your own keys to the provider, traffic stays as it is until you turn routing on, and per-request telemetry is off. The anonymized signal exchange is enabled separately with `relayplane mesh on`.
Which providers does RelayPlane support?
Native forwarding for Anthropic, OpenAI, Google Gemini, xAI, OpenRouter and local Ollama behind one base URL. Failover switches on automatically when keys for two or more providers are set.
Discussion
No questions or reviews yet.
Related
CLI toolsA self-hosted gateway for multiple LLM keys and providers: rotation, failover, request logs and usage accounting
A local telemetry collector for AI coding agents: tokens, sessions and tool calls in one OpenTelemetry-style event schema
A local Rust proxy that compresses the model API requests of Claude Code, Codex and Cursor so you pay for fewer tokens
Local proxy between Claude Code and Anthropic that fixes prompt-cache misses, stabilizes the request prefix and shows quota use in the status line
The CLI starts a language-model proxy and a request tracking service for debugging applications across model providers.
Agentgateway
agentgateway
A proxy for agentic traffic: routes and secures connections to MCP servers, LLMs, and other agents over A2A
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| RelayPlane (this card) | no | 212 | |
| Claude Code Router | no | 38,020 | a router for Claude Code requests between models, while RelayPlane adds per-run cost tracking, caps and a kill switch |
| ccusage | no | 19,337 | after-the-fact reports from logs, while RelayPlane prices live and can stop spend |
README in short
The page shows how to install the proxy in 30 seconds and lists its features: cost tracking, routing, caps, kill switch, anomaly detection and provider failover. It then covers run labels via headers, a comparison with other proxies and links to the docs.