Get started

Per-request auto-routing with vitna-route

Source

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 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 and Emitting a routing policy for the sibling lane-based signed policy format (vitna-routing-policy-v1).