> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyberwave.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
> Automate robot operations with visual workflow orchestration
## What are Workflows?
Workflows in Cyberwave let you create automated sequences of robot operations. Connect nodes visually to build complex behaviors without writing procedural code.
Workflows run either **on the cloud** (Celery tasks — for manual, schedule, webhook, event, MQTT, and email triggers) or **on the edge device** (for `camera_frame` triggers that run ML inference locally without sending video to the cloud).
***
## Workflow Components
### Nodes
Nodes are the building blocks of workflows. Each node performs a specific action.
> stub: Nodes are organised into a hybrid robotics + automation taxonomy. The same categories show up in the editor palette and on `GET /api/v1/workflows/config` (`node_categories`) — backend, API, and UI all read from the same `WorkflowNodeCategory` enum (`cyberwave-backend/src/lib/node_categories.py`). Categories with no nodes today (Perception) are reserved and only show up once we ship nodes for them.
Start the workflow on an event, schedule, or incoming message: manual,
schedule, webhook, event, MQTT, email, camera\_frame, audio\_track, alert
Pull snapshots and samples from sensors, cameras, and external systems on
demand: `data_source`, `twin` (twin + controller metadata for voice
pipelines)
Convert raw signals into reliable observations — reserved for object
trackers, sensor fusion, IMU filtering, ASR (no nodes ship today)
Reshape, convert, route, multiplex, or fan out data: `json_parser`,
`fuzzy_matcher`, `annotate`, `anonymize`
Store and retrieve memory over time: `create_asset`, `edit_asset`,
`create_attachment`, `update_attachment`, `video_tagger`
Use models for interpretation, reasoning, or prediction: `call_model` (cloud
VLM/LLM and edge ML)
Choose what happens next: `conditional`, `loop`; FSM / Behavior Tree / Rule
Engine on the roadmap
Execute physical or twin-side actions: `twin_control` (Move Twin),
`virtual_controller` (MQTT controller commands), `recorder` (start/stop
audio/video recording via media service); future joint / gripper primitives
Talk to external systems and run user-supplied logic: `http_request`,
`send_email`, `code` (edge-only)
Guard, validate, observe, and alert: `send_alert`; validators, watchdogs,
e-stop guards, and anomaly detectors are on the roadmap
### Connections
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: self-connections, cycles, and invalid pairings (e.g. `camera_frame` triggers can only connect to `call_model` nodes) are blocked.
***
## Creating a Workflow
> stub: Workflows now have an editable `slug` that is unique within a workspace. You can keep the generated slug or customize it for stable SDK and automation references. Workflows can also be marked `public` from the workflow creation and editing UI.
### Using the Dashboard
1. Navigate to **Workflows** in the dashboard
2. Click **Create Workflow** — set a name, optional slug, and visibility
3. Drag nodes from the palette to the canvas
4. Connect nodes by dragging from output to input ports
5. Configure each node's parameters
6. Click **Activate**
> stub: The workflow canvas supports two ways to multi-select nodes:
>
> * **Modifier-click** — hold **Cmd / Ctrl / Alt** and click nodes to add them to (or remove them from) the current selection. Works without entering any tool. The previously-selected single node is folded into the group on the first modifier-click. Click the canvas background to clear the whole group.
> * **Multi-select tool** (bottom-right toolbar) — toggle it on, then marquee-drag across the canvas or **Shift-click** individual nodes to pick a group. Press **Esc** to leave the tool.
>
> Once a group is selected (either way), drag any selected node to shift the whole group, and press **Delete** / **Backspace** or the floating **Delete** button to remove them in bulk.
> stub: The workflow editor supports undo (**Ctrl/Cmd + Z**) and redo (**Ctrl/Cmd + Shift + Z**, or **Ctrl + Y**), with up to 50 steps per session. It covers node creation, deletion (single & bulk), node moves (single & group), connection wiring, node renames / notes, and workflow-level changes (name, description, slug, visibility, activation). Toolbar buttons next to the **Hide/Show Nodes** button mirror the same actions.
> stub: The workflow editor toolbar exposes an **Add Note** button that drops a Jupyter-style sticky note on the canvas. Notes pan/zoom with the rest of the workflow, support drag-to-move, drag-to-resize, six colours, and inline content editing on double-click (**Ctrl/Cmd + Enter** to save, **Esc** to cancel). They are persisted inside `workflow.metadata.notes` rather than as workflow nodes, so they never reach the execution engine and stay purely as authoring annotations.
> stub: Workflows created from the dedicated **Workflows** page are `general` workflows. From an environment, Cyberwave can also create `mission` workflows that stay bound to that environment and reuse the same workflow editor/runtime with a mission-specific profile layered on top.
> stub: Mission workflows now expose a **Move Twin** node that targets an environment waypoint. The node waits for navigation completion before continuing and can optionally dwell at the waypoint for a configured number of seconds.
### Using the CLI
```bash theme={null}
cyberwave workflow list # list workflows
cyberwave workflow create -n "Name" # create a workflow
cyberwave workflow create --template motion-detection
cyberwave workflow show # show details (interactive)
cyberwave workflow sync # sync to edge device(s)
cyberwave workflow sync --edge-active # filter selector to active edge workflows
cyberwave workflow activate # activate (interactive)
cyberwave workflow deactivate # deactivate (interactive)
cyberwave workflow delete --yes
```
All subcommands accept `--base-url` / `-u` to override the API URL. When a UUID argument is omitted, an interactive arrow-key selector is shown.
### Using the SDK
```python theme={null}
from cyberwave import Cyberwave
cw = Cyberwave(api_key="your_api_key")
workflows = cw.workflows.list()
run = cw.workflows.trigger("workflow-uuid", inputs={"speed": 0.5})
run.wait(timeout=60)
print(f"Workflow finished: {run.status}")
```
***
## Executing Workflows
### Manual Execution
```python theme={null}
run = cw.workflows.trigger("workflow-uuid")
print(f"Run ID: {run.uuid}, Status: {run.status}")
```
### Triggered Execution
Workflows can be triggered by:
* **Schedule**: Run at specific times (cron)
* **Events**: Run when sensor data matches conditions
* **API**: Trigger from external systems via REST or MCP
* **Camera Frame**: Run on every camera frame at the edge device
* **Audio Track**: Run on every audio chunk from an edge microphone ([docs](/feature-reference/workflows/audio-track/overview))
***
## 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 shipping `wf_*.py`.
See **[Edge workflow dependencies](/feature-reference/workflows/edge-dependencies)** for the full matrix (compile server `base.txt`, edge worker extras, catalog STT models).
| Doc | Topic |
| -------------------------------------------------------------------------- | ------------------------------------ |
| [Audio in Workflows](/feature-reference/workflows/audio-in-workflows) | PCM format, pipeline, compile checks |
| [Call Model STT on edge](/feature-reference/workflows/call-model-stt-edge) | Whisper.cpp vs Faster Whisper |
| [Fuzzy Matcher](/feature-reference/workflows/fuzzy-matcher) | Command matching after STT |
| [Twin](/feature-reference/workflows/twin) | Twin + policy outputs → candidates |
| [Virtual Controller](/feature-reference/workflows/virtual-controller) | MQTT dispatch |
***
## Edge Workflows (Camera Frame)
The `camera_frame` trigger generates a Python worker (`wf_.py`) that runs ML inference directly on the edge device.
To raise alerts from detections, wire an explicit `send_alert` node downstream of `call_model`. Optionally insert:
* a `detection_event_gate` to filter classes / fire `on_enter` or `on_change`, and
* a `timed_condition` (`mode: debounce`) to enforce a cooldown.
The legacy `emit_event` parameter on `call_model` is no longer compiled — see the [`emit_event` migration](/use-cyberwave/workflows#migrating-from-emit_event) on the workflows page.
Sync to the edge with `cyberwave workflow sync` or wait for the automatic periodic sync.
> stub: When a `call_model` node sits downstream of a `camera_frame` trigger, the model picker splits the catalog into a **Compatible models** section (always visible) and a collapsed **Incompatible models** section. The gate rejects (in priority order): cloud-only deployments; models that don't accept image input; models tagged `classification` (single-label classifiers can't drive bbox / mask filters); and models whose `output_family` is `text` / `action` / `mesh` / `image`. Models with `output_family = json` or unset are accepted — most edge YOLO seeds resolve to `json` today and are the canonical use case. Toggle **Show incompatible models** to expand the rejected section for inspection; the cards remain disabled because the gate reflects real edge-codegen incompatibility.
> stub: The same gate runs at compile time. `cyberwave workflow sync` (and any other path that triggers worker codegen) fails fast with a named error if a `call_model` references an incompatible model — no more silently-dropped chains in the generated worker. Persisting an incompatible selection (or importing a workflow that already has one) is rejected at compile time.
See [Edge Workers](/feature-reference/workflows/workers/overview) for the full generated worker lifecycle and format.
***
## Monitoring Executions
Track workflow execution status and results:
```python theme={null}
runs = cw.workflow_runs.list(workflow_uuid="workflow-uuid")
for run in runs:
print(f"Status: {run.status}, Started: {run.started_at}")
```
Each execution tracks status at both the workflow level and individual node level, including `started_at`, `finished_at`, and `error_message` fields.
***
## Example: Edge Detection Workflow
A `camera_frame` workflow that runs YOLO on the edge and emits alerts:
```mermaid theme={null}
flowchart LR
A[Camera Frame Trigger] --> B[Call Model: YOLOv8]
B --> C{Detection?}
C -->|Yes| D[Publish Event]
C -->|No| E[Skip]
```
***
## Best Practices
Create separate workflows for distinct operations rather than one large workflow. This makes debugging and maintenance easier.
Include condition nodes to handle failure cases gracefully. Consider what should happen if a joint can't reach its target.
Name nodes and workflows descriptively. "Alert on person in zone A" is better than "Node 1".
Use `on_enter` for alert-style use cases (person entering a zone) and
`on_change` for occupancy tracking. Set `cooldown_seconds` to avoid event floods.
***
## Next Steps
Voice pipeline packages (compile + edge + STT catalog)
Full workflow API documentation
Generated workers, eject pattern, and custom workers