vitna.ai/docs/runtime/installing Machine view
Raw .md llms.txt
> Source: https://vitna.ai/docs/runtime/installing
> Raw Markdown: https://vitna.ai/docs/runtime/installing.md
> Corpus index: https://vitna.ai/llms.txt

# Installing the runtime

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](relay.md) 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`](../api/v1/verification/keys.md). A CI job with
no session collects the same file with an org key from
[`/api/v1/artifacts`](../api/v1/engine/artifacts.md).

## 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](relay.md);
`vitna-route`, which handles [per-request model and effort routing](route.md);
`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](ledger.md) and prints
[what your traffic consumes](profile.md) reaching no network at all; and
`vitna-runtime-push`, which [sends that ledger's closed days back](pushing.md)
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](serving.md#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](serving.md#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](overview.md) 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](ledger.md) 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](pushing.md) 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](../routing/outcome.md). It is the same
reading [`aperture:usage:import`](../routing/usage-import.md) 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](https://vitna.ai/start#contact). The record keeps only its sha256, and
[/console/settings](https://vitna.ai/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.
Human Machine Shift+M