How execution works

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, depth-first through the DAG)
     |
     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. If two branches have no shared ancestors, they run without waiting for each other.

         root
        /    \
    enrich  validate
        \    /
        combine

In this workflow, enrich and validate are both unblocked as soon as root completes. combine waits for both. The engine never needs to coordinate between them; the topology expresses the dependency.

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 (one child-workflow run per item) or while (repeated runs until a condition is false). Both are expressed as nodes, not control-flow keywords.

Durable execution and checkpointing

Every node writes its output to the execution record before the next node starts. If the worker crashes mid-run, or if the process is restarted, the execution resumes from the last completed checkpoint.

 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.

Pause and resume

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

Review nodes pause at a node marked review: true. The execution waits for a human to approve or reject. When they respond, the execution resumes from that node's output.

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 state indefinitely. There is no timeout on a paused review. Executions resume the moment the signal arrives, regardless of how much time has passed.

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 token binding

Every compiled .swirls definition gets a SHA-256 hash. That hash is embedded as a caveat in the deployment macaroon chain. Each node call is verified against the chain at runtime.

When you redeploy with changes, the hash changes and the previous deployment's tokens are no longer valid. In-flight executions from the previous deployment continue with their original token chain; new executions use the new chain.

See the platform security documentation for the full 5-level delegation chain: Workspace, Deployment, Execution, Node, Tool.

Further reading

• Workflows: DAG structure, edges, and routing.
• Node types: every node type and its configuration.
• Failure policies: retry, skip, and fallback strategies.
• Reviews: human-in-the-loop pause and resume.
• Streams: persisting and reading workflow output.
• Local development: authoring and validating .swirls files on your machine before deploying.