TokenBeaver sits in front of any OpenAI-compatible tool. Point your agent's base URL at the local gateway, keep your own key, and every request is slimmed before it reaches your provider — same requests, same answers, fewer tokens.
The gateway is local-first. Its base URL is always http://127.0.0.1:4505/v1 (port 4505 by default). Point any OpenAI-compatible agent at that URL and pass your own key — it flows straight through (BYOK) and is never stored. Both surfaces below drive the same gateway.
Then set your agent's base URL to http://127.0.0.1:4505/v1. Change the port with TOKENBEAVER_GATEWAY_PORT if 4505 is taken.
Command Palette → TokenBeaver: Copy Gateway Base URL, then paste it into your agent's settings. TokenBeaver: Agent Setup Instructions shows the per-agent steps, and TokenBeaver: Gateway Status confirms it's running.
The gateway forwards to one upstream provider. Precedence is env > config.json > default, and the default is openrouter. Provider changes are restart-required.
| Provider | Default upstream | Key | Notes |
|---|---|---|---|
openrouter | https://openrouter.ai/api/v1 | BYOK, header pass-through | Default |
openai | https://api.openai.com/v1 | BYOK | Also the internal fallback |
anthropic | https://api.anthropic.com/v1 | BYOK (x-api-key) | Native Messages API (/v1/messages) |
custom | none — must set an upstream | Depends on endpoint | Rejected / falls back if set without an upstream |
copilot | dynamic; https://api.individual.githubcopilot.com fallback | GitHub token, no API key | OpenAI-wire only — see Copilot |
The provider lives on the gateway, shared across surfaces via config.json. It is not a VS Code setting — there is no provider dropdown in VS Code settings. State it once and restart.
Dropdown order on the Settings page: openrouter, openai, anthropic, custom, copilot. Restart after changing.
Command Palette → TokenBeaver: Settings opens the same localhost Settings page and provider dropdown. There is no separate VS Code provider setting — engine settings live here so both surfaces stay in sync.
To point the gateway at any other OpenAI-compatible endpoint, set the provider to custom and give it an upstream base URL. A custom provider without an upstream is rejected or falls back — the upstream is required.
In VS Code, set the same two fields on the Settings page (TokenBeaver: Settings): provider custom + the upstream base URL. Restart to apply.
One gateway can serve an OpenAI-compatible agent and Claude Code at the same time. Set an Anthropic upstream alongside your main one: TOKENBEAVER_ANTHROPIC_UPSTREAM_BASE_URL routes /v1/messages to Anthropic, while /v1/chat/completions goes to your OpenAI-compatible provider.
The same two fields exist on the Settings page (upstreamBaseUrl and anthropicUpstreamBaseUrl). Now Cursor (or any OpenAI-wire tool) and Claude Code both point at http://127.0.0.1:4505/v1 and each reaches the right upstream.
Every tool below takes a base URL and an API key. Set the base URL to http://127.0.0.1:4505/v1 and paste your own provider key. For the full agent list see Integrations.
Settings → Models → enable a custom OpenAI base URL, set it to the gateway URL, and paste your key. Cursor then talks to your provider through TokenBeaver.
Set the API provider to "OpenAI Compatible", base URL to the gateway URL, and your key. Pick a model your upstream serves.
Choose the OpenAI-compatible provider, point the base URL at the gateway, and enter your key. Same wiring as Cline.
In Copilot's model settings, add an OpenAI-compatible endpoint with the gateway URL and your key. Full steps and the flat-rate caveat are on the Copilot page.
tokenbeaver-gateway, or TokenBeaver: Start Gateway) and confirm with --status / TokenBeaver: Gateway Status. The base URL is http://127.0.0.1:4505/v1 unless you changed TOKENBEAVER_GATEWAY_PORT.custom provider must also set an upstream base URL (TOKENBEAVER_UPSTREAM_BASE_URL or the Settings field). Custom without an upstream is rejected or falls back./v1/messages goes to the Anthropic upstream and /v1/chat/completions to your OpenAI-compatible one. If a tool lands on the wrong side, check which wire protocol it uses and which upstream URLs you set.env: badge when an environment variable is winning.Open a GitHub issue → · Questions? Support
Email [email protected] or visit the support page — a real developer will get back to you.