Workflow YAML reference

A workflow is a directed graph of typed nodes wired by edges, authored in the visual builder and serialized to YAML. The canonical shape is a single JSON Schema generated from the same zod source the web app validates against (web/src/lib/api-schemas-workflow.ts), so the document, the editor, and the runtime never disagree.

Editor validation

Every workflow exported from the builder begins with a modeline that points your editor’s yaml-language-server at the schema, giving inline validation and node-kind autocompletion:

# yaml-language-server: $schema=https://supacloud.run/schemas/workflow.json
name: nightly-triage
stages:
  - node_key: classify
    role: plan
    who: triage-agent
nodes:
  - key: classify
    kind: llm_classify
    config: {}
edges: []

Note

The schema is regenerated from zod and the committed copy is drift-checked in CI, so it always matches the running validator. Per-node config is currently an open object; per-kind sub-schemas are a follow-up.

Top-level fields

Field	Type	Notes
name	string	Workflow name.
project_id	string	The owning project.
nodes	array	The typed-node graph (the V8 builder surface).
edges	array	Connections between nodes, by source/target key.
steps	array	The v1 agent-only step view, kept for back-compat.
stages	array	Optional first-class metadata assigning graph nodes to semantic workflow stages.
max_concurrent_runs	integer | null	Caps simultaneous runs; null = unbounded.

Stage

Stages annotate existing graph nodes; they do not add execution edges or a second runtime. Each node_key must name one node in the same workflow and can appear only once. role is intentionally an open semantic label, so custom and Marketplace workflows can use their own vocabulary (common roles are plan, implement, and review). who is optional metadata for the intended agent, profile, or owner.

Field	Type	Notes
node_key	string	Required key of an existing workflow node.
role	string	Required non-empty semantic stage label.
who	string	Optional non-empty intended agent/profile/owner label.

Node

Field	Type	Notes
key	string	Unique node key (referenced by edges).
kind	enum	One of the node kinds below.
config	object	Kind-specific configuration (open object today).
position	{ x, y }	Canvas coordinates for the builder.

Edge

Field	Type	Notes
source	string	Source node key.
target	string	Target node key.
source_handle	string	Which output handle the edge leaves (default out; gates use branch handles).

Node kinds

Kind	Purpose
agent	Run an AI coding agent with a prompt.
gate	Branch on a predicate to different output handles.
human	Pause for a human decision or input.
end	Terminal node.
code	Run a Bash/Python/TypeScript/Go/Rust/C# snippet (defaults to Bash). Unbound: hermetic container, no network/DB. A Python/TypeScript node may declare resource_bindings to run on the credentialed sandbox with vetted egress + a host-mediated guarded DB call (ADR 0058).
db_query	Read from a bound PostgreSQL resource. params resolve ${{ nodes.* }}/${{ trigger.* }}/${{ steps.* }} typed (#990); the SQL text itself is deliberately never templated.
db_execute	Write to a bound PostgreSQL resource. params resolve references like db_query (#990); SQL text never templated.
http_request	Make an outbound HTTP call (SSRF-guarded, IP-pinned). url, headers and body resolve ${{ }} references typed (#990); the resolved URL passes the same SSRF vetting as a literal one.
transform	Reshape data flowing between nodes.
notify_telegram	Send a Telegram message.
notify_email	Send an email. Optional attachments (#1050): up to 5 entries of content_b64 (base64 or a ${{ nodes.<key>.<field> }} reference), filename, content_type; 10 MiB decoded total. An unresolvable or undecodable attachment fails the node loudly — an invoice mail never sends hollow.
notify_webhook	POST to a webhook.
notify_discord	Send a Discord message.
loop	Iterate over a collection. over is a TYPED value slot (#990 Teil 2): a single ${{ nodes.<key>.<field> }} / ${{ trigger.<field> }} reference resolving to an array, or a static JSON array literal. The legacy string-interpolation form was removed — a mixed string fails loudly with a migration hint.
wait_event	Pause until an external event arrives.
llm_classify	Classify input with an LLM.
imap_ack	Acknowledge an IMAP message.
app	Invoke a deployed App. inputs resolves ${{ }} references typed (#990).
connector	Run a marketplace connector node. Optional resources pin (#1044): {"<resource_kind>": "<resource name>"} selects WHICH same-kind workspace resource each required kind binds; an unpinned kind keeps the deterministic first-by-name default, a pinned name that does not exist fails the run loudly.
ssh_exec	Run ONE command on a bound ssh_host resource (#1049). The command is STATIC (no ${{ }} templating — that would be a shell-injection channel); dynamic data goes on stdin_b64. Output (stdout/stderr/exit_code) is byte-capped; a non-zero remote exit fails the node. The host/port are SSRF-vetted and IP-pinned; the private key/password come only from the resource secret.

Upstream node results flow to a node via SC_NODE_INPUTS; a trigger payload via SC_TRIGGER_CONTEXT. See the build-your-first-workflow tutorial to author one in the visual builder.