genroc

    docs / Guides / Operating

    Managing instances

    Learn how to manage running instances.

    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:

    PhaseMeaning
    childrenChild instances were spawned; the parent is blocked until all of them finish.
    collectingAll children have finished; the engine still has to merge their outputs into the parent.
    externalParked 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.

    Instance status transitions live in transition instant when nothing is in flight settled start end reached raise error child failed tasks land pause tasks land resume task ends the process cancel tasks land retry running paused failing pausing cancelling completed raised failed cancelled genctl command engine

    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.

    StatusSettledAccepts a resultMeans
    runningnoyesadvancing, or waiting on a timer, a child or an external task
    pausingnoyesa pause was requested while a task at or below it was in flight; it settles once every such task reaches its boundary
    pausednoyesnot being advanced, and able to resume exactly where it stopped; timers keep running
    failingnonodoomed by an error, and draining the descendants still in flight
    cancellingnonoa cancel was requested while a task at or below it was in flight; it settles once every such task reaches its boundary
    completedyesnofinished by reaching the end of its definition
    failedyesnostopped by an error; retryable, which is what separates it from the other settled outcomes
    raisedyesnoconcluded by a raise clause — a condition, not a defect, and catchable by the parent
    cancelledyesnostopped 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
    FieldMeaning
    ParentThe parent instance and the task that spawned it. Children only.
    Call stackEvery ancestor instance, root first. Children only.
    Wake atWhen a pending timer fires - a delay, a retry backoff or a timeout.
    LeaseThe engine worker advancing the instance and how long it has left, or that the lease expired.
    ExternalWhile parked on an external task: unclaimed, claimed by …, or that the claim expired.
    EpochsCounters that keep a stale worker or an old answer from overwriting newer work. For debugging.
    ChildrenThe spawned instances, keyed by the task that spawned them.
    Stateinput, 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.