How execution works

A conceptual walkthrough of how Swirls executes workflows, from trigger to checkpointed output.

Reading the syntax gets you writing .swirls files. This page explains what happens after you write them: how a trigger becomes a running workflow, and how the Swirls Cloud runtime handles failure, resumption, and durable checkpointing.

The execution lifecycle

Every workflow run follows the same four stages.

Trigger fires
     |
     v
 Workflow selected
     |
     v
 Nodes execute (one at a time, in dependency order)
     |
     v
 Checkpoint written after each node completes

When a trigger fires (a form is submitted, a webhook arrives, a schedule ticks), the engine selects the bound workflow and starts a new execution. An execution is a persistent record that tracks every node's status, input, and output.

The DAG model

A workflow is a directed acyclic graph. Nodes are vertices. Edges define dependencies. No cycles are allowed.

This structure has a direct operational consequence: the engine can determine exactly which nodes are ready to run at any moment. A node is ready when all its upstream dependencies have completed. Branches with no shared ancestors are independent: neither one reads the other's output.

         root
        /    \
    enrich  validate
        \    /
        combine

In this workflow, enrich and validate are both unblocked as soon as root completes, so the scheduler can run them concurrently. combine waits for both. Ready nodes start in stable topological order up to the workflow's concurrency: cap, which defaults to 8 and may be set from 1 through 64.

Routing through conditional branches uses switch nodes. A switch node runs its router function and selects exactly one labeled edge. Only the selected branch executes.

         root
           |
        classify
       /         \
  handle_high  handle_low

No other flow control exists at the DSL level. Iteration uses map (sequential child-workflow runs with previous-result access), fanout (bounded concurrent independent runs), or while (repeated runs until a condition is false). All are expressed as nodes, not control-flow keywords.

Durable execution and checkpointing

Every node writes its output to the execution record when it completes. If the worker crashes mid-run, or if the process is restarted, the execution resumes from completed checkpoints.

 root: DONE     (checkpointed)
 enrich: DONE   (checkpointed)
 validate: DONE (checkpointed)
 combine: ---   (next to run on resume)

This means:

Completed nodes never re-execute on resume.
Node side effects (emails sent, database writes, API calls) are not replayed.
An execution that times out or errors at one node does not lose the work already done.

Checkpointing is automatic. No configuration is required. The engine handles it for every node, on every execution.

Per-node execution budget

A code or database node's script body has 30 seconds of wall-clock time to complete. That budget covers time spent awaiting I/O, an HTTP call, a database query, not just computation. A node that exceeds it fails with an execution budget error.

Each node gets its own fresh budget: split long-running work across multiple nodes rather than one large one. To process many rows, use a map node so the work runs one item at a time rather than as a single long query. An http node enforces its own 30 second timeout on the request itself, separate from this budget.

Pause and resume

Some nodes pause execution and wait for an external signal before continuing.

Review-enabled nodes route to review instead of running their own work. When the run reaches a node marked review: true, the engine skips the node's code: or prompt: entirely, creates a pending review, and waits for a human to respond. On approval, the reviewer's submitted form data is recorded as the node's output and downstream nodes proceed. Rejection fails the run. Put the actual work in an upstream node and treat the reviewed node as a gate.

wait nodes pause for a duration (amount and unit) before the next node runs.

workflow nodes (subgraphs) and map / while nodes can trigger child executions. Each child execution is its own checkpointed record. The parent execution waits for all children to complete before proceeding.

A paused execution holds its checkpointed state while it waits and resumes the moment the signal arrives. Reviews do not wait forever: a pending review that receives no response within the review timeout (default 7 days) fails the run with a review timeout error.

Agent turns

A type: agent node runs a tool-call loop inside its execution step. The model receives a prompt and a system message, then generates a response. If the response includes a tool call, the runtime runs the corresponding tool workflow as a checkpointed child execution and returns its output to the model. The model then generates the next response. This continues until the model returns a final answer without tool calls, or until maxSteps is reached (default 20).

Built-in workspace tools (read, write, edit, bash, grep, find, ls) operate on a per-agent Linux sandbox. The sandbox provisions lazily: a turn that never calls a workspace tool never starts one. Workspace files persist across turns for the same agent. The sandbox { } block on the agent declaration controls resources and idle lifecycle.

Each step of the tool loop is checkpointed. If the worker restarts during an agent turn, the loop resumes from the last completed step. See Agents for the full agent configuration reference.

Storage

Execution state lives in a managed PostgreSQL database in Swirls Cloud. Every node output, execution status, and stream record is stored there with encryption at rest. You never configure or manage the database directly.

Workflow execution and agent chat are hosted capabilities. The CLI runs locally to author, validate, generate types, and deploy .swirls files. It does not execute workflows on your machine.

An annotated execution walkthrough

This example traces a single execution of a three-node workflow.

Workflow: process_contact

Trigger: form submission { email: "[email protected]" }

---

[1] root node starts
    Input: { email: "[email protected]" }
    Code: normalize email
    Output: { email: "[email protected]" }
    Status: DONE
    Checkpoint written.

[2] summarize node starts
    Input: context.nodes.root.output -> { email: "[email protected]" }
    AI call: generate summary
    Output: { text: "New contact from [email protected]." }
    Status: DONE
    Checkpoint written.

[3] notify node starts
    Input: context.nodes.summarize.output.text
    Resend call: send email to [email protected]
    Output: { id: "re_abc123" }
    Status: DONE
    Checkpoint written.

Execution complete.

If the worker restarted after step 1, the engine would skip the root node (already checkpointed) and pick up at step 2.

How workflows connect to other workflows

A workflow node calls another workflow as a subgraph. The parent execution creates a child execution, passes the specified input, and waits for the child to complete.

A map node creates one child execution per item in a list. A while node creates child executions repeatedly until the condition is false or maxIterations is reached.

All child executions are checkpointed independently. If a child fails, the parent sees the failure and applies its failurePolicy (if configured). See Failure policies for the available strategies.

Streams

A stream block captures a workflow's output as a typed, persistent record each time the workflow runs. You read from a stream using a type: stream node in another workflow.

Streams are the primary way to share data between workflows. One workflow produces records; another workflow queries them. The two workflows run independently; the stream is the interface between them.

Workflow hash and execution credentials

Every compiled .swirls definition gets a SHA-256 hash. Execution credentials are scoped to that hash, and each node call is verified against them at runtime.

When you redeploy with changes, the hash changes. New executions run under credentials for the new definition. In-flight executions from the previous deployment finish under their original credentials, so a redeploy never changes a run mid-flight.