switchback — part of the aimock family private · pre-launch

Configuration

One JSON file describes the whole edge: where the router listens, which upstreams exist and how each one authenticates, which model slugs map where, which routes match what, and the caps that bound spend. This page is the field-by-field reference: every key, its type, its default, and exactly what refuses to load.

How the file is read

The config is plain JSON, parsed in one shot at startup. The default path is switchback.config.json in the working directory; --config points elsewhere. The loader reads two top-level keys: route, which is everything on this page, and fixtures, which only sim reads. Anything else in the file is ignored, so a stray sibling key is silently inert rather than an error.

Inside route, three blocks are required: listen (with at least a port), upstreams (at least one), and routes (at least one). models, budget, catalog and record are optional.

the smallest config that loads and serves json
{
  "route": {
    "listen": { "port": 4011 },
    "upstreams": {
      "openai-direct": {
        "baseURL": "https://api.openai.com/v1",
        "dialect": "openai-compat",
        "auth": { "env": "OPENAI_API_KEY" }
      }
    },
    "models": {
      "gpt-4o": { "openai-direct": "gpt-4o" }
    },
    "routes": {
      "default": {
        "chain": ["gpt-4o"],
        "policy": { "advanceOn": ["rate_limited", "server_error"] }
      }
    }
  }
}

Warning

Optional fields are never coerced. A present-but-wrong-typed value is a hard load error, not a silent fallback. "enabled": "true" (the string) fails; it does not become false. Every rejection is reported as Invalid route config in <path>: <message> and the process exits 1. A config with no route key exits 1 the same way.

Declaration order in the file is significant in three places: the order of upstreams drives the leg order for unlisted models, the order of routes decides first-match route selection, and budget scopes are listed in declaration order. Reordering keys changes behavior.

Check a file without starting the server. This loads it through the same loader the server uses, so anything below that is a hard failure surfaces here first.

validate before you start shell
$ switchback config check --config switchback.config.json

A complete config

Every block on this page appears below, with real values. Copy it, change the upstream names and the environment variable names, and it will load.

switchback.config.json json
{
  "route": {
    "listen": { "host": "127.0.0.1", "port": 4011 },
    "upstreams": {
      "openai-direct": {
        "baseURL": "https://api.openai.com/v1",
        "dialect": "openai-compat",
        "profile": "openai",
        "auth": { "env": "OPENAI_API_KEY" },
        "timeouts": { "connectMs": 2000, "ttftMs": 15000, "totalMs": 120000 }
      },
      "anthropic-direct": {
        "baseURL": "https://api.anthropic.com",
        "dialect": "anthropic-messages",
        "profile": "anthropic",
        "auth": { "env": "ANTHROPIC_API_KEY" },
        "headers": { "anthropic-version": "2023-06-01" }
      },
      "ollama-local": {
        "baseURL": "http://127.0.0.1:11434/v1",
        "dialect": "openai-compat",
        "profile": "openai",
        "auth": null
      },
      "openrouter-fallback": {
        "baseURL": "https://openrouter.ai/api/v1",
        "dialect": "openai-compat",
        "profile": "openrouter",
        "auth": { "env": "OPENROUTER_API_KEY" },
        "unlistedModels": "verbatim",
        "forwardHeaders": ["HTTP-Referer", "X-Title"],
        "allowCallerKeys": false
      }
    },
    "models": {
      "gpt-4o": {
        "openai-direct": "gpt-4o",
        "openrouter-fallback": "openai/gpt-4o"
      },
      "claude-sonnet-4-5": {
        "anthropic-direct": "claude-sonnet-4-5",
        "openrouter-fallback": "anthropic/claude-sonnet-4.5"
      },
      "llama-3.3-70b": {
        "ollama-local": "llama3.3:70b",
        "openrouter-fallback": "meta-llama/llama-3.3-70b-instruct"
      }
    },
    "routes": {
      "chat-default": {
        "match": { "surface": ["/v1/chat/completions", "/api/v1/chat/completions"] },
        "chain": ["gpt-4o", "claude-sonnet-4-5", "openrouter/auto"],
        "provider": { "allow_fallbacks": true },
        "policy": {
          "advanceOn": [
            "rate_limited", "auth_budget", "server_error", "connect_error",
            "timeout_connect", "timeout_ttft", "silent_empty",
            "stream_error_pre_token", "translated_bad_request"
          ],
          "sameLegRetries": { "server_error": 1 },
          "backoff": { "baseMs": 200, "maxMs": 2000, "jitter": true },
          "respectRetryAfter": { "capMs": 5000 },
          "maxTotalAttempts": 6,
          "keepalive": false
        }
      }
    },
    "budget": {
      "backend": { "kind": "memory", "persistPath": "./.switchback/budget.json" },
      "global": { "dollars": "500.00", "tokens": 50000000, "window": "monthly" },
      "perRoute": { "chat-default": { "dollars": "50.00", "window": "daily" } },
      "perUpstream": { "openrouter-fallback": { "dollars": "25.00", "window": "monthly" } },
      "priceMap": {
        "llama3.3:70b@ollama-local": { "prompt": "0", "completion": "0" }
      },
      "promptSafetyFactor": 2.0,
      "completionReserveFraction": 1.0,
      "allowUnpriced": false,
      "overflowFallback": false,
      "onStoreError": "fail-closed"
    },
    "catalog": { "refresh": false },
    "record": { "enabled": false, "dir": "./fixtures/recorded" }
  }
}

Two details in that file are worth naming now, because both are easy to get wrong. "openrouter/auto" is not in models; it reaches openrouter-fallback only because that upstream sets unlistedModels: "verbatim". And the priceMap key is llama3.3:70b@ollama-local, the upstream model id, not the llama-3.3-70b slug. See priceMap keys.

fixtures

A list of glob patterns naming the fixture files sim replays a request against. This is the one key that lives beside route rather than inside it, because it describes upstream behaviour for the whole file rather than any single route.

fixtures json
{
  "fixtures": ["./fixtures/failure-taxonomy/*.json", "./fixtures/app/*.json"],
  "route": { /* ... */ }
}

Relative patterns resolve against the config file's directory, not the working directory, so a committed config simulates identically from anywhere in a repo. A pattern that matches no files is a hard failure: a run against zero fixtures routes nothing and would read as a pass. The serve path never reads this key, so a config with no fixtures is complete for production — it simply cannot be simulated.

route.listen

Required. Where the HTTP server binds.

listen.host string optional default: 127.0.0.1

Interface to bind. Loopback by default, so a fresh config exposes nothing off-box.

listen.port integer required no default

Must be a non-negative integer. 0 is legal and means "let the OS pick", and the chosen port is reported back on startup.

Warning

Omitting the whole listen block is a hard failure: route.listen is required (needs at least a port). Any host other than 127.0.0.1, localhost or ::1 loads fine but logs a warning naming the exposure. See Security for the bind posture, and Deploy for when you actually want it.

route.upstreams

Required, at least one entry. An object keyed by upstream name, and that name is what models, budget.perUpstream, provider.only and the per-request headers all refer to. Declaration order matters for unlisted models.

baseURL string required no default

Non-empty URL the legs are dispatched against. A URL carrying inline userinfo (https://user:pass@host) is refused at load. Paste the provider's documented base as it is, with or without its trailing API version: the dialect appends its own path (/v1/chat/completions for openai-compat), and a version segment already at the end of the base is not repeated. So https://api.openai.com/v1 and https://api.openai.com both dispatch to https://api.openai.com/v1/chat/completions.

dialect enum required no default

The wire format spoken to this upstream: openai-compat, anthropic-messages, gemini-generate, bedrock-converse or cohere-chat. Per-dialect capability detail lives in Providers.

profile string optional default: openai

Host profile id, which carries the vendor's auth-header shape and quirks. Must be one of the 14 bundled ids listed below; an unknown id is a hard failure.

auth object | null optional default: keyless

Exactly { "env": "VAR" }, { "file": "path" }, or null. Nothing else. Full grammar below.

headers object optional default: none

Static string headers added to every request to this upstream, for things like anthropic-version. Any value that looks like a credential is a hard load error; keys go through auth.

timeouts object optional default: none

connectMs, ttftMs, totalMs. Each must be a positive finite number. connectMs and ttftMs are what produce the timeout_connect and timeout_ttft verdicts that policy.advanceOn can act on.

unlistedModels enum optional default: none

Whether this upstream serves slugs absent from models: "verbatim" passes the slug through, "strip-author" drops everything up to the first /, "none" (or unset) declines. See Routing for how these become legs.

forwardHeaders string[] optional default: none

Allowlist of caller headers to pass through to this upstream. Naming a provider-auth header here is a hard load error.

allowCallerKeys boolean optional default: true

Whether a caller-supplied key may be used for this upstream. Set it to false to force the router's own credential.

Danger

allowCallerKeys is a sibling of auth, not a field inside it. Written as auth.allowCallerKeys it does not disable caller keys. It trips the "unexpected key(s)" error and the config refuses to load. That failure is the friendly outcome; the shape that would quietly leave caller keys enabled is the one to watch for.

The auth grammar

Credentials are referenced, never written inline. The loader accepts three forms and rejects everything else.

auth.env string optional one of env / file

Name of an environment variable, read once at load. Unset or empty is a hard failure naming the variable, so a missing key is a startup error rather than a 500 mid-incident. An env name that itself looks like a credential is refused.

auth.file string optional one of env / file

Path to a key file; relative paths resolve against the config file's directory. The file must be mode 0400 or 0600; any looser mode is a hard failure that states the actual octal mode. Contents are trimmed.

auth: null null optional default when omitted

A keyless upstream. This is the right shape for a local model server that needs no credential.

Danger

There is no way to put a secret in this file. A bare string in auth is refused; both env and file together is refused; neither is refused; and any extra key (value, token, key) is refused by name. If the rejected string looks like a credential the error says so without echoing the value. Credential-shape detection also covers headers values and generic high-entropy strings, so an inline key smuggled through a static header fails the same way.

Bundled profile ids

Fourteen host profiles ship with the router. openai is the fallback.

Profile ids
openai · anthropic · gemini · bedrock · cohere
openrouter · groq · mistral · perplexity · cerebras
sambanova · alibaba · zai · moonshot

route.models

Optional. A two-level map: client-facing slug, then upstream name, then that upstream's own model id. These slug keys are exactly what /v1/models and /api/v1/models advertise, so this block doubles as your published catalog.

models.<slug>.<upstream> string optional block default: none

The upstream's model id for this slug. Must be a non-empty string, and the upstream name must exist; an unknown name fails with route.models.<slug> references unknown upstream "<up>". A slug listed here is served only by the upstreams named under it; unlistedModels does not apply to it.

route.routes

Required, at least one entry. An object keyed by route name, evaluated in declaration order: the first route whose match accepts the request wins, so put the catch-all last.

match object optional default: {} = catch-all

match.surface is a string array of exact request paths; match.models is a string array of *-globs against the requested model. Both must be arrays of strings if present.

chain string[] required no default

Model slugs in fallback order. Each slug expands into one leg per upstream that can serve it; the router walks that list until one succeeds.

provider object optional default: none

Upstream preferences: order, only, ignore (string arrays), allow_fallbacks (boolean), sort. See below.

policy object required no default

Retry and advance behavior. policy.advanceOn is itself required, so every route states in writing which failures are allowed to move the chain.

keepalive boolean optional default: off

Streaming-only keepalive for this route. Also settable inside policy.

Note

A chain entry that maps to no upstream is only a warning at load, not an error: chain model "<m>" maps to no upstream … it will contribute zero legs. The config starts. If the whole chain maps nowhere, requests matching that route get a 404 at request time. Read the startup log.

provider

order front-loads named upstreams, only and ignore filter, and allow_fallbacks: false truncates the chain to the primary candidate. A request may narrow these further but never widen them; the composition rules are in Routing.

provider.sort "price" | "latency" | null optional default: null no effect yet

Validated at load and rejected if it is anything other than those three values, and then ignored. The comparators it would need are never supplied on the live request path, so leg order is preserved exactly as expansion produced it.

Warning

Do not plan cost or latency ordering around provider.sort in this build. A route with "sort": "price" and a priceMap making the second-declared upstream a thousand times cheaper still sends the request to the first-declared one. If you want a cheap upstream tried first, declare it first, or front-load it with provider.order.

policy

policy.advanceOn string[] required no default

Which failure classes advance to the next leg. Every entry must be a known reason; an unrecognised one is a hard failure naming the bad reason. Valid values are listed below.

policy.sameLegRetries object optional default: 0 per reason

Per-reason retry count against the same leg before advancing, e.g. { "server_error": 1 }. Non-negative integers only.

policy.backoff object optional default: 200 / 2000 / jitter on

{ "baseMs", "maxMs", "jitter" }, and all three are required together if you supply the block at all. Omit it entirely to accept the defaults.

policy.respectRetryAfter object optional default cap: 30000 ms

{ "capMs": number }, and nothing else. Bounds how long a provider's Retry-After is allowed to stall a request. There is a built-in cap even when you omit this.

policy.maxTotalAttempts integer optional default: unlimited

Positive integer ceiling on attempts across the whole chain, retries included. Left out, the chain is bounded only by its own length and retry counts.

policy.keepalive boolean optional default: off

Streaming keepalive, same switch as the route-level keepalive.

Valid advanceOn reasons

Reason Advances the chain when
rate_limited 429, with Retry-After honored up to the cap
auth_budget Provider-side permission or budget refusal (401 / 402 / 403 class)
server_error 5xx from the upstream
connect_error TCP, TLS or DNS failure
timeout_connect timeouts.connectMs elapsed
timeout_ttft Dispatched, then stalled before the first token
silent_empty 200 with no content
stream_error_pre_token 200 stream whose first event is an error frame
translated_bad_request 400 on a translated leg, or content the dialect cannot express
budget_exhausted Accepted here but ignored; governed by budget.overflowFallback

route.budget

Optional as a whole block. With no budget, nothing is capped. Budgets covers what the caps mean at runtime (reserve before dispatch, settle from real usage, the 402 envelope). The fields are here.

Field Type Required Default What it does
backend.kind memory | file | redis Optional memory Where spend counters live
backend.persistPath string With file none Optional snapshot for memory; required for file
backend.url string With redis none Redis connection URL (redis:// or rediss://)
global cap object Optional none One ceiling for all traffic; scope key global
perUpstream map of cap objects Optional none Per-upstream ceilings; scope key upstream:<name>
perRoute map of cap objects Optional none Per-route ceilings; scope key route:<name>
priceMap map of price objects Optional none Price overlay on top of the catalog; key format matters
promptSafetyFactor number ≥ 0 Optional 2.0 Multiplier on the estimated prompt cost when reserving
completionReserveFraction number ≥ 0 Optional 1.0 Fraction of max completion tokens reserved up front
allowUnpriced boolean Optional false Whether a leg with no known price may run under a dollar cap
overflowFallback boolean Optional false Whether a reserve refusal advances the chain instead of failing the request
onStoreError fail-closed | fail-open Optional fail-closed What happens when the counter store is unreachable

Warning

backend.kind: "file" without backend.persistPath is a startup failure: budget.backend.kind is "file" but budget.backend.persistPath is not set. Set the path, or use memory, where persistPath is an optional snapshot. Which backend suits which topology is covered in Deploy.

Cap objects

Every scope (global, each perUpstream entry, each perRoute entry) takes the same three fields.

dollars decimal string optional default: none

A string, not a number: digits, an optional ., and at most six fractional digits. Parsed and range-checked at load. "1e-6", "-1" and "abc" all fail; "50.00" is the shape you want.

tokens integer optional default: none

Non-negative integer token ceiling for the window. A cap may set dollars, tokens, or both.

window enum optional default: monthly

One of five values: hourly, daily, weekly (Monday-anchored), monthly, total. Anything else is a hard failure.

priceMap keys use the upstream model id

The overlay is keyed <upstreamModelId>@<upstream>, the id the upstream knows, not the client-facing slug. Price literals follow the same grammar as dollars: non-negative plain decimals, with scientific notation rejected explicitly at load.

right key, wrong key json
// models maps the slug "llama-3.3-70b" onto the upstream's own id:
"models": { "llama-3.3-70b": { "ollama-local": "llama3.3:70b" } }

// so the price key is built from THAT id:
"priceMap": { "llama3.3:70b@ollama-local": { "prompt": "0", "completion": "0" } }

// this one is accepted, never matches, and silently does nothing:
"priceMap": { "llama-3.3-70b@ollama-local": { "prompt": "0", "completion": "0" } }

Danger

A priceMap key that matches nothing produces no error. The overlay is ignored and the leg falls through to the catalog. So the common intent, pricing a local model at "0" so a keyless upstream never draws down a dollar cap, fails in the worst direction: with no catalog row and no overlay, that leg is refused as unpriceable under a dollar cap instead of being free. Check the key against the id in models, character for character.

route.catalog

Optional. The router ships with a signed catalog snapshot, which is what prices legs by default. This block configures refreshing that snapshot over the network.

catalog.refresh boolean optional default: false

Master switch. Present but not a boolean is a hard failure. Refresh only arms when this is true and both url and intervalSec are set.

catalog.url string optional default: none

Where the signed catalog.json is fetched from. Inline userinfo in the URL is a hard failure, and the URL is scheme- and SSRF-checked before any timer starts.

catalog.intervalSec number optional default: none

Seconds between refresh attempts. Values of zero or less are currently accepted by the loader without complaint, which is a known defect. Pass a sensible positive interval.

Warning

Network catalog refresh does not arm in this build, even fully configured. The pinned verifying key is still the committed development key, whose private half is in the repo and therefore forgeable, and a forged catalog could price a model to zero and walk through a dollar cap. The router logs a refusal instead of starting the timer. The bundled snapshot still verifies and is still used.

route.record

Optional. Writes request/response fixtures for later replay.

record.enabled boolean optional default: false

Turns recording on. The --record flag force-enables it regardless of what the file says. See CLI.

record.dir string optional recorder's default dir

Where fixtures are written. Omitted, the recorder picks its own fixtures directory.

Note

Recorded fixtures go through the same redaction chokepoint as logs, but the extra header-denylist option is not exposed in the config schema today; there is no record.extraHeaders. What is and is not redacted is described in Security.

What refuses to load, and what only warns

A config that refuses to load is doing you a favor. The distinction below is the one worth memorising: the first group stops the process, the second lets it start with behavior you may not have intended.

Condition Outcome
No route key, or listen block missing Exit 1
Empty upstreams or empty routes Exit 1
Missing baseURL / dialect, or unknown dialect or profile Exit 1
baseURL or catalog.url with inline userinfo Exit 1
auth as a bare string, both env and file, neither, or any extra key Exit 1
auth.env variable unset or empty at load Exit 1
auth.file not mode 0400 or 0600 Exit 1
Credential-shaped headers value, or an auth header in forwardHeaders Exit 1
models referencing an unknown upstream Exit 1
Missing chain or policy.advanceOn, or an unknown advance reason Exit 1
Partial backoff block, or a non-positive timeout Exit 1
Malformed dollars / price literal, or an unknown window Exit 1
backend.kind: "file" with no persistPath Exit 1
Any optional field present with the wrong type Exit 1
A chain model that maps to no upstream Warning; 404 at request time if the whole chain is unmapped
Non-loopback listen.host Warning naming the exposure; binds anyway
provider.sort set Accepted, validated, then ignored
priceMap key that matches no leg Silently ignored, no message at all
catalog.intervalSec of zero or less Accepted; known defect
fixtures not an array, or an entry not a string Refuses to load
Unrecognised top-level key beside route and fixtures Ignored

What SIGHUP actually reloads

SIGHUP re-reads the whole file, but most of it is not hot-swappable. Treat it as a way to adjust caps and prices, not as a general reload.

Part of the config On SIGHUP
Budget caps and cap gauges Rebuilt
priceMap overlay Rebuilt
Credential registry (auth refs re-resolved) Rebuilt
Budget backend Restart required (logs a warning)
Catalog refresher Restart required (logs a warning)
Observer hooks and recorder Restart required (logs a warning)
listen.host / listen.port Restart required (logs a warning)

Where the behavior is documented

This page is the schema. What each block does at request time lives with the behavior it governs.