Canvas

The canvas is the primary surface for building workflows. It renders a controlled React Flow graph backed by the workflow's AST, giving you a visual representation that stays in sync with the underlying definition at all times.

Opening the editor

Navigate to Workflows inside any project, then click a workflow name (or New workflow). The editor opens at /[orgSlug]/[projectSlug]/workflows/[id]. The same editor shell is shared across org-scoped and project-scoped workflow routes - the URL determines which scope breadcrumb is shown at the top.

Canvas controls

Control	Action
Scroll wheel	Zoom in / out
Middle-click drag / Space + drag	Pan the canvas
Hand mode (toolbar)	Toggle pan-only mode (cursor changes to a hand)
Pointer mode (toolbar)	Default select / connect mode
Undo (`Ctrl`/`⌘` + `Z`)	Step back one AST mutation
Redo (`Ctrl`/`⌘` + `Shift` + `Z`)	Step forward one undone mutation
MiniMap (bottom-right)	Overview of the full graph; click to jump
Auto-arrange (toolbar)	Re-layout via ELK graph engine

Undo/redo tracks typed AST mutations, not pixel positions. Moving a node around the canvas is undoable just like wiring a new edge.

Adding nodes

Drag a node from the Node Palette onto the canvas. You can also double-click an empty area to open a quick-add search. On drop, the node is appended to the AST with a generated ID and placed at the drop coordinates.

To delete a node, select it and press Backspace or Delete, or right-click for the context menu.

Connecting nodes

Drag from an output port (right side of a node) to an input port (left side) to create an edge. Connection rules are enforced in real time - see Port Types for the full validation model. An invalid drag shows a red "snap-back" animation and a tooltip explaining the rejection reason.

Scopes and groups

Workflows can contain group containers - reusable sub-graphs with a typed I/O interface. The scope breadcrumb bar at the top of the canvas shows your current path:

Root > My group > Inner group

Double-click a group node to drill into its body. Click a breadcrumb segment to navigate back up. Nodes in a child scope are not visible from the parent, and edges cannot cross scope boundaries without going through the group's interface ports (an error is shown if you try).

In group-draft mode (used when editing a group bundle), the root canvas itself is treated as a group body. The palette surfaces additional Input port and Output port draggables for authoring the group's public interface.

Boundary ports

Interface ports appear as special pseudo-nodes at the left (inputs) and right (outputs) edges of the group's viewport. You can reposition them by dragging. Configure their types via the Port Type editor.

Execution mode

The toolbar offers two modes:

Edit - normal authoring; node palette and config panel are available.
Execution - shows an instance selector; prior runs appear in the execution history drawer. When a run is selected, each node overlays its live status (pending / running / completed / failed / skipped).

Live step status arrives via Server-Sent Events over a per-instance Redis pub/sub channel. Status icons update in place - no page reload required.

The Run button in the toolbar is only active when the workflow is in the published state. A draft workflow cannot be triggered directly from the editor; publish first.

Execution history drawer

In Execution mode, the Execution History drawer lists every past instance for this workflow. Each row shows:

Status badge - running, completed, failed, suspended, cancelled.
Trigger type - how the instance was started (webhook event, manual dispatch, cron, test run).
Start time and duration - relative timestamp and elapsed time.
Test run indicator - instances started via Run Test show a flask icon so they are visually distinct from production runs.

Click a row to select it; the canvas immediately switches to the selected instance's execution overlay. The status filter dropdown narrows the list to a specific status, and the search box matches against instance IDs and trigger data.

Per-node status overlay

When an instance is selected, each node card displays an icon badge driven by execution streaming:

Badge	Meaning
Pulsing spinner	Node is currently running
Green check	Completed successfully
Red X	Failed (expandable error summary below the canvas)
Grey skip	Skipped - click to see the skip reason (condition branch, null propagation, when guard)
Clock / pause	Waiting - suspended at a gate
Yellow star	Mocked - returned a static payload in test mode

Workflow controls

The right-hand panel exposes:

Publish / Unpublish - promote the current canvas to the published state.
Clone - create a copy of this workflow in the same project.
Deploy - push the workflow to a connected donmai runtime (requires DONMAI_API_URL to be configured).
Required resources - lists the foundational nodes the workflow depends on (agent cards, LLM model profiles, capacity pools). Missing resources appear as warnings.

A broken-state banner appears across the top if the workflow was saved in an invalid state (e.g., after a schema migration). Use the Clear broken state action in the banner to reset the flag after repairing the canvas.

Canvas description API

For programmatic access (e.g., agent tooling), the platform exposes a text-based canvas description:

GET /api/workflows/[id]/canvas?format=description

Returns a ~200-token human-readable summary of the workflow graph - useful for feeding to an LLM to get context without parsing the full YAML.

Group diff overlay

When a group inside your workflow was originally imported from another workflow (via Import sub-flow), the canvas can detect whether the upstream source has changed since you imported it. Click the Upstream diff button that appears on the group node's toolbar to open the group diff overlay:

The overlay fetches the current upstream definition and computes a line-by-line diff (nodes added, removed, or modified; edges added or removed; YAML changed).
Each diff entry has a checkbox. Select the changes you want to apply and click Apply selected to patch the group's inline snapshot.
The patched group is written back to the canvas AST immediately. You can review the result in the YAML pane before publishing.

The diff is computed by computeGroupDiff and applied by applyDiffToSnapshot - both are pure operations against the group's serialized definition, not live execution state. The overlay route is:

GET /api/workflows/groups/{groupNodeId}/upstream-diff

The group diff overlay only appears on groups that carry a provenance.sourceWorkflowId - groups you authored locally from scratch do not have an upstream and show no diff button.

Import and export

Export - download the current canvas as a YAML or JSON file from the workflow controls menu.
Import - replace the canvas AST from a YAML or JSON file via the import dialog.
Import sub-flow - import an existing workflow as a group into the current canvas. Cycle detection prevents circular references.

Keyboard shortcuts

Shortcut	Action
`Ctrl`/`⌘` + `Z`	Undo
`Ctrl`/`⌘` + `Shift` + `Z`	Redo
`Del` / `Backspace`	Delete selected node(s) or edge(s)
`Escape`	Deselect / close config panel

Node Palette - finding and adding nodes
Node Config Panels - configuring node parameters
Port Types - typed connection validation
YAML Pane - direct YAML editing
Versioning - snapshots, diff, and rollback
Publishing and deployment - publish, deploy, draft lifecycle
Test-run mode - mock-node auto-mocking
Execution Streaming - SSE architecture behind the per-node live overlay
Groups - group containers, scope model, and boundary port authoring

On this page