Get started

Installing the runtime

Source

Getting from nothing to a served lane, on your laptop, your box, or your own cloud account.

Everything below is the version where you hold the key: the published package, a signed policy and the key that signed it. To run it with no policy at all, serving every request as the model it names, start Relay instead, which is the same package.

The two things it needs, and where they come from

A signed policy and the key that signed it. Both come from /console/deployment, signed in to your organisation:

  1. An owner presses Ask for a signed policy. The signer runs every five minutes, so the policy is ordinarily signed within about six minutes of the ask; until then the page says the ask is waiting, and says so again if it has waited longer. Where no key is registered to sign policies yet, GET /api/v1/keys answers "policyKey": null, nothing is signed, and the page says so and offers no ask until one is.
  2. Beside the signed policy, Download policy.json saves the file, exactly as it was signed.
  3. The page prints the two lines to give the runtime, with the key that signed that file:
bash
VITNA_POLICY=/etc/vitna/policy.json
VITNA_PUBLIC_KEY=MCowBQYDK2VwAyEA...

Pin the key the page prints beside the file, not the key over the daily roots on /witness, which signs the record and not your policy. Every key and what it signs is at `GET /api/v1/keys`. A CI job with no session collects the same file with an org key from `/api/v1/artifacts`.

From npm

bash
npm install -g vitna-runtime

Or without installing anything:

bash
npx vitna-runtime

A global install puts seven commands on the path: vitna-runtime, which serves signed lanes; vitna-relay, which serves with no policy; vitna-route, which handles per-request model and effort routing; vitna-runtime-prove, which checks one real serve against its ledger row; vitna-runtime-lock, which verifies a signed policy and lockfile in CI; vitna-runtime-profile, which reads the ledger and prints what your traffic consumes reaching no network at all; and vitna-runtime-push, which sends that ledger's closed days back when, and only when, you run it.

Started this way the runtime listens on 127.0.0.1 and asks callers for no key. To reach it from another machine, set VITNA_HOST and VITNA_INBOUND_KEY together: the front door covers both.

The package has no dependencies. It is plain .mjs under plain node, with no build step, because a gateway a customer trusts with every prompt is one a security review should be able to read in an afternoon. A test asserts that property rather than claiming it: the published file list is checked against the closure of every import from the entry points, so a dependency cannot arrive without failing a build.

From the container

bash
docker run --rm -p 8787:8787 --stop-timeout 35 \
  -e VITNA_POLICY=/etc/vitna/policy.json \
  -e VITNA_PUBLIC_KEY="$(cat policy-key.pub)" \
  -e VITNA_INBOUND_KEY="$VITNA_INBOUND_KEY" \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -v "$PWD/policy.json:/etc/vitna/policy.json:ro" \
  ghcr.io/convexityos/vitna-runtime:latest

The image is built by packing the same whitelist npm publishes, so what it holds is what the tarball holds. Nothing of the record or the site is in it.

The image refuses to start without `VITNA_INBOUND_KEY`. A container port is reached from outside the container, so the image listens on every interface, and a runtime reachable from a network with no key would spend your provider keys for whoever found it. Generate one (openssl rand -hex 32), and send it as your SDK's API key: every /v1 request carries it as authorization: Bearer <key>. A health check needs none.

`--stop-timeout 35` is what lets a restart drain. docker stop sends SIGTERM and then SIGKILL ten seconds later unless told otherwise, and the runtime drains for up to 30 seconds (see restarting). Compose spells it stop_grace_period: 35s, and Kubernetes terminationGracePeriodSeconds: 35.

On your own cloud, which is Deploy

Deploy is the runtime on infrastructure you own, provisioned by tooling Vitna publishes. Your keys stay in your account and Vitna is not in the request path, exactly as when you run the process yourself. It is not a hosted gateway, and the modes table is exact about the difference.

Save this beside your policy as fly.toml and change the app name. It is the recipe Vitna keeps working, printed whole here because nothing else needs to be downloaded:

toml
app = "my-vitna"
primary_region = "iad"

kill_timeout = 35

[build]
  image = "ghcr.io/convexityos/vitna-runtime:latest"

[env]
  VITNA_PORT = "8787"
  VITNA_HOST = "0.0.0.0"
  # VITNA_LEDGER = "/data/ledger.jsonl"

[http_service]
  internal_port = 8787
  force_https = true
  auto_stop_machines = "suspend"
  auto_start_machines = true
  min_machines_running = 1

  [[http_service.checks]]
    grace_period = "5s"
    interval = "30s"
    method = "GET"
    timeout = "5s"
    path = "/status"

# [[mounts]]
#   source = "vitna_ledger"
#   destination = "/data"

kill_timeout is 35 because on SIGTERM the runtime drains for 30 seconds and then gives the requests it cut 2 more to write their ledger rows; Fly's default of five would cut every stream still open with no row at all. VITNA_HOST is every interface because Fly's proxy reaches the machine over its private network, which is what makes VITNA_INBOUND_KEY required below. The health check reads /status with no header, which answers { ok, version } and nothing else. A ledger that must outlive a restart needs a volume: fly volumes create vitna_ledger --size 1, then uncomment VITNA_LEDGER and the mount.

Then three commands:

bash
fly launch --copy-config --no-deploy --name my-vitna
fly secrets set VITNA_PUBLIC_KEY="$(cat policy-key.pub)" \
                VITNA_POLICY_B64="$(base64 -w0 policy.json)" \
                VITNA_INBOUND_KEY="$(openssl rand -hex 32)" \
                ANTHROPIC_API_KEY=...
fly deploy --image ghcr.io/convexityos/vitna-runtime:latest

Then point your SDK's base URL at https://my-vitna.fly.dev/v1, give it the VITNA_INBOUND_KEY you set as its API key, and name a lane.

An app deployed from this recipe before 0.2.0 has no inbound key, and because the recipe runs :latest, its next fly deploy boots a runtime that refuses to start until fly secrets set VITNA_INBOUND_KEY=... has run. Its health check needs no change: the recipe's check reads /status with no header, which still answers.

The image runs anywhere a container runs. Fly is the one path documented end to end; a second platform is documentation rather than code.

The policy as a secret

A machine provisioned from a console has no filesystem to copy a file onto, so the document may also arrive base64 encoded in VITNA_POLICY_B64.

This is a delivery, not a fetch. You put it there, no endpoint served it, and it is verified against the key you pinned by the identical path the file form takes. A policy signed by another key, or edited after signing, refuses to start here exactly as it does on a box.

Exactly one of VITNA_POLICY and VITNA_POLICY_B64 may be set. Both is refused at boot rather than ranked, because a precedence rule is a deploy that quietly serves the wrong document the day somebody forgets which one wins.

A reload re-reads whichever one is in play. A secret that has gone missing or gone malformed refuses the reload and the running policy stands, which is the same fail-static rule a half-written file gets.

Whether the readings come back, which is a decision to take here

The runtime writes its ledger locally whatever you decide. Sending those readings to Vitna is a separate command, and nothing schedules it until you do:

bash
vitna-runtime-push

That is a property of the software rather than a setting, and Pushing the ledger is where it is argued. The serving process holds no code path that reaches vitna.ai, with telemetry or without, so the claim that the runtime never calls home survives push existing. It stays true whichever way you answer this.

This page did not used to ask, which turned "off by default" into "never put to anybody". Those are different, and only the first was ever the commitment.

What answering yes buys. The register can then state what it told a workload to run *and* what the workload was observed running, so a decision's prediction stops being an intent and becomes something checkable against what actually served. It is the same reading `aperture:usage:import` takes from a file you export by hand, arriving with less typing.

What it costs. One org-scoped push key, and a timer you install. Vitna mints the key for your organisation and it is shown once: ask for one through the contact form. The record keeps only its sha256, and /console/settings lists the keys your organisation holds. It goes in VITNA_PUSH_KEY on the box that will push, and authenticates that org's workloads only.

What goes, and how to see it before deciding. Served units per lane per closed UTC day, mapped to workloads through the policy. No prompt, no response, no content of any kind. You do not have to take that from this page:

bash
vitna-runtime-push --dry-run

shapes and prints the exact payloads, holding no key and reaching no network. Read them, then answer.

What answering no costs, stated so the choice is informed rather than cautious: the register holds what it decided and never learns what happened, so the outcome comparison above has nothing to read for that workload, and the evidence behind the next decision stays whatever somebody typed in by hand.

Licence

The runtime is Apache-2.0. The record, the collector and the emitting half of the engine are not published and are not covered by that grant.

The published paths include the policy parser and its canonical form, which is deliberate: a policy signed with your own key verifies against whatever key your runtime pinned, so the executor runs with no Vitna in the picture at all. That is the architectural claim written as a licence term rather than a promise.