> Source: https://vitna.ai/docs/routing/router
> Raw Markdown: https://vitna.ai/docs/routing/router.md
> Corpus index: https://vitna.ai/llms.txt
# Vitna router
**Built on 2026-08-31, ahead of the preconditions this page sets out, on the
owner's instruction.** The software exists: `npm run router:start` runs a
multi-tenant router serving C1, and [Running the hosted router](hosted.md) is
how. What does not exist is the product. Vitna operates no traffic for anybody,
the three preconditions in `RUNTIME.md` phase R5 are still unmet, and this page
remains the design to hand a reviewer rather than a description of a service
somebody can buy.
**Frozen at the design on 2026-09-09, and no further code goes into it.** What
Vitna sells is routing in the customer's own infrastructure, where independence
needs no argument, the customer's own merge is still a control, and an outage
here is not an outage there. Hosted routing serves the one buyer that position
does not reach, the buyer who cannot run a process at all, and nobody has
counted that buyer yet. The page stays published for the reason it was written:
a design a reviewer can refuse is worth more unshipped than a service nobody
asked for is worth running.
Drafted 2026-08-30. It existed because the blocking precondition on that mode is
"a credential custody design that has been reviewed by someone whose job is to
refuse it", and a design cannot be refused until somebody writes one down. That
is still what it is for, and the reviewer's job is now easier and more urgent:
there is code to read beside the argument.
**The marker this page opened with is gone, and its going is the mechanism
working rather than a rule being dropped.** It read "Not built", named
`npm run router:start` as the thing whose existence would falsify it, and
`tests/docs-drift.test.mjs` failed on the commit that added that script and sent
somebody here. `docs/README.md` records why the check runs in that direction: a
page that goes on calling itself a plan after the thing ships reads as modesty
and is a false statement about what the reader is running. So the sentence
changed on the day the claim did.
**What each section is now**, because a design page and a description of running
software want different reading:
| Sections | Status |
|---|---|
| 1 to 3 | The argument and the custody ladder. Unchanged, and still the thing to refuse |
| 4 | Built. The reachable universe is compiled at emit time by `platform/engine/reachable.mjs` |
| 5 | Built, with C1 as the only route. C2 and C3 are designed and are not implemented |
| 6 | The costs. Unchanged, and none of them is paid off by the code existing |
| 7 | Half built. The key split shipped; the independent trail is `npm run router:trail` |
| 8 | The sequencing, with steps 0, 1, 3 and 5 struck through or amended below |
| 9 and 10 | What a router may never do, and what is still not verified |
Authority sits elsewhere and this document defers to all three. `RUNTIME.md`
is authoritative for the execution modes, the application axis, the phases and
the open decisions. `PRICING.md` is authoritative for what may be charged and
what no plan includes, and is itself a proposal dated 2026-08-30 rather than a
settled schedule. `COMPETITION.md` is authoritative for the landscape and for
where this position is weak. Those three are internal and are cited here by
name so a claim can be traced to where it was decided, not so a reader outside
can open them. Where this page and any of them disagree, they are right and
this is a draft that has aged.
## 1. The word, and the boundary it looks like it crosses
`/method` states three boundaries: never a dependency, not an eval platform,
not an autopilot. The first read "not a router" until 2026-08-24, when R1
shipped: it became a statement about the control plane rather than about all
Vitna software, and `RUNTIME.md` records the exact sentences that changed and
why. The page now carries the narrowed form, so this paragraph names what a
reader will actually find there.
This document does not narrow it a second time, and the distinction is worth
being exact about because the word invites the opposite assumption.
| | In the request path | Holds provider keys | Bills for tokens |
|---|---|---|---|
| The record and the emitters | No | No | No |
| `vitna-runtime`, customer-run | The customer's software is | The customer does | No |
| The router described here | **Yes** | **No, and section 3 is how** | **No, and `PRICING.md` forbids it** |
| A router as the market builds one | Yes | Yes | Usually |
The third row is the whole proposal. The fourth row is what `COMPETITION.md`
calls a scorekeeper marking its own exam, and it is the thing this design has
to avoid becoming rather than the thing it has to compete with.
## 2. What "rotate" means, and each kind has its own gate
Five distinct rotations get bundled under the word. They are not one feature
and they must not share an authorisation gate.
| Rotation | Trigger | Gate | Ledger shape | Blast radius |
|---|---|---|---|---|
| Lane to a different sku | Price move, new evidence, a trigger firing | An accepted decision, and a re-emitted policy | `serve: "primary"`, decision id | All of a lane |
| A rule within a lane | A declared predicate on what the request can be counted for | Born shadow. Promoted only under a decision whose brief cites its shadow readings | `serve: "rule:<n>"`, `cohort` where a share looked | A declared slice |
| A canary share | `traffic_share`, nested buckets, shipped 2026-08-27 | The ladder: watching, shadow, five percent, twenty five, incumbent | `cohort`, 0 to 99, on every row | Five to twenty five percent of a lane |
| A fallback | Transport failure, 429, the provider's own 5xx. Never a 4xx, and deliberately never a 401 | The chain an accepted decision registered | `serve: "fallback:<n>"`, never blended into the primary's numbers | One request |
| **The seller of the same model** | A cheaper or faster host for weights nothing decided to change | **Does not exist** | Would need the route on the row | One request |
The first four are built, in `platform/runtime/` and `platform/engine/`, and
run today on the customer's own box. The fifth is the one that most wants a
router, and it is the one this document recommends building first, in section
8, for a reason that has nothing to do with hosting.
**Why the seller is different from the model.** Vitna already mirrors what
every seller of every model charges, key-free, into `app/data/endpoints.json`.
Those prices move on a much shorter half-life than a model choice does, and a
customer applying decisions by hand cannot chase them. Rotating the seller
while holding the model constant is also a change with no quality question
attached, which is what would let it move under a standing decision naming the
model rather than under a new one.
It is not free of a gate, and the record already says why. Those are list
prices per seller and not what anybody paid, and quantization is the seller's
own declaration and is verified by nobody. So a seller whose declaration
cannot be checked is reachable only where a decision named it, and the gate is
the declaration plus measured throughput rather than nothing.
## 3. The custody ladder
One test orders it, and the test is the design in a sentence.
> **The router never holds a credential the customer cannot end in one action,
> at the source, without asking Vitna.**
| | Posture | Who bills the customer | Their kill switch | Reaches |
|---|---|---|---|---|
| C0 | Customer-held, customer-run: `vitna-runtime`, Deploy | Their provider, directly | Stop the process | Everything. Built |
| C1 | Delegated and revocable at source: the OpenRouter key a consent screen mints | OpenRouter, directly | `openrouter.ai/keys/<sha256>` | Everything OpenRouter lists |
| C2 | Federated and short-lived: assumed roles, workload identity, managed identity | Their cloud, directly | Delete the trust policy | Bedrock, Vertex, Azure |
| C3 | The key rides the request, held for its life and never written | Their provider, directly | Rotate the key | OpenAI and Anthropic direct |
| C4 | A stored provider key | Vitna could be | Ask Vitna to delete it | Refused |
**C4 is refused and does not become available later.** Not because sealing a
secret is unsolvable, but because "ask Vitna to delete it" is the customer's
only remedy, which is the shape of dependency this whole architecture is
arranged against. `PRICING.md` lists "provider keys stored by vitna.ai" among
the things no plan includes, and this document does not reopen it.
**C1 is three quarters built and is the interesting rung.**
`docs/routing/connected-accounts.md` describes a control-plane connection that
serves no traffic: OAuth PKCE, owner-only and checked twice, the verifier held
in the session and never sent, sealed with AES-256-GCM under additional
authenticated data binding provider, org and fingerprint, and written by a role
whose column-list `SELECT` cannot read `sealed_key` back. Making that key serve
traffic changes none of it.
What it buys that nothing else on the ladder buys is a check Vitna does not
control:
> The customer reads what the key did at `openrouter.ai/logs?api_key_hash=<sha256>`,
> at a party Vitna is not. The router's own ledger becomes falsifiable by
> somebody else's record.
That is the same move as pinning the public key out of band rather than reading
it from the file it verifies. A claim somebody can check beats a claim
somebody makes.
It also survives `PRICING.md`'s narrowest exclusion, which is worth stating
because it is the one a hosted router looks most likely to trip. "Consolidated
billing for third-party model providers" is excluded; a PKCE key is minted
under the customer's own OpenRouter account, so OpenRouter bills them directly
and Vitna is a merchant of record for nothing.
**C2 is where the cloud vendors already solved this.** Nothing at rest,
credentials minted per request and expiring in minutes, revoked by deleting a
trust policy the customer owns. The exact shape of each grant is a vendor fact
and is not asserted here: it carries a retrieval date when an adapter is
written against it, per the repository rule.
**C3 is the honest weak rung and should not ship first.** The router sees
plaintext, in memory, for every request. "Nothing is stored" is true and
smaller than it sounds, because a compromised router harvests every key that
passes through it. It also forces the caller to present a bundle rather than a
key, since a fallback may cross vendors inside one request.
## 4. Custody and routing are one fact seen twice
This is the part that makes the design cohere with what is already built
rather than sitting beside it.
`allowedProvidersOf` and `hasDataRequirement` in `platform/engine/policy.mjs`
are read when a policy is emitted, so a lane carrying a data requirement is
emitted with no OpenRouter name at all: the traffic cannot go there, rather
than being asked not to. `RUNTIME.md` states the general form, that gates are
compiled into the signed policy and never evaluated by Vitna while a request
waits.
Apply the same move to credentials.
> The credentials an org has connected define its **reachable universe**,
> established when the connection is made and compiled into the policy at emit
> time. A rotation to a provider the org has not funded is unreachable, not
> refused at request time.
Three things fall out without being designed:
- No synchronous permission check, so the router asks vitna.ai nothing while a
request is waiting. That is the property, not a promise about it.
- Disconnecting a credential is a policy re-emission, through the same signed
artifact as everything else, rather than a runtime state change nobody can
audit.
- The console can say, per lane, reachable by which route or unreachable and
why, which is the shape `/status` already answers in for keys and lanes.
## 5. One request
```
caller SDK -> router model: "vitna/deep-research"
resolve lane the signed policy, digest pinned per request
rules declared predicates, exact character counts
cohort stable hash, 0 to 99, as traffic_share already buckets
route C1 delegated, C2 federated, or C3 presented
attach minted per request, or opened, or forwarded
forward the provider's own endpoint, billing the customer
fallback 5xx, 429 and transport only, each its own row
ledger lane, digest, decision id, sku, route, cohort,
tokens, latency, primary or fallback or shadow
```
Everything `platform/runtime/` refuses today it keeps refusing: no fabricated
response, no retry of the same model without a row saying so, no fallback
blended into the primary's numbers, no key in a log line or an error message
including a prefix of one, and no reading of content beyond the counts routing
needs.
Two problems are genuinely new, and both are multi-tenancy rather than
routing. Policies must not bleed between tenants, which the per-request digest
pin is the answer to. And under C3 a credential must not outlive the request
that carried it, which is a property to test rather than to state.
## 6. What the router spends, and how much comes back
| Property today | What hosting costs it | Recoverable |
|---|---|---|
| An outage at vitna.ai is an event the runtime cannot observe | Gone. Vitna becomes an uptime dependency | Partly, and less than it first looks. See below |
| Independence: an unflattering verdict costs nothing to publish | At risk the moment Vitna is in the money path | Yes, by never taking a token margin and by C1 to C3 keeping the customer billed by their own vendor |
| Vitna holds no provider keys | Still literally true under C1 and C2. A delegated key and an assumed role are not provider keys | Yes, and the sentence gets more precise rather than retiring |
| Multi-region availability | New, real, and permanent | No. This is R5's actual price |
**The obvious rescue for the first row does not work, and it fails in exactly
the wrong segment.** A client shim whose failure mode is calling the provider
directly with the lane's decided model would turn a Vitna outage into a
question of which model you get rather than whether you get one. But calling
the provider directly requires the customer to hold provider keys locally,
which is the precondition for running the runtime. So the shim protects the
customers who did not need a router, and does nothing for the buyer who cannot
run a process, who is the only reason to build one.
State it as a limit rather than as a mitigation: **a hosted router's outage is
an outage, for the customers it exists to serve.** That is what the third R5
precondition, multi-region availability as a paid promise, is the price of.
## 7. Where the merge disappears, and what has to replace it
`RUNTIME.md` open decision 9, drafted 2026-08-30, splits the signing key: one
Ed25519 key currently signs both the daily Merkle roots and every emitted
config and policy, and a compromise of a customer-facing signer must not be
able to forge the public record's roots. It then declines to overclaim, and
the sentence it declines with is the most important one in this document:
> A forgery still has to reach a runtime, and under the file and GitOps modes
> that means a diff somebody merges, which is a second control. Under a pushed
> policy it is thinner.
**A hosted router is the thinnest case there is.** Vitna signs the policy and
Vitna executes it, so there is no diff, no reviewer and no second party between
a mistaken or forged policy and production traffic. The merge control is not
thin here. It is absent.
Two consequences, and neither is optional.
**The key split stops being hygiene.** Under every other mode it bounds a
compromise. Under a router it is the only control left on what the router
executes, so the router does not ship before it.
**The router owes a replacement control, and it is after the fact.** The
candidate is section 3's independent trail: under C1 the customer can catch a
serve their own register never decided, at OpenRouter, in a log Vitna does not
control. That 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. Any router that ships should ship with a documented way to run
that check, not merely the possibility of one.
**There was a hard ordering constraint here, and it was paid on 2026-08-31,
which is the same day this page first said it was owed.** `policy-store.mjs`
used to refuse a policy whose carried `publicKey` was not the single value
`VITNA_PUBLIC_KEY` pinned, so a key could not be replaced without every
deployed runtime being edited and restarted. It now parses a comma-separated
set and a policy signed by any member verifies, which is how a signing key is
replaced without an outage. `witness.signing_key` landed alongside it, so
"the key the record publishes" is a fact with a purpose attached rather than a
query against the newest attestation row, and that query would have started
answering the wrong question the moment a policy key was split out.
Both are prerequisites of this page rather than parts of it, and both are done.
What that buys the router is narrow and worth stating exactly: the key split is
now possible, not performed. Until it is, one key still signs both the daily
Merkle roots and every emitted policy, and the argument above about a
customer-facing signer is unchanged.
## 8. What to build, and in what order
| | Step | What it clears |
|---|---|---|
| 0 | ~~`VITNA_PUBLIC_KEY` accepts a comma-separated set, and the record says which keys it acknowledges and what each signs~~ **Done 2026-08-31.** | It preceded everything, and it did |
| 1 | ~~Open decision 9: the isolated asynchronous signer, the split key, its own least-privilege role~~ | **Built 2026-08-31.** `aperture:sign`, `vitna_signer`, and the policy key in its own file with its own unit |
| 2 | ~~**Seller rotation under a standing decision, in the customer-run runtime**~~ | **Built 2026-08-31**, after 1, 3 and 5 rather than before them. `docs/routing/sellers.md` |
| 3 | ~~C1 as a data-plane route, still customer-run~~ | **Built 2026-08-31, and hosted rather than customer-run.** The independent trail is `router:trail` |
| 4 | Sell the ten Deploys. Record what each buyer refuses | The R5 demand precondition, measured rather than assumed. **Not done** |
| 5 | ~~Hosted, C1 only, as its own product with its own risk review~~ | **The software is built. The product is not**, and the risk review this row is conditional on has not happened |
**The order above was not followed, and it is worth recording that rather than
tidying it away.**
Steps 1, 3 and 5 were built on 2026-08-31, and step 2, which this section named
as the place to START, was built last on the same day. The reason it was named
first stands: it has no custody question, it proves the rotation mechanics on
data already mirrored, and it is a feature of a runtime that already ships.
What the order cost is smaller than it would have been and is not zero. Seller
rotation now exists in the customer-run runtime, so it is no longer true that its
first run anywhere will be inside a Vitna-operated process. What is still true is
that it was written after the hosted router rather than before it, so it did not
get to be the thing that found the rotation bugs before hosting could add its
own. Nothing in this repository has yet routed a real request to a named seller.
Step 4 is untouched, which means the demand precondition is exactly as unmeasured
as it was when this page was written. The software existing is not evidence that
anybody wants it.
**Step 4 is the honest form of R5's demand precondition.** Deploy is built,
complete, and priced at $79 a month, and `PRICING.md`'s rollout sells it by
hand to the first ten. It is the product that absorbs "run it for me". So the
router's evidence is not whether anybody asks for hosting, it is **what the
first ten Deploy buyers refuse Deploy for.** If they stall on running a process
in their own cloud, that is the signal. If they stall on price or on trust,
which is what the open decision on $79 expects, there is no demand case yet.
**Step 5 is a product and not a tier**, and `PRICING.md` says so in advance:
if Vitna ever operates hosted traffic it becomes a different product with a
different risk review and cost model, and it cannot be smuggled into a plan as
an entitlement.
## 9. What a router may never do
Inherited from `PRICING.md`'s exclusion list rather than invented here, and
narrowed to this surface.
- No token spread, no percentage of provider spend, no percentage of claimed
savings. The fee cannot move with the recommendation, or the recommendation
is not worth reading.
- No paid provider placement, and no preferred-provider ranking.
- No stored provider key, which is C4 and is refused above.
- No consolidated billing. The customer's provider bills the customer.
- No silent substitution of one model for another. Every serve names the
decision that authorised it, per request, forever.
- No prompt or response inspection beyond what routing counts, and no
retention of either beyond the request. `PRICING.md` excludes prompts or
responses transiting Vitna **by default**, and a router is the explicit
non-default: it is an opt-in a customer takes deliberately, priced and
reviewed separately, not a capability that arrives with a plan.
## 10. What is not verified
The four questions open decision 8 asks of Connected mode, re-asked of this
credential class, have answers in sections 3 and 4 rather than open ones: per
account and keyed to the org that granted it, which the sealing already binds;
reachable universe compiled at emit time; revocation makes a lane unreachable
at the provider before Vitna notices, so fail static and report; and owner-only
approval, checked twice, already built. Those answers are for a reviewer to
refuse, which is the point of writing them down.
What is genuinely unverified:
- **Whether an OpenRouter key minted by a consent screen may serve
`/chat/completions` at all.** `docs/routing/connected-accounts.md` says the
key Vitna holds "serves no traffic by design", which implies the capability
without establishing it. Issue #87 already found this grant narrower than
expected once, for usage rather than for serving. Nothing in step 3 is
worth starting until somebody checks this against OpenRouter's own
documentation, with a retrieval date.
- **The shape of each cloud's delegation grant**, which section 3 deliberately
does not assert.
- **Whether the buyer exists.** `COMPETITION.md` already says the audit buyer
is asserted and has not been counted. The router's buyer is a subset of a
population nobody here has observed, and step 4 is the only thing that
changes that.