One endpoint.
Every provider.
No single point of failure.
Automatic failover across providers, hard budget caps you can't blow through, and a full record of every call, on infrastructure you run.
Budget gate
Legs, in order
- openai-primary openai-compat 429 · rate_limited
- anthropic-main anthropic-messages streaming
- bedrock-usw2 bedrock-converse standby
Six things an LLM edge has to get right
Every one of these is a decision you write down in config, not a heuristic you inherit.
-
Candidate chains
A route is an ordered list of providers. When a leg fails, switchback classifies the failure and moves to the next one only for the classes you named inadvanceOn. Anything you did not name surfaces to the caller. -
Budget caps
Dollar and token caps, global or per-upstream or per-route. The router reserves against every cap before it dispatches: a request that cannot fit gets a402and no provider is ever contacted. It settles from real usage afterwards, out of memory, a file, or Redis for a fleet. -
Credential isolation
Every upstream resolves its own key from its own environment variable, and the handle is bound to that upstream: using one provider's key for another throws instead of dispatching. Keys never leave the host you run this on. -
Five upstream dialects
One request shape goes in. switchback builds each upstream's native wire format, parses its native stream, and normalizes both back, so a chain can cross vendors mid-failover. Params a dialect cannot express are dropped or clamped and named in the request report; a few, liketop_k, are dropped without a note, and Providers lists them. -
OpenAI-shaped surface
Your clients keep speaking OpenAI. Point them at/v1and nothing else changes. Only the paths switchback implements are served: every other path is a 404, so nothing unknown is ever proxied through to a provider. -
Operator surface
/healthand/readyfor your orchestrator,/metricsfor Prometheus,/budgetfor spend against caps, and/route/reportsfor the per-request trace: which providers were tried, why each was abandoned, what it cost. Reports are redacted before they are stored.
You pay your providers directly. switchback takes no per-token fee of its own.
Five dialects, one request shape
A dialect is a full round trip: request translation, response parsing, stream normalization. Chains mix them freely, and fourteen bundled host profiles layer per-vendor quirks on top.
- openai-compat OpenAI & compatible
- anthropic-messages Claude Messages
- gemini-generate Google Gemini
- bedrock-converse AWS Bedrock
- cohere-chat Cohere
One file describes the whole edge
Upstreams, models, routes, caps, and what each one makes the router do.
switchback.config.json
{ "route": {
"listen": { "host": "127.0.0.1", "port": 8787 },
"upstreams": {
"openai-primary": {
"baseURL": "https://api.openai.com/v1",
"dialect": "openai-compat",
"auth": { "env": "OPENAI_API_KEY" }
},
"anthropic-main": {
"baseURL": "https://api.anthropic.com",
"dialect": "anthropic-messages",
"auth": { "env": "ANTHROPIC_API_KEY" }
}
},
"models": {
"mux/fast": {
"openai-primary": "gpt-4o",
"anthropic-main": "claude-sonnet-4-5"
}
},
"routes": {
"chat-default": {
"match": { "models": ["mux/fast"] },
"chain": ["mux/fast"],
"policy": {
"advanceOn": ["rate_limited", "server_error"]
}
}
},
"budget": {
"backend": { "kind": "redis" },
"global": { "dollars": "250.00", "window": "daily" }
}
} }
What the router then does
-
Binds loopback
Nothing is exposed off-box until you changelisten.hostyourself. -
Resolves two keys
Separately, at startup. An unset variable is a startup failure naming it, not a 500 during the incident you're already having. -
Matches, then chains
mux/fastexpands to two legs. The first triesopenai-primary; on a class listed inadvanceOnthe same request is translated into the Anthropic Messages dialect foranthropic-main. -
Reserves, then settles
Against a shared Redis counter, so a fleet of replicas shares one daily ceiling instead of each enforcing its own.
The full key-by-key reference lives in Configuration, and the matching and failover rules in Routing.
Where this actually stands
- Private, pre-launch
- The repository is private and nothing is published to a registry. No release, no support commitment, no pricing.
- There is nothing to install
-
No registry package exists, so no
npxornpm installline here will work. You build from a checkout and runnode dist/switchback-cli.js. See Install. - The config shape can change
- The router is under active development and its config shape and behavior may change without notice. The CLI prints the same warning when it starts.
Kin to aimock
aimock mocks LLM traffic; switchback routes it. Same team, same reading of provider wire formats, two separate tools. You can run either without the other.
Write the failover policy down. Then read it back at 3am.
One file you own, on a box you own, with the keys you already have.
Or start from the concern you have: Install · OpenRouter migration · Security · Observability · Deploy