Instances are essentially state machines. When you run a process, genroc validates the input data and stores the initial state.
The instance is then picked up by the engine, which advances it into a new state.
Listing instances
To list current instances on the server, use the instances command. It lists root instances
(add --children for the rest) and shows the newest 20; pass --since to read further back.
> genctl instances
ID STATUS PROCESS UPDATED CREATED CODE ERROR
3kjfx4vm completed hello@v1 22h ago 22h ago
006y1m7d completed hello@v1 just now just now
You can also filter by various parameters like --status or --process (process name);
check the full cli docs for details.
Info about the instance
To check the current state of an instance, use the get command.
> genctl get @last
ID: 006y1m7d
Process: hello@v1
Status: completed
Task: greet
Created: 2026-09-30 12:53:58 (just now)
Updated: 2026-09-30 12:53:58 (just now)
Output:
at: "2026-09-30T10:53:58.669Z"
greeting: hello, world
The example shows a completed instance,
as indicated by status.
The output can also contain Phase, Retries, Error, Code and Error data, and an
External input block while the instance waits on an external task.
These are listed only if they have a value.
Task
The task field tells you which task is being or is going to be performed.
If the instance has finished, it tells you which task was the last.
Phase
Some tasks are not atomic (external/children), meaning the engine needs to perform multiple "ticks" per task.
In that case the phase field is used to distinguish between the sub-states.
It is shown only when it's not empty, and has the following meaning:
| Phase | Meaning |
|---|---|
children | Child instances were spawned; the parent is blocked until all of them finish. |
collecting | All children have finished; the engine still has to merge their outputs into the parent. |
external | Parked on an external task, waiting for an answer or for its timeout. |
Error, Code and Error data
Describes an error if the status is raised, failing or failed.
System error codes contain a dot (e.g. result.invalid); user-defined codes can't contain one.
Error data is an optional payload of panic or raise.
Check the task error reference.
Output
This is the public output of the process.
It's available once the instance has completed, if the process defines output.
Instance lifecycle
Genroc instances communicate their lifecycle through the status field.
Settled marks a terminal state: no work moves, and nothing leaves it on its own
(retry gives a failed one another attempt).
Accepts a result is whether a worker's answer to an external task is still delivered —
a pause suspends execution, not delivery.
| Status | Settled | Accepts a result | Means |
|---|---|---|---|
running | no | yes | advancing, or waiting on a timer, a child or an external task |
pausing | no | yes | a pause was requested while a task at or below it was in flight; it settles once every such task reaches its boundary |
paused | no | yes | not being advanced, and able to resume exactly where it stopped; timers keep running |
failing | no | no | doomed by an error, and draining the descendants still in flight |
cancelling | no | no | a cancel was requested while a task at or below it was in flight; it settles once every such task reaches its boundary |
completed | yes | no | finished by reaching the end of its definition |
failed | yes | no | stopped by an error; retryable, which is what separates it from the other settled outcomes |
raised | yes | no | concluded by a raise clause — a condition, not a defect, and catchable by the parent |
cancelled | yes | no | stopped for good by an operator — terminal, and unlike a pause there is no way back |
You have four commands at your disposal: pause, resume, cancel and retry.
They can only be applied to root instances, and they apply to the whole
tree. They are refused on children.
pausing, failing and cancelling are transitions: while the root is in one, every command
is refused until it settles, except repeating the one under way. To take back a pause or turn it
into a cancel, wait until the tree is paused.
Pause (and resume)
genctl pause @last
This will pause the instance if it's running. The instance can then be resumed by the resume command with the same syntax.
pause returns at once. An instance a worker is executing goes to pausing and becomes paused
when that task finishes, so no worker is forcefully interrupted and no work is repeated.
If that task ends the process, the instance settles as it would otherwise (completed, raised or failed). Every
instance above it stays pausing until nothing below it is running, so the root's status is the
whole tree's: a paused root means nothing in the tree is executing.
Pause/resume operates strictly within the definition boundaries (they never add a retry), so you can use them as you like without changing the instance's behavior. The only caveat is that timers keep running even when the instance is paused, so a timeout (e.g. on an external task) can run out while the instance is paused.
An external worker can still deliver a result through resolve, even if the instance
has switched to the paused status.
Cancel
genctl cancel @last
This cancels the instance for good — a cancelled instance can't be resumed.
Cancel goes through cancelling the same way, up to the root.
An external worker can't deliver a result through resolve (it will fail) if the instance
was cancelled while the worker was running.
Retry
genctl retry @last
Retries a failed instance; it basically adds one extra attempt on the current task
(it doesn't reset the retry counter, so it tries once and goes straight back to failed on an error).
Retry can't be used on paused, cancelled or raised statuses.
When a child fails, the rest of its tree is paused rather than left running work the failure has
doomed, and the root becomes failed once nothing in the tree is executing. retry revives the
failed branch and resumes the paused ones where they stopped; resume is refused on a failed tree.
If the task is only_once, retry needs the --force flag,
because a retry could easily break the only_once rule by accident.
Upgrade
genctl upgrade @last --to latest
Moves a running, paused or failed instance to another version of its definition, for example to fix a URL in a process that's already running. It only moves if the new version fits the state the instance is in. See Upgrading instances.
Instance logs
To see a detailed history of an instance, use the logs command.
> genctl logs 006y1m7d
TIME LEVEL ID EVENT TASK
--- 2026-09-30 +02:00 ---
12:53:58 INFO 006y1m7d inst_created by=no-auth:anonymous input={"who":"world"}
12:53:58 INFO 006y1m7d child_spawned greet msg="1 children"
12:53:58 INFO 3k1nz7pq inst_created input={"code":"async function greet (input) {\n return …
12:53:58 INFO 3k1nz7pq extern_armed eval_node msg="token=3k1nz7pq.0 timeout=5000ms -> 2026-09-30T10:54:03Z"
12:53:58 INFO 3k1nz7pq extern_resolved eval_node
12:53:58 INFO 3k1nz7pq inst_completed eval_node output={"at":"2026-09-30T10:53:58.669Z","greeting":"hello,…
12:53:58 INFO 006y1m7d child_collected greet
12:53:58 INFO 006y1m7d inst_completed greet output={"at":"2026-09-30T10:53:58.669Z","greeting":"hello,…
When you target a root, the logs include its children's logs as well.
Instance detail
If you want more info about an instance, use the detail command.
It prints everything get does, plus extra info about the internal state.
> genctl detail @last
ID: 006y1m7d
Process: hello@v1
Status: completed
Task: greet
Created: 2026-09-30 12:53:58 (just now)
Updated: 2026-09-30 12:53:58 (just now)
Epochs: lease 2, task 0, parent task 0, external claim 0
Output:
at: "2026-09-30T10:53:58.669Z"
greeting: hello, world
Children:
greet: 3k1nz7pq
State:
input:
who: world
last_error: null
outputs:
greet:
at: "2026-09-30T10:53:58.669Z"
greeting: hello, world
| Field | Meaning |
|---|---|
Parent | The parent instance and the task that spawned it. Children only. |
Call stack | Every ancestor instance, root first. Children only. |
Wake at | When a pending timer fires - a delay, a retry backoff or a timeout. |
Lease | The engine worker advancing the instance and how long it has left, or that the lease expired. |
External | While parked on an external task: unclaimed, claimed by …, or that the claim expired. |
Epochs | Counters that keep a stale worker or an old answer from overwriting newer work. For debugging. |
Children | The spawned instances, keyed by the task that spawned them. |
State | input, each task's output under outputs, and last_error - the latest failure that wasn't retried, until the next task. |
Only Epochs is always shown; the rest appear when they have a value.