harness.yml

A harness declares its configuration once, as a table of keys. harness.yml is the committed manifest of those keys; everything here is read off the tables the keys are declared in — the model family every harness ships (modelSettings) and the template’s own — so the file that disagrees with this page is the one to read.

Where a value comes from

Every declared key is resolved through the same four rungs, highest first, and the rung that supplied it is reported beside it as its provenance — what the dev pane’s Settings tab shows next to each value.

Two more provenances appear without being rungs: session, a value patched in memory by a served session that no file will remember, and cli, a flag name a key may declare for a boot that passes overrides — the shipped boots pass none.

An empty string is a clear at every rung: the value comes from the rung beneath. A key declared as a path is expanded (~) and made absolute at the boundary — against the project for a value from either file or the default, against the process for one set in the environment.

targets: [cli, desktop, web]

model:
  llm:
    id: qwen3.5-4b
    context: 32768
    branches: 5
  reranker:
    id: qwen3-reranker-0.6b-q8
  vision: {}

sources:
  outputDir: reports

defaults:
  effort: low
  guards:
    url_dedup:
      scope: cohort
    query_dedup:
      scope: cohort

The research template’s manifest as scaffolded. model is the family every harness ships; sources and defaults are this template’s own keys; targets is the scaffold’s.

The model family

One block per model, and the block’s presence is the request: naming a block under model: is what loads that model; removing it is how “I don’t need this” is said. Its keys are the selection — path outranks id. An empty block (vision: {}, or a bare vision:) is a request with nothing selected: a service with a derivation takes it (vision pairs from the llm), and one without is refused, naming the key to add (reranker: {} → “set model.reranker.id or model.reranker.path”). No selection key has a default; a tuning key may (model.reranker.context), and it stands only once its block is present — a default never requests a model.

Every key lives at the path the file names it by: model.llm.context is the key, the yml path, and the provenance name. Every block beside llm is a service: the guide has the lifecycle, what a bound one exposes, and how a new kind is added.

llm

The reasoning model and the one shared context every agent branches from.

Unset, context is 32768 and branches is 32; the KV cache is q4_0. Before a byte is fetched, the boot asks whether this machine can hold the catalog model it names: an edge model needs 10 GB of total memory, an appliance model 24 GB, and a box under the floor is refused with what it has and what it needs — a path: model is trusted by possession and not gated. The CUDA backend pack is the box’s, not a key: lloyal backends:install puts it there and writes gpu: cuda for you.

reranker

The pointwise judge the abilities score with. An ability that needs one says so in its manifest (services: ["reranker"]); the block is what provides it.

Unset, context is 16384. The reranker runs on its own context, at q8_0 KV precision — at q4_0 its verdicts invert on close pairs.

vision

The projector through which the reasoning model sees an image. The block with no id takes the projector the catalog pairs with the llm, so switching the llm switches the projector with it; a path: llm has no pairing and needs an explicit id or path.

embedding

The encoder a harness indexes with, one vector per text. A model’s pooling is its own property — Qwen3-Embedding reads its last token, nomic-embed averages — so a catalog id carries it and a local file must say.

Unset, context is 2048, which is the batch too: a text is encoded whole. A path: model with no pooling is refused at bind, naming the key. nomic-embed-text-v1.5-q4 is the one to reach for on an edge box: a tenth of the memory and a quarter of the latency of the Qwen encoder; Qwen recalls more of what the reranker would confirm and suits an appliance-class box.

The catalog and the slots

A catalog id is fetched on first launch into the project’s models/<block>/<id>.gguf slot and verified against the catalog’s digest, fail-closed: a truncated or tampered download is deleted, never loaded. A path is trusted by possession and never copied.

The CLI writes the selection for you: lloyal models:use <id> [--role llm|reranker|vision|embedding] writes the block’s id, lloyal models:add <path> [--role] its path, each replacing the other; lloyal models:list shows the catalog, your pins and what is on disk. An llm block that names neither and has exactly one .gguf in its slot adopts it; two is refused as ambiguous.

When a change applies

Each key declares when a change to it takes effect, and the settings pane offers a control only where one can do something.

Every key of the model family is reload or boot: the family describes the running residency, which a save cannot change, so it stays boot-frozen for the life of the process — what a session reports is what it runs. A served session saves in memory only (its keys read session) and cannot reload the runtime: the host chose its model when it started and serves every session from that one residency.

Your own keys

A template declares its configuration in src/config.ts: the model family spread in, then its own keys. The key is the path in the resolved config; the entry says where each rung reads it, what it takes, and what stands when nobody sets it. The Config and Origin types are read off the table, so a key added here is typed everywhere at once, and the dev pane lists it.

export const config = defineConfig({
  ...modelSettings,
  "sources.outputDir": {
    yml: "sources.outputDir", path: true, default: "reports",
    describe: "Where settled briefs, their annexures and the session trace are written.",
  },
  "defaults.effort": {
    yml: "defaults.effort", oneOf: ["low", "medium", "high", "ultra"], default: "high",
    describe: "How much a run may spend.",
  },
});
export type Config = ConfigOf<typeof config>;

Two rules the declaration enforces: version and the abilities family are the platform’s and cannot be declared, and a key cannot also be a family — model.reranker and model.reranker.id cannot both exist. A family holds keys; a scalar, an array or an object-valued key (defaults.guards) is one value, replaced whole.

The shipped templates’ keys

defaults.guards is the harness’s side of a gate an ability declared: url_dedup: { scope: cohort } widens the gate to every agent in the pool; url_dedup: false switches it off. The life of a tool call has the ability’s side.

The abilities family

Every harness carries abilities.<name>, declared by none: one entry per installed ability, holding whatever its manifest’s configSchema asks for. Committed entries come first, then the local overlay replaces a named ability’s entry whole and leaves the others; a value is resolved as a path when its key ends in Path or it begins with ~, / or .. An ability whose schema has required keys is not enabled until they are present, and its settings page says so. Values never ride the wire: the pane sees each key redacted to its presence, so a secret saved once is never read back.

abilities:
  corpus:
    corpusPath: ./docs

targets

targets: [cli, desktop, web] is the scaffold’s: which surfaces the project carries. The CLI reads it when it prunes a target you drop; the runtime never reads it. It is the one key at the top of the file that no table declares.

The box’s own settings

What describes the machine rather than the harness comes from the environment and nowhere else: one build serves many machines, and a committed manifest would ship one box’s numbers to all of them.

harness.json

The local overlay, beside the manifest: what the settings pane writes, at version 2, one block per model in the same shape as the manifest. It is written atomically with mode 0600 — it can carry a credential — and every save tightens a looser file; scaffolds ship it in .gitignore, and a save appends it there when it is not. A save carries only the keys it changes, merged into the families the table declares and replacing anything else whole, so a local overlay never pins an untouched value over the rungs beneath it.

A file written before 1.11 says "version": 1 and is refused, naming the fix: delete it and relaunch. A file at a version this runtime does not write is ignored by the loader and never rebuilt over by a save — nothing overwrites a newer runtime’s settings.

The manifest is the deploy; the overlay is the machine. Naming a model in either is enabling it.