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:
# 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 -- servePoint 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.
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/v1and choose modelauto(orvitna/auto). - Claude Code / Anthropic SDKs: set
ANTHROPIC_BASE_URL=http://127.0.0.1:8787for byte-for-byte/v1/messagesand/v1/messages/batchespassthrough 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.
# 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 servePass --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.
# 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-01Setting VITNA_LEDGER=/var/lib/vitna/ledger.jsonl also mirrors each completed request onto the shared runtime ledger 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 unlessVITNA_INBOUND_KEYorVITNA_ROUTE_API_KEYSis configured. - When running open on loopback without inbound keys, browser-forged non-loopback
Hostheaders,/v1/*POSTrequests with anOriginheader, and non-application/json/v1/*POST payloads are rejected with403. VITNA_ALLOW_PROVIDERSrestricts eligible models and passthrough routes per vendor (for example,openai,anthropicexcludes OpenRouter-backed targets).- See The runtime and Emitting a routing policy for the sibling lane-based signed policy format (
vitna-routing-policy-v1).
