> Source: https://vitna.ai/docs/runtime/route
> Raw Markdown: https://vitna.ai/docs/runtime/route.md
> Corpus index: https://vitna.ai/llms.txt

# Per-request auto-routing with vitna-route

`vitna-route` selects the model and reasoning effort for each request
deterministically from structural counts of the prompt, preserves prompt caches
across multi-turn conversations, and requires an Aperture-signed policy pinned
by `VITNA_PUBLIC_KEY` before routing live traffic.

It ships inside the Apache-2.0 `vitna-runtime` package with zero external
dependencies. Out of the box it starts in `shadow` mode (serving the
configured incumbent while recording what rules would choose), and once
validated over your shadow ledger it promotes to `route` mode under a signed
`vitna-auto-route-policy-v1` artifact.

## Quick start

Run `vitna-route` globally from `vitna-runtime` or directly from a checkout of
this repository:

```bash
# Shadow trial (loopback, unsigned shadow mode)
OPENAI_API_KEY=... OPENROUTER_API_KEY=... vitna-route serve

# From a repository checkout
OPENAI_API_KEY=... OPENROUTER_API_KEY=... npm run runtime:route -- serve
```

Point any OpenAI-compatible SDK or coding harness at `http://127.0.0.1:8787/v1`
and pass `"model": "auto"` (or `"vitna/auto"`). Requests naming a concrete model
pass through with their parameters intact while still recording a comparison row
in the local ledger.

```bash
curl http://127.0.0.1:8787/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Summarize HTTP status codes in one sentence."}]}'
```

## Coding harness quickstart

Because `vitna-route` exposes `/v1/chat/completions`, `/v1/messages`, and
`/v1/models` on one loopback port, coding agents and SDK clients work with only a
base URL override:

- **OpenAI SDK / OpenAI-compatible tools (`opencode`, `Crush`):** set
  `OPENAI_BASE_URL=http://127.0.0.1:8787/v1` and choose model `auto` (or
  `vitna/auto`).
- **Claude Code / Anthropic SDKs:** set `ANTHROPIC_BASE_URL=http://127.0.0.1:8787`
  for byte-for-byte `/v1/messages` and `/v1/messages/batches` passthrough with
  per-turn decision attribution in the ledger.

## Aperture-signed promotion and offline verification

Unsigned configurations are restricted to `shadow` mode: `vitna-route serve`
refuses to boot an unsigned config with `"mode": "route"`. Moving into `route`
mode requires an Ed25519 signature over the canonical JSON body (`auto-route-json-v1`),
verified against a key you pin in `VITNA_PUBLIC_KEY`.

```bash
# 1. Mint an Ed25519 keypair (or use your existing Aperture policy keypair)
vitna-route keygen

# 2. Sign a validated configuration into a route-mode policy tied to a decision id
VITNA_ROUTE_SIGNING_KEY="$(cat route-key.priv)" \
  vitna-route sign --org acme --decision 42 --mode route --out auto-route-policy.json

# 3. Verify signature, digest, org, decision, and mode offline (exit non-zero on drift)
VITNA_PUBLIC_KEY="$(cat route-key.pub)" \
  vitna-route verify --policy auto-route-policy.json --org acme --require-mode route --json

# 4. Serve under the verified signed policy (SIGHUP reloads fail-statically)
VITNA_ROUTE_POLICY=./auto-route-policy.json \
VITNA_PUBLIC_KEY="$(cat route-key.pub)" \
  vitna-route serve
```

Pass `--shadow` to `vitna-route serve` at any time as an instant rollback to
shadow serving without re-signing or editing the policy file.

## Explain, report, and replay

Every request leaves a single text-free JSONL row of feature counts, decision
reasons, signed policy metadata, and upstream token usage under
`VITNA_ROUTE_DATA_DIR/ledger/YYYY-MM-DD.jsonl` (default `~/.vitna/route/ledger`).
No prompt or completion text is ever written.

```bash
# Decide a single request locally with full scoring and effort reasons
vitna-route explain request.json

# Summarize shadow agreement, token costs, and TTFB from recorded traffic
vitna-route report

# Simulate a candidate policy or config over recorded feature counts
vitna-route replay --config candidate.json --since 2026-11-01
```

Setting `VITNA_LEDGER=/var/lib/vitna/ledger.jsonl` also mirrors each completed
request onto the shared [runtime ledger](ledger.md) format so
`vitna-runtime-profile` and `vitna-runtime-push` read auto-routed traffic directly.

## Configuration and front-door controls

`vitna-route` shares the runtime's loopback and off-loopback security boundaries:

- Binding a non-loopback address (`VITNA_HOST=0.0.0.0`) refuses to start unless
  `VITNA_INBOUND_KEY` or `VITNA_ROUTE_API_KEYS` is configured.
- When running open on loopback without inbound keys, browser-forged non-loopback
  `Host` headers, `/v1/*` `POST` requests with an `Origin` header, and
  non-`application/json` `/v1/*` POST payloads are rejected with `403`.
- `VITNA_ALLOW_PROVIDERS` restricts eligible models and passthrough routes per
  vendor (for example, `openai,anthropic` excludes OpenRouter-backed targets).
- See [The runtime](overview.md) and [Emitting a routing policy](../routing/policy.md)
  for the sibling lane-based signed policy format (`vitna-routing-policy-v1`).
