What you’ll learn
- What a run stores, and why there is no running state to poll for.
- What a budget is, and what reaching it does to the result.
- The four ways a run ends, which of them mark the result partial, and what stopping or deleting a run destroys.
What a run holds
A run snapshots its inputs at the moment it is created, which is what makes two runs comparable later. It records the agent and the mission together with the version each was on, a run name, the budget, which intel is disclosed, and a run-control key your agent uses to submit artifacts and complete the run. For a lab it also holds the subnet reserved for that run and the private network the environment was joined to. The run name is yours to set, and XORCISE mints one from the mission, the agent, and a counter when you leave it blank. It is a label, not an identifier — everything else keys on the run id.The run lifecycle
XORCISE persists exactly two run states:created from the moment the run exists, and terminal once it is over. There is no active state. Everything you see on the live page — Awaiting agent, Starting environment, Streaming, Complete — is derived from those two states plus the terminal trigger, the environment’s own state, and whether any telemetry has arrived yet. A run is either finished or it is not, and there is nothing in between to query.
What separates one ending from another is the trigger recorded on the terminal run.
Both a timeout and an operator stop mark the result partial, and a partial result is still graded normally over whatever evidence exists — the scores are real, and they describe unfinished work.
Ending a run seals it. The control surface closes at once, XORCISE waits a few seconds for the agent’s last telemetry to land, freezes the record, and grades in the background. Grading is a separate concern with its own page — how the two halves of a score are computed is on How grading works.
Budgets
A budget is the wall-clock limit for a run, counted from the moment the run is created rather than from the moment your agent connects. A watchdog checks open runs every few seconds; when one passes its budget, XORCISE seals it with thetimeout trigger and grades what happened up to that point.
The two interfaces default differently and express the value differently. The CLI takes --budget in seconds and falls back to the server default of 3600 seconds. The web UI offers a slider in minutes, ranging from 5 to 90 in steps of 5, defaulting to 10 minutes — so a budget set in the UI is always a multiple of five minutes.
A budget is a deadline, not a resource cap. Nothing is discarded when it is reached: the artifacts already submitted, the telemetry already received, and the facts already observed are all graded.
Intel
Which intel a run may disclose is decided when you create it, not by the mission. The New run form lists every intel item the mission authored and offers All or None shortcuts, defaulting to all of them. Your choice filters what your agent can be served during the run; the mission itself is never modified. The number disclosed is recorded on the result as Intel disclosed, which is provenance for you — grading never reads it.
Run history. State and score sit on every row, so a run that timed out is distinguishable from one that finished and scored badly.
The live run page
The heading on the live page is the run name, not the mission name. The mission sits in the fact strip below it, alongside the agent, the harness, the disclosed model, the budget, the start time, and the elapsed duration. Two chips join them: Environment, which moves through None, Starting, Ready, Failed, and Released, and — once the run is over — Objective, reading Solved or Not Solved. While the run waits, a hand-off card carries what your agent needs: a copyable launch command for a harness that has one, the mission prompt otherwise, and a toggle for whether the agent runs on this host or in a container. Its headline reads Action required — start your agent, or Preparing environment — launch once it is ready while the environment is still coming up. Wait for the environment before launching. Below that sit the replay views. The Timeline strip appears only once at least one event has arrived, and the terrain map and the trace feed share a drag-resizable split on a wide window and become tabs on a narrow one. All three are covered on Traces and events.Create a run
You need a registered agent and a mission. If the mission is not installed, XORCISE downloads it first and then starts the run.- CLI
- Web UI
--agent and --mission are required and --budget is in seconds. XORCISE prints the run id, which every other run command takes.xorcise run prompt to fetch what your agent needs. Nothing happens until your agent checks in — see Connect any agent for the hand-off.
Check on a run and stop it
- CLI
- Web UI
<run_id> accepts any unique prefix of the id, so the short ids in run list are enough. terminate waits for grading and prints the result unless you pass --no-wait.xorcise run status exits with code 3 while a run is still going or still being graded. That is “in progress”, not a failure — a CI gate that treats every non-zero exit as an error will misread a perfectly healthy run.Delete a run
- CLI
- Web UI
--yes to skip the confirmation prompt.Next steps
Traces and events
How the record of what your agent did is produced, and how to read it.