Operate runs

This guide is for the person who looks after runs once workflows are in use. It shows how to find the runs that need attention, how to get each kind moving again or end it, and how to keep the store tidy. Every output shown is from a real run of the command.

Find the runs that need attention

List the runs, newest first:

realm run list

It prints one line for each run: its ID, workflow, phase, last change and number of steps.

566ba1b6-8e67-4255-9fd9-ed9b270b452d  sync v1  abandoned  10/2/2026, 12:33:38 AM  1 step(s)
7be2233c-2f2d-4f22-98cd-f561496c129b  sync v1  failed  10/2/2026, 12:32:56 AM  3 step(s)

Narrow the list with --status <phase> or --workflow <id>.

To see only the runs that are open and have not moved for a while, use --stuck:

realm run list --stuck

It prints:

No stuck runs found (threshold 24h).

By default a run counts as stuck after 24 hours without a change. Set another limit with --older-than, for example --older-than 30m. A run that is listed says why:

Stuck runs (threshold 0m):
f4dee18d-e5a4-4989-885d-bea2a7b60483  sync v1  running  10/2/2026, 12:35:37 AM  1 step(s)  idle: 0m

Look at one run

realm run inspect <run-id>

The first lines say where the run stands and, for a finished run, what ended it:

Phase: failed
Sealed by: step_failure
Cause: Step 'fetch' failed: Step 'fetch' failed after 3 attempts
Completed: page_on_call, release_lock
Failed: fetch
Skipped: summarise

Further down, Run Health lists anything Realm finds wrong with the run, and Drive failures lists the times a driver gave up on it. See Evidence for how to read the rest.

Decide what to do

The run is	Do this
gate_waiting	Answer the gate. See Waiting at a gate.
running, and its driver has stopped	Start a driver on it again. See Open, with no driver.
failed, and the cause is now fixed	Resume it. See Failed.
open, and should not continue	Abandon it. See No longer wanted.
finished, and old	Purge it. See Keep the store tidy.

Waiting at a gate

realm run inspect shows the gate’s ID and choices. Answer with:

realm run respond <run-id> --gate <gate-id> --choice <choice>

See Add a human gate.

Open, with no driver

A run in running moves only when a driver calls it. If the driver has stopped, start one on the same run. When the run owes the engine work — an auto step or a guard, as the Owed to the engine: line of realm run inspect says — run it from your shell, with no model and no key:

realm run advance <run-id>

It stops where the run next needs something else, such as an agent step or a question, and says which. An agent step needs a driver with a model:

realm agent --run-id <run-id> --model <model>

<model> is the model to drive the run with. Give the flags you drove the run with: the model flags (--provider-module, or --provider, --model, --base-url and --strict-base-url) as you used them, and --extensions-module, --project, --schema-retries, --llm-timeout or --mint-writer-nonce if you used them. Realm does not record the model or most of those flags: realm run inspect shows the provider of a drive failure, and the extension module the run loaded under Extension Identity. A run started by realm workflow run was never driven by a model: name any provider and model you want. Version 0.45.0 has a default model, so --model can be left out there.

An assistant connected over MCP can pick the run up as well, by asking for its state and following the reply.

Failed

When the cause of a failure has been fixed, re-enable the failed step:

realm run resume <run-id> --from <step>

It prints:

Resumed run '4a0eafe2-afff-40ca-8b89-ad0e92db1a9c': step 'fetch' re-enabled and run reset to 'running'.
To run the step the engine owes ('fetch') without a model: realm run advance 4a0eafe2-afff-40ca-8b89-ad0e92db1a9c

The run is open again. Steps that had completed stay completed; the named step will run again. fetch is a step only the engine runs, so the second line names the call that runs it, with no model. When the step that is ready again is an agent step, the second line is Drive it with: realm agent --run-id <run-id> --provider <provider> --model <model> instead, with <provider> and <model> to fill in as above, and a third line names the other flags to add. The realm run advance line was added after version 0.46.0, which prints the Drive it with: lines for every step. Version 0.45.0 prints the Drive it with: line without --provider <provider> --model <model>, and nothing after it.

--from must name a step the run lists under Failed. For any other step, the command refuses:

Step 'fetch' is not in failed_steps for run '44df45a3-630d-4679-961e-4cc1616307b4'.

A run that was aborted cannot be resumed. Start a new run.

No longer wanted

To end an open run by hand:

realm run abandon <run-id> --reason "docs test"

It prints:

Run '566ba1b6-8e67-4255-9fd9-ed9b270b452d' abandoned (phase: 'abandoned'). Reason: docs test.
…
abandon is a kill — declared finalizers (if any) did NOT run and will not for this run. …

Two things to know before you abandon:

• Cleanup steps do not run. A workflow’s finalizers are skipped.
• A run waiting at a gate cannot be abandoned. Answer the gate first.

A run that has already finished is left alone:

Run '0fdae340-…' is already terminal (failed); cannot abandon a finished run.

To abandon every open run that has been idle for a while, preview first:

realm run cleanup --older-than 7d --dry-run

It prints:

Would mark 1 run(s) as abandoned.
  • 79b5ba95-7bc1-4779-ab12-2e653139eb29
abandon is a kill — declared finalizers (if any) did NOT run and will not for this run. …

Without --dry-run, the same command abandons them. It leaves runs that are waiting at a gate.

Keep the store tidy

Run records stay on disk until you remove them.

Keep a copy first

realm run export writes everything Realm holds about a run to one file:

realm run export <run-id> --out ./run-44df45a3.json

It prints:

Exported run '44df45a3-630d-4679-961e-4cc1616307b4' to './run-44df45a3.json' (5.8 KB).
  phase: failed, attempts: 2, WAL steps: 0, sealed artifacts: 0

Delete finished runs

realm run purge deletes finished runs for good. It only reports what it would delete, unless you add --force:

realm run purge --older-than 30d

It prints:

6 run(s) WOULD be purged (21.3 KB to free):
  • 0fdae340-a7e5-4ff5-b83f-9fb6086a53be  (failed, 3.6 KB)
  …

3 of 6 selected run(s) are resumable via 'realm run resume' — purging would destroy that path permanently.
Re-run with --force to actually delete.

Read the list, then run it again with --force:

Purged 6/6 run(s) (21.3 KB freed, store-reported). 0 already gone, 0 blocked, 0 failed.
3 of 6 selected run(s) were resumable via 'realm run resume' — purging has destroyed that path for them.

Purge never touches a run that is still open. To purge one run, give its ID in place of --older-than.

Remove leftovers

realm run gc removes files that a crash can leave behind. Like purge, it only reports unless you add --force:

realm run gc --older-than 1d

It prints, on a clean store:

No orphaned .tmp files found to reap.

No run-less orphaned WAL/sidecar artifacts found to reap.

gc does NOT yet reap orphaned .lock dirs (deferred — issue #164). Their presence in runsDir is expected and not a sign gc is broken.

Two rarer cases

• A step was started and never finished, because the process running it died. realm run reclaim <run-id> reports such steps, and with --force makes them runnable again. The step’s work may then happen twice, so read what it reports first.
• A run ended but its cleanup steps did not finish. realm run drain <run-id> reports them, and with --force runs them.

If you see something else

• Run not found: <id> No run has that ID in this store. Check the ID with realm run list.

See also

• realm run commands that read
• realm run commands that act
• Run state and health findings lists everything Run Health can report.