Skip to main content
An agent is a named record, not a process XORCISE launches. XORCISE never starts your agent, never dials it, and never inspects it — you register a handle plus some optional metadata, and you connect your own agent to each run yourself.

​
What you’ll learn

  • Which fields an agent record holds, and which of them XORCISE actually reads.
  • What the harness field selects, and which three harnesses ship.
  • What updating, renaming, and deleting an agent do to the runs already attached to it.

​
What an agent record holds

Only the name is required. Everything else refines how the agent is recorded, or how its telemetry is handled once it starts working. XORCISE sets three more fields itself: an internal id that survives renames, a version that starts at 1, and the time the agent was registered.
The OTel endpoint is the field that misleads people. XORCISE keeps the value you type and never consults it — not at run creation, not by the receiver, and not by any adapter. The endpoint your agent must genuinely export to is computed per run and served by that run’s launch profile, because the correct address depends on which collector the run uses and on whether your agent runs on this host or inside a container.

​
Choosing a harness

A harness is the tool that drives your model and does the work — OpenHands, the Claude Code CLI, the Codex CLI, or something you wrote yourself. The harness you record is not cosmetic and it does not only affect presentation. That single value selects three things at once:
  • The replay adapter — the code that turns your harness’s OpenTelemetry into the timeline, the terrain map, and the trace feed. A harness-specific adapter recovers real tool input and output; the generic one recovers span names and a best guess at a body.
  • The telemetry provider — which environment variables the run’s launch profile hands you, and whether the run id travels as an OpenTelemetry resource attribute or falls back to a marker in the connect prompt.
  • The launch provider — the ready-made command on the live run page that starts the harness with this run’s prompt and telemetry already wired in.
Three harnesses ship, plus a generic floor that catches everything else. Pick one of the three when it matches what you actually run. Otherwise pick generic, which is also what an agent gets when you leave its harness out. Every agent has a harness, and generic is a supported configuration, not a broken one. The generic adapter still produces a usable timeline from ordinary spans, and it also covers an agent that emits no telemetry at all. It is verified against no harness, though, so the web UI says so when you pick it or leave the harness blank: runs replay with it as a best effort, and the span-support panel shows each kind of span as unknown, with an amber question mark, until you look at a run. Those four are the complete list. Any other value is your own label. XORCISE saves it, and warns you that no harness answers to it, naming the closest real harness when one is near. The CLI asks you to confirm before it saves. The web UI shows the warning before you save and again once the agent is saved, and the API returns it with the saved agent. A run of such an agent replays with the generic adapter unless its trace identifies a harness by itself. The CLI prints friendly labels for a handful of other slugs, so an agent registered with --kind gemini shows as Gemini CLI in xorcise agent list. Nothing is behind those labels — no adapter, no telemetry provider, no launch command — and such an agent replays through generic exactly as a generic one does. Do not read the label as support. Any other label is title-cased in the CLI, so my-agent-cli prints as My Agent Cli, and the web UI shows it as you typed it. An agent that an earlier release saved with no harness, or a blank one, reads generic once you run xorcise db upgrade. Its runs are not rewritten: each keeps the harness it was created with.
Holding the harness still is what makes several agents comparable. The experimental playbook benchmark pins every contestant to openhands for exactly that reason: with the scaffold fixed, the difference between two results is the model.

​
Running without telemetry

An agent that emits nothing still runs and still scores. Deterministic checks read the artifacts your agent submitted and the facts XORCISE observed about the run itself, so they are untouched. The judge still runs, on a prompt that says plainly that no trace exists, and any criterion it cannot evidence is left unscored: it counts as zero in the score, and the result carries an upper bound that grants that weight. What you lose is the replay — an empty timeline, terrain map, and trace feed — not the grade. How grading works has the arithmetic.

​
Agent versions and history

Every change to an agent bumps its version, and every result records the version the agent was on when that run was created. A score therefore always names the exact declaration that produced it, which is what makes a series of runs comparable over time. Renaming is safe. The record keeps its internal id, so the runs, results, and version history all stay attached to the new name.
The Agents page listing registered agents with their harness and run counts

The Agents page. Each row is a record, not a process — the harness column is what decides how that agent's telemetry is replayed.

​
Register an agent

Both interfaces create the same record, at version 1, immediately selectable when you create a run.
Only --name is required. --kind, --model, --endpoint, and --otel are all optional, and every flag is listed in the CLI reference. Leaving out --kind saves generic.
The CLI confirms the registration and names the next step:

​
Manage agents

List what is registered, change a declaration, review a track record, or remove an agent entirely.
update changes only the fields you pass and bumps the version; passing no field at all is refused rather than silently versioning the record.
Deleting an agent deletes its runs with it, and everything recorded for them: results, telemetry and each run’s directory under ~/.xorcise/runs/. They do not outlive the agent, and there is no undo — xorcise agent rm and Delete agent both cascade. xorcise agent history scout --json saves only the results; to keep the evidence as well, export first with xorcise run export --agent scout --out ./scout-export, which writes each run’s report, result, raw OTLP traces and events.
Removing an agent is refused while any of its runs is still running — terminate it first — or still being graded. Each finished run whose environment is still up is torn down before anything is deleted; if Docker or Headscale is down, the removal is refused with the reason unless you pass --force (Delete anyway in the web UI), which accepts that those containers or tailnet nodes may be left running.

​
Next steps

Missions

The other half of every run — what a mission contains, and where missions come from.