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

Quickstart

Five steps from a built clone to a routed chat completion: write the smallest config the loader will accept, validate it, start the router, and send one request. Everything here runs on loopback.

Before you start

This page assumes you have already done Install: a clone of the private repository, built, with dist/switchback-cli.js on disk. Every command below is run from the root of that clone.

You also need a real API key for a provider you have an account with. Every request in this guide goes to a live upstream and bills your provider account; nothing here is a dry run. To exercise a route config without a key or a network, replay a request against fixtures with the sim subcommand instead.

Warning

Run dist/switchback-cli.js, not the dist/switchback-cli.cjs twin next to it. The CJS artifact is not recognised by the self-run guard, so it loads, prints nothing, and exits 0, which looks exactly like a silent hang.

1. Write the smallest config that loads

Save this as switchback.config.json in the clone root. That filename is the CLI default, so you can drop --config once it is in place. The flag is spelled out below anyway, because being explicit is cheap.

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" }
      }
    },
    "models": {
      "gpt-4o": { "openai-direct": "gpt-4o" }
    },
    "routes": {
      "chat-default": {
        "match": {},
        "chain": ["gpt-4o"],
        "policy": { "advanceOn": ["rate_limited", "server_error"] }
      }
    }
  }
}

That is not an abridged example. It is the floor. Four things are mandatory:

route object required

The router reads exactly one top-level key. A file without route is not a partial config: the loader returns nothing and the CLI exits 1.

route.listen.port integer required no default

There is no default port, and omitting the whole listen block is a hard error. listen.host does default to 127.0.0.1; a non-loopback host is honored but logs a warning naming the exposure.

route.upstreams object required at least one entry

Each upstream needs a baseURL and a dialect. Its credential is a reference, either { "env": "VAR" } or { "file": "path" }, never an inline value. route.models, by contrast, is optional.

route.routes.<name>.policy.advanceOn array required

Every route needs a policy, and every policy needs an advanceOn array, the failure classes that move the chain to its next candidate. An empty array is a valid answer ("never advance"); a missing key is not.

match: {} makes this route the catch-all, and chain holds a single candidate, so there is nothing to fail over to yet. That is deliberate: get one leg working, then read Routing to add the second.

2. Set the key, then validate

The variable named by auth.env is read once, at load. Export it first, then let the CLI tell you whether the file is sound before you try to serve traffic.

export and check shell
$ export OPENAI_API_KEY=your-openai-api-key
$ node dist/switchback-cli.js config check --config switchback.config.json

A sound config prints one line and exits 0:

output text
Config check passed: /abs/path/switchback.config.json is valid and all referenced env vars are set.

Danger

your-openai-api-key above is a placeholder. Substitute your own key at the shell and keep it out of the config file, out of your shell history, and out of version control. The config grammar enforces half of this for you: an inline secret, a credential-shaped header value, or userinfo embedded in a baseURL is refused at load rather than quietly accepted.

3. Start the router

start shell
$ node dist/switchback-cli.js --config switchback.config.json

Three lines, in this order, and then it is listening:

startup log text
[switchback] EXPERIMENTAL: the self-hosted router is under active development; config shape and behavior may change without notice (§13.9).
[switchback] auth: default mode — keys held in memory; SIGHUP re-reads keys from env
[switchback] router listening on http://127.0.0.1:4011

The experimental notice is printed on every start, and it means what it says: treat the config shape as unstable. The second line is the key posture: credentials live in this process's memory only, and SIGHUP re-reads them from the environment without a restart.

4. Send the first request

The OpenAI Chat Completions surface is /v1/chat/completions. Leave the router running and use a second terminal.

first request shell
$ curl -i http://127.0.0.1:4011/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"ping"}]}'

A success is a normal Chat Completions body plus four x-switchback-* headers that say who served it and how many attempts it took:

response http
HTTP/1.1 200 OK
content-type: application/json
x-switchback-upstream: stub
x-switchback-dialect: openai-compat
x-switchback-attempts: 1
x-switchback-budget-remaining: global=4.999977

{"id":"chatcmpl-x","object":"chat.completion","created":1,"model":"gpt-4o","choices":[{"index":0,"message":{"role":"assistant","content":"pong"},"finish_reason":"stop","native_finish_reason":"stop"}],"usage":{"prompt_tokens":5,"completion_tokens":1,"total_tokens":6},"provider":"openai"}

Note

That transcript was captured against a local stub upstream named stub, standing in for OpenAI, with a global dollar cap configured. With the config on this page you will see x-switchback-upstream: openai-direct, real token counts, and a real completion. The x-switchback-budget-remaining line reports what is left under a configured cap (see Budgets), and Observability covers the header set in full.

The OpenRouter-shaped surface

The same request sent to /api/v1/chat/completions comes back in the OpenRouter envelope instead: a gen- id, reasoning on each choice, and system_fingerprint / service_tier present as nulls. Same bytes from the upstream, one post-pass.

/api/v1 response body, abridged json
{"id":"gen-x","object":"chat.completion",...,"choices":[{"index":0,"message":{"role":"assistant","content":"pong","reasoning":null},"finish_reason":"stop","native_finish_reason":"stop"}],...,"provider":"openai","system_fingerprint":null,"service_tier":null}

If you are pointing an existing OpenRouter client at the router, that is the surface you want; OpenRouter migration covers what else carries over.

Streaming

Add "stream": true to the body. The routing headers arrive with the SSE head, before the first token, followed by chat.completion.chunk frames and a final data: [DONE].

streaming response head http
HTTP/1.1 200 OK
content-type: text/event-stream; charset=utf-8
cache-control: no-cache
connection: keep-alive
x-switchback-upstream: stub
x-switchback-dialect: openai-compat
x-switchback-attempts: 1
x-switchback-budget-remaining: global=5.000000

5. Read what it decided

Every request leaves one routing report behind, retained in memory and served at GET /route/reports. This is the thing to reach for when a response surprises you: it names each leg tried, its verdict, and what it cost.

the last report shell
$ curl -s http://127.0.0.1:4011/route/reports | jq '.reports[0]'
report, excerpted json
{
  "id": "rt-e0d276c4f3ee",
  "surface": "/v1/chat/completions",
  "requested_model": "gpt-4o",
  "candidates": ["gpt-4o"],
  "legs": [{
    "candidate": "gpt-4o", "upstream": "stub", "dialect": "openai-compat",
    "verdict": "success", "status": 200, "connect_ms": 1,
    "usage": { "prompt_tokens": 5, "completion_tokens": 1 },
    "budget": { "settlement": "committed_actuals", "amount": "0.000023" },
    "cost": { "amount": "0.000023", "source": "catalog" }
  }],
  "client": { "aborted": false, "committed_at_ms": 1 },
  "winner": { "candidate": "gpt-4o", "upstream": "stub", "provider": "openai" },
  "budget": { "scope": "global", "remaining": "4.999954" }
}

One leg, one verdict, one winner. When a chain has several candidates the legs array grows an entry per attempt, each with the verdict that ended it, which is how you tell a failover from a retry.

If it will not start

The failure you are most likely to hit is a declared credential that is not in the environment. A referenced variable that is unset or empty is a hard load error, not a warning, and it stops both config check and the server with exit 1:

load failure text
Invalid route config in /abs/path/switchback.config.json: upstream "openai-direct": auth.env references environment variable "OPENAI_API_KEY" which is unset or empty — a declared key must be present at load, otherwise the upstream is silently keyless and every request 401s

The fix is the export from step 2, in the same shell that starts the router. Note what the message does not contain: the loader prints the variable's name, never its value. Two consequences worth internalising. Declare only the keys you have, because an upstream you are not using yet still fails startup if its variable is missing. And the loader stops at the first unset variable, so fixing one can reveal the next.

The other common first-run error is a config whose keys sit at the top level. Everything belongs under route, or you get:

missing section text
Config in /abs/path/switchback.config.json has no "route" section — nothing to serve.

Two things that will surprise you

Both are consequences of the router being chain-driven rather than model-driven. Better to meet them here than in an incident.

The request's model does not pick the candidate

With no models array in the request body, the engine routes the matched route's chain, whatever model says. Against the config on this page, a request for "model":"nope" is served successfully by gpt-4o. The model field is used for exactly two things: choosing a route via match.models globs, and populating requested_model in the report.

Send a models array to override the chain instead. A slug in there that maps to no upstream is a clean 404 rather than a silent substitution:

unmapped candidate json
{"error":{"message":"no upstream mapping for candidates: nope","type":"no_route_configured","code":404}}

Only Chat Completions is served

Legacy /v1/completions is a permanent 404 with a message that says so, and any unknown path is a structured 404 too. Nothing is proxied through by accident.

unknown path json
{"error":{"message":"no such endpoint: GET /nope","type":"not_found","code":404}}

Where to go next

You now have one upstream, one candidate, and no caps. Each of the next three pages removes one of those limits.