What are workflows?
Workflows are Cyberwave’s automation primitive. They turn a graph of nodes (triggers, models, twins, conditions, integrations) into a runnable artifact. That artifact can fire on a schedule, an MQTT message, a webhook, or every camera frame on a Raspberry Pi. You connect nodes visually to build complex behaviors without writing procedural code. The graph and the Python are two views of one object, so you can open, edit, and visualize the same workflow in the workflow editor or in code. Workflows can run on the cloud (Celery tasks) or on the edge device, depending on the trigger type. Cloud triggers handle schedule, webhook, event, and manual execution. Thecamera_frame trigger runs ML inference directly on the edge, so no video leaves the device.
Three ways to build one
You never have to pick between a low-code graph and “real” code. Cyberwave keeps the two in sync.Visual editor
Drag nodes from the palette, wire ports, configure parameters. Great for
prototyping and for handing flows to non-engineers.
Python SDK
Build, list, trigger, and monitor workflows from
cw.workflows. Anything you can do in the UI
you can do in code.With an agent
Use the workflow assistant in the workbench, or describe
the automation in plain English to Claude, Cursor, or any MCP client.
Cyberwave’s MCP server and
Claude skill wire up the graph for you.
Workflow components
Nodes
Nodes are the building blocks of workflows. Each node performs a specific action. For every node in the palette, what it does, and where it runs, see Workflow nodes. Nodes are organised into a hybrid robotics + automation taxonomy. The same categories show up in the editor palette and onGET /api/v1/workflows/config (node_categories), so the docs, the API, and the UI all read from the same WorkflowNodeCategory enum (see cyberwave-backend/src/lib/node_categories.py). Categories with no nodes today (Perception) are reserved. They appear in the API response but are hidden in the palette until they ship.
Triggers
Start the workflow on an event, schedule, or incoming message: manual, schedule, webhook, event, MQTT, email, camera_frame, alert
Data Sources
Pull snapshots and samples from sensors, cameras, and external systems on demand:
data_sourcePerception
Convert raw signals into reliable observations — reserved for object trackers, sensor fusion, IMU filtering, ASR (no nodes ship today)
Transform & Routing
Reshape, convert, route, multiplex, or fan out data:
json_parser, annotate, anonymize, send_depth (edge-only)State & Memory
Store and retrieve memory over time:
create_asset, edit_asset, create_attachment, update_attachment, video_taggerIntelligence
Use models for interpretation, reasoning, or prediction:
call_model (cloud VLM/LLM and edge ML)Decision & Control Flow
Choose what happens next:
conditional, loop; FSM / Behavior Tree / Rule Engine on the roadmapActuation
Execute physical or twin-side actions:
twin_control (Move Twin); future joint / gripper / navigation primitivesIntegration
Talk to external systems and run user-supplied logic:
http_request, send_email, send_mqtt, code (edge-only)Observability & Safety
Guard, validate, observe, and alert:
send_alert; validators, watchdogs, e-stop guards, and anomaly detectors are on the roadmapConnections
Connections define the execution flow between nodes:- Sequential: Execute nodes one after another
- Parallel: Execute multiple nodes simultaneously
- Conditional: Branch based on conditions
Connection validation prevents invalid graphs: trigger nodes cannot accept incoming connections, cycles are blocked, and
camera_frame triggers can only connect to call_model nodes.Trigger types
A trigger decides when a workflow runs and where it runs.
You can also trigger a workflow from external systems through the REST API or MCP.
Where workflows run
Cloud, edge, or both, in one graph
A workflow can span both sides of your stack. Trigger and ML nodes that run on the cloud coordinate with the same workflow’s edge half through the edge worker runtime. A common shape: The video frame never leaves the device unanonymized, the VLM runs on a GPU in the cloud, and an email goes out, all from a single workflow definition. The unified edge compiler decides what runs where based on the graph itself. You don’t manage model downloads, hardware compatibility, or reconnects. Cyberwave provisions the right model into the right runtime (edge YOLO forcamera_frame, cloud VLMs for call_model) and keeps it healthy when the network blinks.
Same workflow, sim or real
Workflows run unchanged against simulation or live hardware. Set the workflow’s execution target to Simulation and the same graph drives a MuJoCo twin in CI. Set it to Live and it drives a real robot in your cell. See Running a workflow in simulation.cw.affect() does not change where cw.workflows.trigger() runs.
Failed simulation runs show their runtime alerts in Simulate. Open the execution details to inspect the failure.
This is the practical version of “test before you deploy”. See the environment editor for replaying past runs and inspecting per-node executions.
Creating a workflow
- Dashboard
- CLI
- Python SDK
1
Open Workflows
Navigate to Workflows in the dashboard.
2
Create
Click Create Workflow. Give it a name, optional slug (unique within the workspace), and visibility.
3
Build
Drag nodes from the palette to the canvas. Connect nodes by dragging from output to input ports.
4
Configure
Configure each node’s parameters (twin UUID, model, confidence threshold, send-alert metadata, etc.).
5
Activate
Click Activate. Edge workflows (
run_on_edge: true) automatically publish a sync_workflows MQTT command to each referenced twin’s Edge Core, which immediately pulls and reloads the freshly compiled worker — no CLI step needed. The editor locks the graph while active, so the natural edit flow (Deactivate → edit → Activate) republishes through the same signal. Start from a template
You don’t have to start from a blank canvas. Cyberwave ships a library of workflow templates (motion detection, pick-and-place, intrusion alerts, voice control), and you can publish your own for your team or the world.acme/workflows/my-template), and editable after cloning. They’re a starting point, not a black box.
Workflow assistant
Select a workflow in the workbench, then use Prompt or the right-hand Assistant tab to edit it with the assistant. Click the assistant title in Assistant to switch between Environment assistant and Workflow assistant. When the workbench is closed, the workflow option is disabled and reads Open the workbench. The workbench shows node details only while a node inspector is open. Close it or clear the node selection to reclaim that space.Environment-bound workflows
A workflow can optionally be bound to an environment (setenvironment_uuid when creating it, or open the Create Environment Workflow dialog from an environment panel). Bound workflows are scoped to that environment in the editor, surface in the environment’s workflow list, and ship to the environment’s edges through edge_sync_workflows when combined with run_on_edge: true.
Compiler dispatch keys off the graph itself: a twin_control node renders through the navigation path and a camera_frame trigger renders through the perception path, regardless of how the workflow is bound. Run cyberwave workflow compile <uuid> to see exactly which path the unified compiler took, or the diagnostic explaining why it skipped the workflow.
Edge workflows (camera frame)
Thecamera_frame trigger is designed for on-device ML inference. The backend generates a Python worker file that runs directly on the edge, so raw video frames never leave the device.
Choose a Source Twin with a declared camera, then select Source Sensor.
A twin with one camera fills the sensor automatically. Older saved camera values
remain visible until you choose a declared camera. Source selection does not
activate the workflow.
How it works
For open-vocabulary edge models (YOLOE-26 text/visual, YOLO-World), set the Prompt field on thecall_model node to drive set_classes at inference time. The camera worker forwards the static prompt into model.predict(..., prompt=...). See Prompting Call Model for the full guide, including the comma-list vs. single-phrase semantics and the camera-only limitation that reference-wired prompts are not supported.
Migrating from emit_event
Older workflows configured implicit alerts via an emit_event block on the call_model node (event_type, severity, emit_mode, cooldown_seconds). That path was removed: emit_event is no longer a schema field, the next save of any call_model node strips leftover emit_event values from parameters and metadata.input_mappings so the saved graph converges to the post-migration shape, and call_model no longer publishes alerts on its own. Pre-migration rows that haven’t been re-saved yet still load — codegen also drops emit_event during compilation, so they ship a worker that runs inference but publishes nothing.
To raise alerts from detections, wire an explicit send_alert node downstream of call_model. The legacy fields map onto existing nodes:
A typical edge chain becomes:
timed_condition wired downstream of call_model without a trailing send_alert is now inert — the legacy implicit-alert path it used to gate is gone. The compiler surfaces a warning on the resulting compilation (the /compile API and cyberwave workflow sync preflight already render it) so the silent-skip case becomes visible instead of looking like a quietly broken alert chain.
Existing workflows continue to load and run inference, but stop emitting alerts until you add the explicit chain — the migration is intentionally a hard break so silent regressions are impossible.
Syncing to the edge
Activating arun_on_edge workflow auto-publishes the sync_workflows MQTT command for each referenced twin, so the edge picks up the worker within seconds — no manual step. The editor locks the graph while active, so the natural edit flow (Deactivate → edit → Activate) republishes through the same signal.
Reach for a manual sync only when the activation cycle can’t fix it — e.g. a broker outage or Edge Core restart swallowed the original nudge.
POST /api/v1/workflows/{uuid}/sync-edge— per-workflow fan-out across all referenced twins. Returns{success, workflow_uuid, command, twin_uuids[], request_ids, skipped_reason}.200covers both the success case and declarative no-ops (cloud-only workflows, workflows without a twin-bound node, references that have all gone stale or cross-workspace) —skipped_reasonpins the case. Partial broker failures also stay on200withskipped_reason: "MQTT publish failed for N of M twins". Total broker failure surfaces as500so retry/back-off logic can branch on status code rather than parsing the body.POST /api/v1/twins/{uuid}/sync-workflows— twin-wide republish covering every active workflow on that twin’s edge. Surfaced in the dashboard as the twin editor’s Force-sync all workflows menu item.
/workflows/{uuid}/sync-edge, /twins/{uuid}/sync-workflows, twin editor menu) publish the identical MQTT command on cyberwave/twin/{twin_uuid}/command, which makes Edge Core run reconcile_worker_sync immediately instead of waiting for the next periodic cycle.
The CLI derives the MQTT topic prefix (dev, staging, empty for production) from CYBERWAVE_ENVIRONMENT/credentials and cross-checks it against the broker host before publishing. A mismatch (e.g. dev broker with production prefix) aborts with a clear error instead of silently shipping the command into a topic Edge Core never subscribed to. Override with CYBERWAVE_MQTT_TOPIC_PREFIX if you really need to.
The edge device also syncs automatically on boot and periodically (default ~5 min, configurable via CYBERWAVE_WORKER_SYNC_INTERVAL_LOOPS).
See and customize the generated Python
Every workflow compiles to a real Python worker built on the Cyberwave SDK. Open Code in the workflow editor to read the exact script your graph generates, then copy or download it. This works for every workflow, whichever runtime it uses. Cloud workflows run through Cyberwave’s own interpreter rather than the script, but the generated Python is still there to read. Need to go beyond the nodes? On workflows set to the edge runtime, Customize the script and save it. Your edited version is persisted and shipped to the edge in place of the autogenerated one. Restore brings the autogenerated script back at any time. If you edit the graph after customizing, the editor flags that your custom script no longer matches the graph so you can regenerate. Custom worker code runs only on your own edge runtime.Code node
The Code action node runs a user-supplied Python function on the edge. It is only valid on workflows withrun_on_edge: true — Cyberwave never executes user-authored code on its own infrastructure.
- Runtime: Python, on the edge worker container that already runs the compiled
wf_*.pymodule. - I/O contract: Every Code node must define a top-level
def run(input: dict) -> dict. The return value is fed into the next Code node’sinputvia an internal_node_outputvariable. - Validation: The API parses the body with
ast.parseon create/update and rejects syntax errors or missingrunfunctions inline, before activation. - Activation guards: Activating a workflow is blocked if it contains a Code node and either (a)
run_on_edgeis false, or (b) the workflow uses acamera_frametrigger (not yet supported by the perception path of the edge compiler). - Availability: The node is always visible in the palette; it is disabled with an “Available only on run_on_edge workflows” tooltip when the workflow is not edge-bound.
Edge voice workflows (audio + STT + control)
Voice pipelines chain Audio Track, Audio Assistant, Wake Word Engine, Call Model (STT), Fuzzy Matcher, Twin, and Virtual Controller. Each node declares a minimal Python/SDK extra; the compile server validates imports before shippingwf_*.py.
See Edge workflow dependencies for the full matrix (compile server base.txt, edge worker extras, catalog STT models).
Monitoring executions
Track workflow execution status and results:started_at, finished_at, and error_message fields.
Check if a workflow is running
Useis_running() to quickly check if a workflow has any active execution without manually querying runs:
True when any run has status running, waiting, or requested.
In the dashboard, a Running indicator appears next to the Active badge in the workflow editor header whenever the workflow has an active execution. It refreshes automatically every 2 seconds.
Why a run is queued
A run on an edge workflow starts asrequested (shown as Requested) and becomes running only once the edge acknowledges it. If the edge is still bringing its worker up — downloading the worker image, installing it, then loading and warming up models — the run carries a pending_reason explaining what it is waiting for, with a percentage where one is available:
reason is worker_starting when the edge is bringing the worker up, or awaiting_edge when the run has been sent but nothing has picked it up yet. The field is null on runs that are not waiting on an edge.
The reason covers the worker’s whole startup, including the models loading and warming up inside an already-started container — on a cold device the longest part of the wait. A run is not failed while the device is still reporting progress, and a run that the device picks up late is returned to Running rather than left marked failed.
Concurrent run controls
Open Workflow run settings from the gear icon in the workflow editor header to control overlapping runs:- Allow concurrent runs of this workflow is off by default. While off, a trigger is rejected with HTTP
409whenever the same workflow already has arequested,running, orwaitingexecution. - Incompatible workflows selects other workflows from the same environment. The current workflow cannot start while any selected workflow has an in-flight execution.
allow_concurrent_executions and concurrency_blocked_by_workflow_uuids on workflow create, update, and response payloads.
Example: edge detection workflow
A camera_frame workflow that runs YOLO on the edge and emits alerts:What workflows are good at
Orchestrating multiple twins
Synchronise robots and sensors: swarm formations, multi-arm cells, or a
fleet of cameras feeding a single inspection job. Wire any twin from the
catalog into the same graph.
Reacting to the real world
Camera-frame,
MQTT, schedule, webhook, and email
triggers wake the workflow up
without you wiring anything custom.
Calling out to anything
http_request, send_email, and send_alert nodes plug Cyberwave into
the rest of your stack: PagerDuty, Slack, your warehouse system, a Notion
page.Best practices
- Keep workflows focused — create separate workflows for distinct operations rather than one large workflow. This makes debugging and maintenance easier.
- Add error handling — include condition nodes to handle failure cases gracefully. Consider what should happen if a joint can’t reach its target.
- Use meaningful names — name nodes and workflows descriptively. “Alert on person in zone A” is better than “Node 1”.
- Use
on_enteremit mode for alerts — avoids flooding with repeated events while the same object stays in frame. - Set appropriate cooldowns — balance between responsiveness and event volume. 5s is a safe default; lower for time-critical use cases.
- Eject before customising — never edit
wf_*.pyfiles directly. Copy them to a custom name and deactivate the originating workflow.
What to read next
Workflow nodes
Every node in the palette, grouped by category, with what it does and where it runs.
Running a workflow in simulation
Set the execution target to Simulation to test against a physics simulation.
Workflow API
REST schemas:
WorkflowSchema,
WorkflowExecuteSchema,
WorkflowNodeSchema.Edge-to-cloud VLM tutorial
Build the anonymize-on-edge + VLM-on-cloud workflow end-to-end.