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.
db_execute	Write to a bound PostgreSQL resource.
http_request	Make an outbound HTTP call (SSRF-guarded, IP-pinned).
transform	Reshape data flowing between nodes.
notify_telegram	Send a Telegram message.
notify_email	Send an email.
notify_webhook	POST to a webhook.
notify_discord	Send a Discord message.
loop	Iterate over a collection.
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.
connector	Run a marketplace connector node.

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.