Reference

Runs

The commands that start, list, show and cancel a run, and the fields of a run as JSON.

A run is one execution of a machine. <id> below is the ID that corbie run submit prints. Each command has a page with its flags, such as corbie run show.

Commands

corbie run submit <definition>starts a run and prints its ID corbie run lslists this client's runs in progress, with child runs corbie run show <id>prints one run's status, input and output corbie run cancel <id>cancels a run this client started corbie run send <id> <event> [data]sends an event to a run this client started corbie run reply <id> <ticket> [value]answers a ticket the run waits on corbie controller cancel <id>cancels any run, with the controller's config

A run as JSON

corbie run show <id> --json and the gateway print a run as one line, wrapped here.

  {"id":"laptop-client/20261013T185126.250Z-571d935912","machine":"fetch-title","type":"flow",
   "status":"done","input":{"url":"https://example.com"},
   "output":{"title":"Example Domain","url":"https://example.com"},
   "used":["net:example.com:443"],"step":2,
   "started":"2026-10-13T18:51:26.25Z","ended":"2026-10-13T18:51:27.31Z"}

idthe name of the client that started it, a slash, the time and a random part machine, typethe definition's name, and flow, statechart or agent titlethe definition's title:, filled in when the run started statuswaiting until a controller starts it, then running, done, failed or cancelled failurefor a failed run: denied, timeout or error errorthe failure's text; cancelled for a cancelled run refused, layer, fixfor a refused permission: the entry, the layer and the change that allows it inputwhat the run was started with outputthe machine's output usedthe permissions its jobs used, child runs included stepthe number of its latest step started, endedtimes in UTC parentfor a child run, the ID of the run that started it jobs, timershow many of its script jobs are on a runner, and how many timers it waits for ticketsthe names of the tickets it waits on labelsthe labels it was started with

denieda job was refused a permission, or the ask did not approve a job timeoutthe run's timeout passed; a job that timed out fails its run with error erroranything else, such as a failed job the machine has no rule for, or a start the controller refused

A field with no value is left out. A run in a list has no title, output, error, refused, layer, fix or used.

Files

A blob is printed as { "$blob": <path>, "type", "size" }. The path gives the blob's place in the run.

report, pages[2]in the output input/reportin the input steps/3/events[0].data.reportin step 3 of the record emits/<job>/1/values[0].data.reportin a value that the job emitted definition/scripts.<name>a script of the definition definition/machines.<name>a machine that the definition names

To give a blob of one run to another run, write it in the new input with the first run's ID added. Both runs must be this client's. Corbie copies the blob into the new run's record, so it remains after the first run is deleted.

  corbie run submit next.yaml --input '{"doc": {"$blob": "report", "run": "<id>"}}'

The record

corbie run show <id> --record --json prints each entry as one line, child runs' entries included.

id, timethe run the entry belongs to, and when it was written step, eventsa step's number, and the events it received: name, from, data, and answer: true on the answer to a ticket askswhat the controller did next; kind script or child is a job it started status, statethe run's status and the machine's state after the step job, name, dataan emitted value: its job, its name (log for a log line) and the value

Events and tickets

A statechart state with ticket: <name> issues a ticket, and corbie run reply answers it (Statechart). Only the client that started the run can print the ticket, with corbie run show <id> --tickets.

A statechart with no final state keeps running. Start it once with a label, send it an event each time there is work, and find it later with corbie run ls --label service=reports.

# reports.yaml

statechart: reports
initial: idle

states:
  idle:
    on: { work: working }
  working:
    job: { script: ./work.js, input: { item: "${event.data}" } }
    on:
      done: idle
      failed: idle

// work.js

return "did " + input.item

corbie init --ceiling all --name laptopcorbie start &corbie run submit reports.yaml --label service=reportscorbie run send <id> work '"q3"'  taken; the machine acted on itcorbie run send <id> pause  taken; the machine had no rule for itcorbie run show <id> --record  step 1  <- start  step 2  <- work from client "q3"  step 2  -> job working: a script, on laptop-runnercorbie run cancel <id>  taken

The state working has no rule for work, so the statechart ignores an event that arrives while the job runs.

Reference

Statechart on:, ticket: and event.from
Routes the same requests over HTTP, and their answers as JSON
The store who can read a run's files