Get started

Running the hosted router

Source

router:start serves an OpenAI-compatible endpoint for several organisations at once, resolving each request against that organisation's own signed policy and paying for it with that organisation's own delegated OpenRouter key.

bash
VITNA_ROUTER_POLICIES=/etc/vitna/policies \
VITNA_PUBLIC_KEY=$(cat /etc/vitna/policy-key.pub) \
VITNA_ROUTER_LEDGERS=/var/lib/vitna/router \
VITNA_CONNECTION_KEY=... DATABASE_ROUTER_URL=... \
npm run router:start

This is Vitna in a request path, which every other page here says Vitna is not. The design is where that is argued and where its costs are named, including the one that does not go away: a hosted router's outage is an outage, for the customers it exists to serve.

What a hosted policy is, and why it is a different file

bash
npm run aperture:policy -- --org convexity --hosted --out /etc/vitna/policies/convexity.json

--hosted emits only the lanes that organisation's own connections can fund. A lane it cannot pay for is absent from the document, not refused when somebody calls it, which is the same move the emitter already makes for a workload's constraints: a lane carrying a data requirement is written with no OpenRouter name at all, so the traffic cannot go there rather than being asked not to.

Three things follow, and none of them needed designing:

  • The router asks nothing about permission while a request is waiting. That is a property of where the check runs.
  • Disconnecting an account is a policy re-emission, signed like everything else, rather than a runtime state change nobody can audit.
  • Every dropped lane is named when the policy is emitted, so a policy quietly smaller than the register is not a thing that can happen silently.

A hosted policy and a customer-run policy are different documents with different digests, deliberately. What a customer runs on their own box with their own keys and what Vitna may serve on their behalf are not the same set of lanes, and one file pretending to be both would overstate one of them.

Calling it

bash
curl https://router.example/v1/chat/completions \
  -H 'authorization: Bearer vitna_push_...' \
  -H 'content-type: application/json' \
  -d '{"model":"vitna/deep-research","messages":[{"role":"user","content":"hello"}]}'

The key decides which organisation the request is for. A model name without the vitna/ prefix is forwarded untouched and marked unrouted, exactly as the runtime does.

A router key is not a push key. They are the same shape and they are two capabilities: a push key reports what already happened, and a router key spends money at a provider. Mint one deliberately:

bash
npm run org:key:create -- --org convexity --scope router --label "router, prod"

A push key presented to the router is refused with a sentence saying so, and a router key presented to /api/v1/usage is refused the same way. A capability that is a superset of another has not been separated from it.

What it holds, and what it cannot

The credential in front of a requestThe organisation's own OpenRouter key, minted by a consent screen
Who bills the customerOpenRouter, directly, on the account that granted the key
Their kill switchopenrouter.ai/keys/<sha256>, without telling Vitna
A stored provider keyRefused. There is no configuration that turns it on

The router is the only thing anywhere permitted to read a sealed connection, and it holds no write on anything. The console can store a credential and cannot read one back; the router can read one and cannot write one. Neither can do both.

Configuring an instance

VariableMeaning
VITNA_ROUTER_POLICIESDirectory of signed hosted policies, one per organisation, as <org>.json. Required.
VITNA_PUBLIC_KEYThe key to verify them against, pinned once out of band. Several, comma separated, are accepted. Required.
DATABASE_ROUTER_URLThe vitna_router role. Reads one key row and one connection, and writes nothing anywhere. Required.
VITNA_CONNECTION_KEYThe sealing key the console's connect flow uses. Required, or no delegated key opens.
VITNA_ROUTER_LEDGERSDirectory for one ledger per organisation. Optional, and its absence is said out loud.
VITNA_ROUTER_PORTDefault 8788.

GET /status answers for the organisation whose key is presented and for no other. GET /healthz is unauthenticated and says only whether the process is up, because that is not a fact about a tenant.

SIGHUP reloads every policy. A reload that cannot be verified leaves that organisation's running policy in force and takes nobody else's lane down.

Checking the router against a record it does not keep

This is the part worth reading even if you never run the router yourself.

Under the file and GitOps modes, a mistaken or forged policy still has to reach a runtime, which means a diff somebody merges. A hosted router has no diff and no reviewer: Vitna signs the policy and Vitna executes it. The merge control is not thin there, it is absent.

What replaces it is a check you run at a party Vitna is not. Every request the router makes carries your own delegated key, so OpenRouter's record of what that key did is a second account of the same traffic, kept by somebody with no stake in Vitna's ledger being right.

  1. Read what your key did at openrouter.ai/logs?api_key_hash=<sha256>. The digest is on your /status response and on the console beside the connection. The page resolves only for the signed-in owner.
  2. Export it, as JSON or CSV, with a timestamp column and a model column.
  3. Compare it against the router's ledger for your organisation:
bash
npm run router:trail -- --ledger convexity.jsonl --provider openrouter-activity.json

It exits non-zero when the two accounts disagree, so it can sit in your own CI and mean something without being read.

What it catches: a serve the router made and did not record, a serve the ledger claims that never happened, and a model substituted for the one your decision named. What it does not: a forged policy routing within the same model you already funded, which both accounts would agree on. What bounds that is the reachable universe above, which is why the two mechanisms are described together.

The command holds no key and reaches no network. It reads two files you already have, and it runs equally well against a ledger somebody else produced, which is the other half of what makes it worth having.

A clean comparison is not proof the router behaved. It is one account agreeing with another over the window compared, which is weaker than a merge because it catches after rather than before, and stronger than a promise because the checker is not the party being checked.