> Source: https://vitna.ai/docs/runtime/harness
> Raw Markdown: https://vitna.ai/docs/runtime/harness.md
> Corpus index: https://vitna.ai/llms.txt
# Putting a coding harness on a lane
*An operator note.* The launcher is not in the published package: it runs from
a checkout of Vitna's private repository, as does the local lane it looks for.
Outside Vitna, point the harness at a runtime you [installed](installing.md)
yourself, with the base URL [Serving a lane](serving.md) gives.
A coding harness is the cheapest way to make a lane carry real traffic, because
it is traffic somebody was going to generate anyway. One command starts one
with its environment pointed at a runtime you are already running, and every
turn of the session lands on the lane and leaves a [ledger](ledger.md) row.
```bash
npm run harness:start -- opencode --lane deep-research
```
It needs a runtime answering first. [A lane on your own machine](local.md) is
the shortest way to one and lands on the port this command already looks at:
```bash
npm run runtime:local
```
[Serving a lane](serving.md) is the other way, and the launcher cannot tell
them apart. It asks whatever is answering what it serves, rather than reading a
policy a second time, so a lane it offers you is a lane that will answer.
## What it is, and what it is not
It is a wrapper. It sets the environment a harness reads, and everything else
you typed reaches the harness in the order you wrote it. It parses no harness
flags, forwards no requests and sits in no request path.
| Flag | Meaning |
|---|---|
| `--lane <alias>` | Which lane the session runs on. Required. |
| `--url <base>` | The runtime. Default `http://127.0.0.1:8787`. |
| `--print` | Shape the whole launch, print it, start nothing. |
| `--list` | Name each harness and where it reads its configuration. |
| `--context-window <n>`, `--max-output <n>` | Override what the harness is told the model can hold. |
| anything else | The harness's, untouched. |
A bare `--` ends the launcher's reading entirely, which is the escape for the
day a harness ships a flag of its own called `--lane`.
## The harnesses
Two, and a third is a decision rather than a default. Each entry is a promise
to keep following somebody else's releases, so the list is short on purpose.
| Harness | Install | Configured through |
|---|---|---|
| [opencode](https://opencode.ai) | `npm i -g opencode-ai` | `OPENCODE_CONFIG_CONTENT`, a whole config document in the environment |
| [Crush](https://github.com/charmbracelet/crush) | `npm i -g @charmland/crush` | `CRUSH_GLOBAL_CONFIG`, a directory holding `crush.json` |
| [Claude Code](https://claude.com/claude-code) | `npm i -g @anthropic-ai/claude-code` | its environment; no configuration file is written |
Neither file on your disk is read, replaced or edited. opencode merges the
document in the environment last, after its global config and the project's
own; Crush is pointed at a temporary directory that is removed when the session
ends.
**Both are told the lane twice**, as the model and as the small model. A coding
harness asks a cheap model for titles and summaries between turns, and a small
model left pointing somewhere else is a request that never reaches the runtime
and leaves no row, which makes a session look smaller than it was.
## Which session a row belongs to
Every request a launched session makes says who it was for, so its rows can be
totalled as one session rather than picked out by time and lane. The launcher
tells each harness to send two headers the runtime records on every row
([the request](serving.md#the-request)): `x-vitna-agent`, which is `harness:`
and the harness's id (`harness:opencode`, `harness:crush`, `harness:claude`),
and `x-vitna-run`, a new id for each launch. The launcher prints both before the
harness starts.
| Harness | Told through |
|---|---|
| opencode | `headers` in the provider's `options`, which opencode hands to the provider it loads |
| Crush | `extra_headers` on the provider |
| Claude Code | `ANTHROPIC_CUSTOM_HEADERS`, one `Name: Value` per line |
A real opencode 1.18.35 session and a real Claude Code 2.1.283 session, run
against a real runtime with only the provider stubbed, left rows carrying both,
the small model's included, and the provider was sent neither. Crush was read
from its source at v0.100.0 rather than run. The colon keeps a harness apart
from a routine: a routine's id is lower case letters, digits and hyphens, so a
routine named `opencode` is never counted as the harness.
## What the harness never gets
Two mechanisms, and the point of having both is that neither is sufficient.
**Its environment has every provider credential removed.** Anything named
`*_API_KEY`, `*_AUTH_TOKEN`, `*_API_TOKEN`, `*_SECRET_KEY`, `*_ACCESS_KEY` or
`*_CREDENTIALS`, the AWS and Google credentials that are not shaped like that,
and the whole of `VITNA_*`, which is where the signing key and the push key
live. What was withheld is printed by name and never by value, the same rule
`/status` follows for the keys the runtime does hold.
The shape is deliberately wider than the model providers, and that has a cost
worth knowing: a key for something that is not a model at all, a sandbox or a
deployment target, matches it too, so a harness tool that wanted one finds it
missing. That is the right way round for a launcher whose whole point is that
the runtime holds the credential relationship, and it is not silent. Every
launch prints the list.
**And the harness is told to load no provider but this one.** That is
`enabled_providers` for opencode and `CRUSH_DISABLE_DEFAULT_PROVIDERS` for
Crush. This is the half that matters, because clearing the environment cannot
reach a credential the harness already stored on disk under its own account.
What it gets instead is `VITNA_LANE_KEY`, whose value says in its own words
that it is not a credential. A runtime started without `VITNA_INBOUND_KEY`
reads no inbound authorisation at all, so the value is arbitrary; sending
nothing is not an option, because a harness with no key configured decides its
provider is not set up and never asks it anything.
That makes this command one for a runtime on loopback, which is where one
listens by default. A runtime with an inbound key (see
[the front door](serving.md#the-front-door)) answers this command's `/status`
read with its version and nothing else, and refuses the placeholder on `/v1`,
so the command says the runtime serves no lane. Carrying the key through is not
built yet.
## Where the numbers in its config come from
Both harnesses want a context window, an output ceiling and a price per million
tokens. The window and the ceiling decide when the harness compacts its own
history; the price is what it shows you at the end of a session.
They come from the record. The launcher reads what the runtime says the lane
resolved to and looks that model up in the catalogue by its exact id, so a
session priced in a harness's status bar is priced from a figure with a date on
it rather than from a table its author last updated at some point.
**A lane routed direct will miss**, and the launcher says so rather than
finding a lookalike. A direct lane sends the provider's own name for a model
and the catalogue is keyed by OpenRouter's, and turning one into the other is a
lookup the record makes rather than a rule anything may apply, which is what
[Model ids](../routing/model-ids.md) is about. On a miss the window and the
ceiling are the launcher's own defaults, named as defaults, and the prices are
zero rather than a plausible number. Zero is visibly not a price. A guess is
not visibly anything.
## Tools, and the one lane shape that will not work
A coding harness sends `tools` on every turn. The OpenRouter and OpenAI direct
routes forward the body as it arrived, so tool calling works on those today.
The Anthropic direct route translates, and it refuses `tools` by name rather
than dropping them, for the reason [Serving a lane](serving.md) gives: a caller
who sent tools, had them dropped and got an answer produced without them has a
wrong answer that looks like a right one. So **an Anthropic direct lane will
refuse the first turn of any harness session.** The launcher warns when a lane
routes direct. `VITNA_ROUTE_ANTHROPIC=openrouter` on the runtime moves it to the
substrate, which speaks the dialect natively.
## Codex
It cannot reach a lane, and it is named by the launcher rather than left out of
it. Codex stopped speaking this dialect: `wire_api = "chat"` was removed and is
now refused by name, the only value its provider config takes is `responses`,
and the runtime serves `POST /v1/chat/completions` and has no `/v1/responses`.
The removal was announced on 2025-12-09 for early February 2026, and a version
without it is 0.84.0 (read from `openai/codex` at rust-v0.154.0 and its
discussion 7782, retrieved 2026-09-10).
It needs an inbound Responses dialect this runtime does not have. Pointing it at
a vendor's own compatible endpoint would bypass the runtime and write no ledger
row, which forfeits the whole point.
Claude Code was in this section for the same shape of reason, needing an inbound
Anthropic dialect. The runtime serves `POST /v1/messages` since 2026-09-10, so it
is in the table above instead.
## Claude Code, and what running it found
Its entry was checked against 2.1.267 by running it, which is worth saying
because running it is the only thing that could have produced any of the
following. Nothing here comes from a published description of that dialect.
**It sends three fields nothing documents.** `thinking`, as
`{"type":"adaptive"}` rather than a token budget, `context_management`, and
`output_config`. All three were refused by name, which is the runtime working as
designed and also a session that cannot make one request.
**Two of them turn off together**, which is why the launcher sets
`MAX_THINKING_TOKENS` to `0` and says so when it starts. The
`context_management` this harness sends is an instruction to clear thinking
blocks, so a session with no thinking has nothing to manage.
**The third cannot be turned off**, so the runtime learned it.
`output_config.effort` is a level, and the dialect the runtime forwards has the
same three levels under the name `reasoning_effort`, so that one is a lookup
rather than a guess. A level outside `low`, `medium` and `high` is still refused.
**It puts a `system` message inside the messages array**, which the Anthropic
dialect documents as carrying user and assistant turns only. It carries the
agent-type listing. The runtime carries it in place.
Extended thinking being off is the one thing a session on a lane does
differently from a session against the vendor, and the launcher prints it every
time rather than leaving it to this page.
## Adding a third
One entry in `platform/harness/launch.mjs` naming the command, how it is
installed, and what it is told. There is no discovery and no generic mode, and
that is the design rather than an omission: a launcher that pointed any binary
at a base URL would be claiming support for harnesses nobody has run.
What costs the day is not the entry. It is finding out where that harness reads
its configuration, what it calls a model, and whether it insists on a live
model list. The runtime serves no `GET /v1/models`, so a harness that asks for
one has to be told not to. Crush asks whenever its model list is empty or
discovery is on, which is why its entry declares its models and sets
`discover_models` to false.
## Windows
The launcher resolves the command on `PATH` itself, honouring `PATHEXT`, so a
harness that is not installed is said in the launcher's words with the install
line rather than as a spawn error.
A harness installed by npm is a `.cmd` shim rather than an executable there,
and a shim has to be handed to the command interpreter, which parses the
arguments a second time. The launcher builds that command line itself rather
than letting a shell do it, so an argument carrying a space or a quote arrives
whole.
One thing it cannot carry: a `%`. There is no escape for one on a command line
as there is inside a batch file, and it is expanded inside quotes as well as
outside. An argument containing one is refused by name rather than delivered
changed.
## What it refuses
| Refusal | Why |
|---|---|
| A harness it does not know | It starts two, and each further one is an ongoing obligation rather than a default |
| Codex | Named with the reason above, because it is the wrong answer to a reasonable question |
| Nothing answering at the runtime's URL | With the line that starts one |
| A lane the runtime does not serve | With the lanes it does serve |
| A lane the runtime carries and cannot serve | With the runtime's own reason, usually a missing key |
| One of its own flags given no value | Rather than guessing at one |
| An argument a Windows command line would change | Named, rather than passed through wrong |
## Seeing it without starting anything
```bash
npm run harness:start -- crush --lane deep-research --print
```
The whole launch: every variable added, every variable withheld by name, the
config document as the harness would receive it, and the command line that
would have run. Nothing is started and no harness needs to be installed.