One base URL. The model a decision named.
An optional process on your own infrastructure that reads a signed policy off disk and serves the model a person accepted. Point any SDK at one base URL, name a lane, and log every attempt locally.
Our software may sit in your request path. Our service may not.
No call to vitna.ai. 127.0.0.1:8787/v1
On npm today, with a signed policy.
Published under Apache-2.0 with zero runtime dependencies. Bring Node 22.13+ and your own provider keys.
- Stage
- On npm.
vitna-runtime0.2.0 is the latest release, published on 2026-10-07. - Licence
- Apache-2.0, with no dependencies.
- Needs
- Node 22.13 or later, and your own key for each provider your lanes name.
- Policy and key
- A signed policy and the key that signed it, both from /console/deployment, signed in to your organisation. An owner asks for the policy there, and the signer runs every five minutes, so it is ordinarily signed within about six. A lane appears once a workload's proposal has been accepted.
- To start
- Free. The software costs nothing on any plan, and the register's Free plan is $0. Public intelligence, open-source runtime, starter web data limits, and 1 active workload.
One request, four ways.
The same lane served by its decision, failed over along its chain, matched by a shadow rule, and passed through unrouted. The runtime is a process on your machine and nothing on vitna.ai would answer one of these, so they are illustrative. To send a real one, the steps below take a signed policy to a served lane, and Relay, in the same package, serves the model you name with no policy at all.
The request names a lane, not a model. The runtime reads the sku an accepted decision chose for that lane out of the signed policy on its own disk, and serves it.
POST /v1/chat/completions
{
"model": "vitna/deep-research",
"messages": […]
}{ "lane": "deep-research", "sku": "anthropic/claude-opus-4-8",
"decision": "154", "serve": "primary", "routed": true,
"outcome": "served", "units": 1 }The primary rate-limited. The runtime walks the chain a person registered against this lane's decision and stops at the first model that answers. One request, two rows: the failure is worth no units and the serve is worth one.
POST /v1/chat/completions
{
"model": "vitna/deep-research",
"messages": […]
}{ "serve": "primary", "outcome": "failed", "status": 429, "units": 0 }
{ "serve": "fallback:1", "outcome": "served", "decision": "154", "units": 1 }A rule is a declared predicate on something the runtime can count, signed into the policy. Every rule is born shadow: it routes nothing, and stamps the row of what actually ran with what it would have served instead.
POST /v1/chat/completions
{
"model": "vitna/deep-research",
"messages": […] // 912,400 chars of content
}{ "sku": "anthropic/claude-opus-4-8", "serve": "primary",
"shadowRule": "rule:2", "shadowSku": "anthropic/claude-sonnet-5",
"outcome": "served", "units": 1 }A model name without the vitna/ prefix is forwarded untouched and marked unrouted, attributed to no decision, because nothing in the record chose it. That is what lets one service point at the runtime and move its lanes over one at a time.
POST /v1/chat/completions
{
"model": "gpt-5.2",
"messages": […]
}{ "model": "gpt-5.2", "routed": false,
"lane": null, "decision": null,
"outcome": "served", "units": 1 }Illustrative requests. Nothing here calls anything.
The answer, and why it was that model.
The provider's answer, as the provider sent it, in the dialect you asked in, errors included. Four headers name the lane, the sku that answered, the decision that authorised it and the policy that carried the decision, and the same values go on a line of your ledger for every attempt.
One line per attempt, on your disk.
A usage export read after the fact is scoped by whatever the exporting system could scope it by, which is rarely the lane. A ledger written at the moment of the request is lane-exact, because the caller named the lane.
- Append only. There is no code that can edit a line already written, and no compaction
- A refused or failed attempt is a row too, worth zero units; a 401 or 403 at the door writes none
- A token count the provider did not report is null, never a plausible figure
# on the response x-vitna-lane: deep-research x-vitna-sku: anthropic/claude-opus-4-8 x-vitna-decision: 154 x-vitna-policy: ecb93b2a5c50… # on your ledger: the same values, and what happened { "lane": "deep-research", "decision": "154", "policy": "ecb93b2a5c50…", "serve": "primary", "sku": "anthropic/claude-opus-4-8", "outcome": "served", "units": 1, "inputTokens": 812, "outputTokens": 140 }
From a signed file to a served lane.
Five steps. They are the same on a laptop, on a box, or in the container image on your own cloud account, where the one difference is the inbound key in step three.
- 01
Get a signed policy and its key
Signed in to your organisation, open /console/deployment, ask for a signed policy, and download
policy.jsononce it is signed. The page prints the key that signed that file. Pin that one, not the key over the daily roots on/witness, which signs the record and not your policy.VITNA_POLICY=/etc/vitna/policy.json VITNA_PUBLIC_KEY=MCowBQYDK2VwAyEA...
- 02
Install it
From npm, on Node 22.13 or later. It puts
vitna-runtimeon your path, besidevitna-runtime-profile, which reads the ledger back, andvitna-runtime-push, which sends closed days only when you run it.npm install -g vitna-runtime - 03
Configure it, and start it
The policy, its key, a ledger path and a key for each provider your lanes name. It listens on
127.0.0.1:8787and asks callers for no key. Listening anywhere else, the container included, it refuses to start withoutVITNA_INBOUND_KEY, which every/v1request then sends as a bearer.VITNA_POLICY=/etc/vitna/policy.json \ VITNA_PUBLIC_KEY=MCowBQYDK2VwAyEA... \ VITNA_LEDGER=/var/lib/vitna/ledger.jsonl \ ANTHROPIC_API_KEY=... \ vitna-runtime
- 04
Send the first request
Point any SDK's base URL at
http://127.0.0.1:8787/v1and sendvitna/<lane>where it wants a model name. A name without the prefix is forwarded untouched and marked unrouted, so a service already running can move one lane at a time.vitna-runtime · 127.0.0.1:8787 curl http://127.0.0.1:8787/v1/chat/completions \ -H "content-type: application/json" \ -d '{ "model": "vitna/deep-research", "messages": [{ "role": "user", "content": "…" }] }'
127.0.0.1, port 8787, by default: the address rather than localhost, because the runtime listens on IPv4 loopback only. A base URL that already ends in /v1 works too, because /chat/completions answers the same.
from openai import OpenAI client = OpenAI(base_url="http://127.0.0.1:8787/v1", api_key="local") client.chat.completions.create( model="vitna/deep-research", messages=[{ "role": "user", "content": "…" }], )
The model field names a lane, and the API key is the runtime's, never a provider's: on loopback any value does, and with VITNA_INBOUND_KEY set it is that key. Everything else is the SDK you already have, including the errors: a provider's own error is returned as the provider said it.
from anthropic import Anthropic client = Anthropic(base_url="http://127.0.0.1:8787", auth_token="local") client.messages.create( model="vitna/deep-research", max_tokens=1024, messages=[{ "role": "user", "content": "…" }], )
Anthropic's dialect, at the same lanes, for a client that speaks only that one. A lane routes and writes its row exactly as on /v1/chat/completions. The SDK's x-api-key is not read, so the key goes in as an auth token, which it sends as a bearer.
client.chat.completions.create( model="vitna/support-triage", messages=[…], stream=True, ) # One row per request either way. Nothing is estimated: # a provider that reported no usage gets nulls.A same-dialect route is forwarded byte for byte. An Anthropic-direct lane is translated into chat completion chunks, and the usage, which that dialect splits across two events, is held and recorded together.
client.chat.completions.create( model="vitna/deep-research", messages=[…], extra_headers={ "x-vitna-cohort": account_id }, ) # bucket = FNV-1a(cohort) % 100 < share # The same request always lands the same way, and the # ledger carries the bucket so it can be recomputed.Without a cohort key a share is a share of requests, so two requests from one person can land on different sides. Send a stable id and the share becomes a share of whatever that identifies. It is the one header that reaches routing.
- 05
Check it
/healthzneeds no key and says only that it is up, and which version./status, with the key where one is set, lists the lanes it can serve and by which route, and the ones it cannot and why.curl http://127.0.0.1:8787/healthz { "ok": true, "version": "0.2.0" }
Installing the runtime covers the container image and a policy set as a secret, and Serving a lane every variable it reads.
One lane first, then the estate.
Three situations the runtime was built for, in the corpus's own words, and a fourth below it: a lane served from your own machine.
A lane whose model changed
The decision named a different sku. The policy is re-emitted and signed, the file lands on the box, SIGHUP re-reads it (where the policy is a secret, updating the secret restarts the process instead), and the next request serves the new one. No deploy of your application, and every row afterwards names the decision that authorised the change.
A lane that needs cover
A chain registered under the lane's standing accepted decision, walked only when a provider cannot serve the request now: a transport failure, a rate limit, the provider's own 5xx, Anthropic's 400 for an account with no credit left, or a time budget that ran out before anything reached the caller. Every entry names the decision it was registered under, so a fallback serve is still an attributable serve.
Moving off a gateway you already run
Point one base URL at the runtime and move lanes over one at a time. A model name without the prefix is forwarded untouched and marked unrouted, so the services you have not moved yet keep working exactly as they did.
A lane can point at your own machine.
A lane whose provider is local or anchor resolves with no API key and serves from the OpenAI-compatible server VITNA_LOCAL_ENGINE_URL names, which in 0.2.0 defaults to 127.0.0.1:8765, the port Anchor's own daemon listens on. It overflows the other way round from a cloud lane: a prompt longer than VITNA_LOCAL_MAX_CONTEXT_CHARS, or a first token slower than VITNA_LOCAL_MAX_TTFT_MS, hands that turn to the chain. Both are thresholds you declare, and neither is a judgement the runtime makes on its own. The next release, not yet published, drops the default: a local lane will be unreachable until the variable names a server, as a lane with no key is.
Every routing shape, one base URL.
The runtime answers two dialects at one base URL: OpenAI's chat completions, because that is the one every SDK already speaks, and Anthropic's messages, for the clients that speak only that one. The request shape, the response shape and the errors are the ones you already handle. What changes is the model field, which names a lane instead of a model.
POST /v1/chat/completionsPOST /v1/messagesmodel: "vitna/<lane>"- Checks Ed25519 signature on
policy.json - Picks primary SKU + ordered fallback chain
- Appends 1 JSONL row per attempt on disk
Anthropic, OpenAI, Google, DeepSeek, billed directly to your own keys.
Chain failover on 429/5xx, or local VITNA_LOCAL_ENGINE_URL.
- POST /v1/chat/completionsOpenAI's dialect
- POST /v1/responsesOpenAI's Responses dialect
- POST /v1/messagesAnthropic's, tools translated
- GET /v1/modelsServable lanes and models
- POST /v1/embeddingsVector embeddings
- POST /v1/rerankCohere, Voyage, Jina rerank
- POST /v1/audio/transcriptionsMultipart audio transcription
- GET /statusLanes, routes, counts
- GET /healthzUp, and which version
A lane routes and writes its row identically whichever endpoint asked. A request on /v1/messages that names a model rather than a lane goes to Anthropic as it was written, where your Anthropic key can take it there, so thinking and prompt caching work as they do direct.
- OpenAIDirect adapter
- AnthropicDirect adapter, translated
- Everything elseOne substrate, OpenRouter
Vitna decides what model. Which of your accounts serves it is your own operational fact, so it comes from the environment rather than from the record. A forced route that cannot be taken is unreachable rather than quietly becoming the other one: an operator who wrote down direct has said something about committed spend or data handling, and a silent reroute would break it.
A decision, applied per request.
Four things the runtime does, each written down in the corpus before it was drawn here. The boundary first, because it is the claim the rest rests on; failover last, because it is the case you hope never runs.
Your keys. Your accounts. Your traffic.
A consumer that fetched its routing from us at request time would have made our availability a factor in its own. So there is no fetch. The answer to where this request should go was signed into a file before the request existed, and the process that reads it holds no address for us at all.
- No fetch at request time, so none of our uptime in yours
- The route was signed into a file before the request existed
- The serving process holds no code path to vitna.ai
Rules are declared before they route.
The per-request question, answered without an oracle: a declared predicate on an observable request attribute, routing to a named sku, shadow first.
- Predicates on what the runtime can count, never on what a request means
- A character threshold is counted exactly. No token is estimated to reach it
- Every rule is born shadow: it routes nothing and records what it would have served
A canary you can recompute.
A traffic share is the rung this register was missing. It changes none of the epistemics: born shadow, promoted only under an accepted decision whose brief cites its shadow readings, removed by a dated row that is kept. What changes is that the promoted form may route five percent instead of all of it.
- The bucket is FNV-1a of a cohort key, so the same request always lands the same way
- Every row carries the bucket, so a reader can recompute which arm it belonged to
- Without a cohort key a share is a share of requests, and the reading says so
A chain a person registered.
A fallback is the first thing this register holds that serves production traffic without a decision having chosen it for that request. So the question is not which model, but who said this model may ever answer for this lane. The answer is a column: every entry names the accepted decision it was registered under, and every request it serves carries that decision on its row.
- Walked when a provider cannot serve now: a transport failure, a 429, a 5xx, a hang before the first byte, or Anthropic's no-credit 400
- Re-deciding the lane retires the chain, and the emitter refuses rather than shipping it
- Taking an entry out keeps the row, dated, because a fallback that served during an incident is part of what happened
Three places a model choice can live.
The column that matters is the second. A gateway is a service that has to be up for your request to succeed; the runtime is a process you run, so the only availability you inherit is the one you were always going to inherit.
| Capability | Direct SDK | Vitna runtime | Hosted gateway |
|---|---|---|---|
| Where the request goes | Your provider | Your provider | The gateway, then your provider |
| Whose uptime yours includes | The provider's | The provider's | The provider's and the gateway's |
| Who holds the provider key | You | You | The gateway |
| What chose the model | Whatever is in your code | An accepted decision | A console setting |
| Changing it | A deploy | A signed file: SIGHUP, or a restart where it is a secret | A console change |
| Failover | Build it yourself | A registered chain, one row per attempt | Vendor-dependent |
| Per-request record | Build it yourself | One line per attempt, on your own disk | The vendor's, by export |
| What a row is attributable to | Nothing | Lane, decision, policy digest | Vendor-dependent |
| A token count the provider did not report | Absent | Null, never estimated | Vendor-dependent |
| Dependencies to review | Your SDK's | None | The vendor's surface |
A hop in the path is a hop you can lose.
A gateway does not have to be unreliable to cost you something. It has to be up for your request to succeed, and its availability multiplies with your provider's rather than replacing it. That is arithmetic, and it is the same arithmetic however good the vendor is.
Arithmetic on a stated assumption, not a measurement of any vendor: a year is 525,600 minutes, and an added hop at each availability is unavailable for that share of them. The runtime adds no hop, because it is the process making the call rather than a service between you and it.
Where it runs, and what it does when something is wrong.
Each row is a property of the published package, written down in its docs. No throughput or latency figures are published for the runtime: nothing on this page measures it under load, and what a request takes is your provider's time plus your own machine's.
Where it runs
- Node
- 22.13 or later. Plain
.mjs, no build step. - Install
- npm, as
vitna-runtime0.2.0, or the container imageghcr.io/convexityos/vitna-runtime, tagged 0.2.0. - Where
- A laptop, a box, or your own cloud account. Your keys stay in your account and Vitna is not in the request path on any of them.
- Listens
127.0.0.1:8787by default, where no key is asked for. Anywhere else, the container included, it refuses to start withoutVITNA_INBOUND_KEY.- Providers
- OpenAI and Anthropic directly, everything else through OpenRouter, each on your own key.
- Dependencies
- None. A test checks the published file list against every import the entry points reach, so one cannot arrive unnoticed.
- A hang
- Cut at budgets you set: by default nine minutes for a completion, and five for a stream's first chunk or a silence inside it.
- A restart
- Drains for up to 30 seconds, so give whatever sends SIGTERM 35.
When something is wrong
- Refuses to start unsigned
The policy is verified against a key you pinned once, out of band, rather than the key that came with the file. Checking a signature against its own key proves only that the file agrees with itself, which anyone who can write a file can arrange.
- Fails static
A reload that cannot be verified changes nothing. The running policy stands, the refusal is logged, and status counts it, because adopting an unverified document routes traffic nobody signed for and refusing to serve turns a bad file into an outage.
- A stale policy is reported, never enforced
A runtime that stopped serving because its policy was old would convert a control-plane outage into a data-plane one, which is the exact coupling this design exists to refuse.
- Per-lane status, read and never enforced
What each lane has served, refused, failed and failed over since the process started, with the tokens each spent. Nothing is refused for exceeding anything: a gateway that starts dropping production traffic at month end is a page at 2am that we wrote.
- An allowlist a chain cannot reach past
A provider outside the allowlist is unreachable by every route, including the substrate, including as the last entry of a chain. An allowlist a chain could reach past is not an allowlist.
- Refusals by name, not by dropping
A field the Anthropic translation does not carry, such as response_format, is refused rather than quietly removed. A caller who sent it, had it dropped, and got an answer that ignored it has been given a wrong answer that looks like a right one.
- Names are looked up, never derived
The record registers claude-opus-4-8 and the substrate lists anthropic/claude-opus-4.8. Both are signed into the lane, so which name goes on the wire is a lookup rather than a rule that will one day be wrong.
The software is free. Your model use is billed by your providers.
Vitna is never in the request path, so there is no call to take a percentage of. What Vitna charges for is the register that decides the policy, priced per workload and never per token.
- VitnaNothingThe runtime
Apache-2.0, on every plan. No fee per request and no share of spend: no request of yours reaches us.
- Vitna$0Free, the decision plan for 1 workload
Public intelligence, open-source runtime, starter web data limits, and 1 active workload.
- Vitna$79 a monthPro, the decision plan for 5 workloads
The payment processor is not switched on yet, so Deploy starts as a conversation: talk to us.
- Your providersTheir ratesModel use, on your own keys
Billed to your accounts at their rates, including a request the runtime timed out, a caller left or a restart drained, since a provider keeps what it generated before the abort reached it.
- YouYour ownThe machine it runs on
A laptop, a box or a cloud account of yours. Vitna hosts nothing here and bills nothing for it.
Every product's costs, side by side, are on the pricing page.
Before you run one.
How policies load, how failovers behave, and what stays on your disk.
What do I need before I install it?
Node 22.13 or later, a key for each provider your lanes name, and a signed policy with the key that signed it, which /console/deployment gives an owner of your organisation once a workload carries an accepted decision. Installing the runtime walks through each.
To try the same package with no policy at all, Relay (vitna-relay) serves exactly the model you name, on your own keys.
Which keys does it hold, and what does my SDK send it?
Your provider keys, read from its environment and sent to their own provider and nowhere else. /status prints each as set or unset, never a value and never a prefix of one.
On 127.0.0.1 it asks callers for no key, so any non-empty value satisfies an SDK that insists on one. Anywhere else, every /v1 request sends VITNA_INBOUND_KEY as authorization: Bearer, which is where an OpenAI SDK already puts its key. An Anthropic SDK sends its key as x-api-key, which the runtime does not read: give it the inbound key as an auth token instead (ANTHROPIC_AUTH_TOKEN, or authToken in code).
The policy key is pinned once, out of band: the one /console/deployment prints beside the file, not the key over the daily roots on /witness, which signs the record and not your policy.
What leaves my machine?
Your requests, to your providers, on your keys. The ledger stays on your disk and holds no prompt and no response.
Nothing reaches Vitna unless you run vitna-runtime-push, a separate command that nothing schedules until you do. It sends served units per lane per closed UTC day, mapped to workloads through the policy, with the counts and latencies beside them, and never a prompt, a response or a price. vitna-runtime-push --dry-run prints the exact payloads first, holding no key and reaching no network. Pushing needs a key Vitna mints for your organisation: ask for one.
Does the runtime call vitna.ai?
No. Not at boot, not per request, not on a timer. There is no endpoint that serves a policy to a process, and there will not be one, so we can be entirely unavailable and every request keeps routing.
Pushing closed days of the ledger back to the record is a separate command an operator schedules, opt-in and off by default. The serving process holds no code path to vitna.ai with push enabled or without.
Does it retry?
Never the same model. A second attempt is a second serve, it gets its own ledger row, and it only happens when a chain names one.
A 4xx stops at the first attempt, and a 401 is deliberately on that side of the line: asking a second model the same wrong question spends money to be told the same thing twice, and failing over on a bad key would serve from the chain indefinitely while the real fault stayed invisible.
Two cases fail over that would otherwise stop. Anthropic reports an account with no credit as a 400, so that one 400 walks the chain, and its row names it credit_exhausted. And a provider that hangs past its budget before anything reached you is a provider that cannot serve now; one that goes quiet after the answer began is ended rather than spliced to a second model's.
What happens when a model goes down and the chain is exhausted?
It returns the last failure. Nothing is invented in its place, and no model is substituted for the one a decision named. A lane that cannot be reached is an error you see rather than a quiet reroute.
Can it choose a different model per request?
Only by a rule you declared, and only after a decision that cited that rule's shadow readings. A rule's predicate is written down, its terms are signed into the policy, and every request it touches resolves to a decision id.
What it will not do is run a classifier that picks per request. That is a decision made a million times a day with no record, no threshold anybody wrote down, and no brief anybody can regenerate.
I already run a gateway. Do I need this?
Probably not. A team with a gateway already has somewhere to put a decision, and config mode costs them no runtime footprint at all: the decision arrives as a fragment loaded into a variable that gateway already reads.
The runtime is for a stack with nowhere to load one into.
What does it add to what a request costs?
Nothing, because nothing of yours transits our infrastructure. You call your providers with your own keys on your own accounts, and we never see the request, so there is no call to take a percentage of.
Where do I get help?
Talk to us. Support is best effort on every plan, with no service level, and the docs are the reference: Serving a lane lists every variable it reads and every refusal it answers.
Start with one lane.
Install it, point one base URL at it, and move the rest when you are ready. The lanes you have not moved pass through untouched, and the ones you have write a row you own.
