Online controllers

Find controls in the Workbench

Open Workbench → Control and select a twin to see its actions, control methods, controller settings and related workflows. Manual inputs lists saved input mappings and opens the existing keyboard or leader-arm editor. Workflows & shortcuts lists environment tasks; it is grey when no workflows exist. Shortcuts run only in their matching Simulation or Live mode. The detailed controller settings remain available, including model/camera configuration, code and motion sequences. Adding a different input may replace the twin’s primary controller; review that change before assigning it. A saved mapping does not confirm that its device is connected. Select an action to focus its controls. In catalog Control and Workbench, Other controls keeps existing Manual inputs and Autonomy and logic settings together when they are shared across actions. In Edit, expand Controller & runtime settings for the full controller detail; operating controls stay visible in Simulation and Live. Opening or switching actions does not change a saved assignment. For a configured IK service, open End-effector → Autonomy and logic → Tool frame. Select the tool’s robot link and choose Place working point to show the 3D handles. Finish placement hides them. Expand Exact offset to enter position and rotation; position is in metres relative to the link. Save on the asset sets the default for newly added twins; Save in Workbench changes only that twin. The configured solver is retained. Saving does not move the robot or confirm collision-free operation. Use Overview to see the twin’s mappings, policies and related workflows together. SDK examples are available in the asset’s Code tab. Pin control guides, cameras or microphones to the Overview panel. Choose Arrange to show the handles and reorder them, save personal layouts, or—if you can edit the environment—save an environment default. Your personal layout takes precedence. A command-connection warning describes the connection used to send commands; it does not mean your keyboard is disconnected. Robot keys pause while you use the Overview toolbar. After closing + Pin or the layout menu with the keyboard, Tab to Resume keyboard controls and press Enter or Space to return to robot input. Clicking outside either menu restores robot input unless you move into a text field or dialog. Changing a key or gamepad button preserves that command’s saved values. Review its parameters separately to change the amount or behavior; catalog defaults initialize new bindings. Commands such as adjustable lights need a value before saving. The mapping editor shows the configured parameter and its range; expand Other parameters to use a supported alternative. For Navigate, End-effector or Joint targets, choose Open control panel to pin the supported operator control. In Simulation or Live, switch to Control. Choose a target, or expand Enter coordinates / Enter joint values; checks run automatically and Move or Go to point remains unavailable until the target can run. Live movement may require confirmation. Expand Live unavailable to see why a control works in Simulation but needs driver support for Live. The same limitation appears once for controls grouped under a twin. A hardware limitation remains unavailable in both modes; unverified support must be checked in the catalog. Switching modes or opening this guidance does not send a command. Navigation needs a current localized pose. If localization is unavailable or stale, restore the selected mapping/localization service and its sensor input before retrying. A saved map with no observed free space cannot be used for localization: capture a new map with free-space tracing or choose another map. The map remains available for inspection. Saved poses, Drive to home pose, and workflow joint movements require declared controllable joints. Complete gripper poses may include coupled fingers when they agree with the driver joint. If an imported robot is rejected, review its actuation setup and joint limits in the catalog; movable geometry alone does not establish command support. For a spatial target, choose Place target, right-click a scene point and select Set control target here. Drag the marker to adjust its position, then choose Done to hide the handles. Expand Enter coordinates for world coordinates in metres. Describe target opens the control agent for the selected twin; review its result before running it. Placing a target does not move the robot. Use Arrange to reorder pinned panels. A saved layout remembers the panel, not a destination or joint command. Missing robot capabilities remain unavailable even when a 3D model has movable joints. In Attach target evidence, saved task and model choices stay selected when the catalog refreshes. If one is unavailable, choose its replacement explicitly. Attaching a result does not run a model. For a perception action, Workflow task lists compatible environment workflows and available templates. Select a template, then choose Use template in this environment to create an inactive copy linked to the twin. This also works for an inherited template. Open Edit model & inputs to select its camera or other sensor sources; the catalog template stays unchanged. Missing setup appears beside the selected task. Saving the setup does not activate the workflow or confirm sensor availability. In Workbench, Enable starts the linked workflow’s triggers once its checks pass; Pause disables them. A blocker appears beside the task with Edit model & inputs. Cloud or Edge beside the model describes inference placement; Enabled does not confirm that results are arriving.

What is an online controller?

An online controller is a controller policy that runs in its own controller-host cloud node — separate from the simulation. The controller host communicates with a plant (the cyberwave-sim physics worker or a live robot) over MQTT and WebRTC. The plant only steps physics and publishes state; it never runs the controller logic in its own loop. This split is the defining property of online controllers: the control loop and the physics loop live in different processes, connected by a wire. Because that wire is the same whether the plant is a simulator or a real robot, an online controller can target either with no code changes.

	Plant (`cyberwave-sim` or live robot)	Controller host (cloud node)
Role	Steps physics / hardware, publishes state	Runs the controller policy
Communicates via	MQTT joint state, WebRTC frames	MQTT joint commands, WebRTC frames
Runs the control loop?	No	Yes

Cyberwave supports basic mjlab today — online controllers run against both basic MuJoCo and vectorized mjlab backends over the same wire. We’re planning to release a richer Cyberwave mjlab extension with useful helpers in the future.

Online controller types

Three policy types run on the online-controller host path:

Code

A custom Python controller you write — a control() function or a stateful controller class — optionally carrying named model weights.

Random

A random policy, optionally shaped by weights. Useful for smoke-testing a plant or establishing a baseline.

RL Task

A trained RL checkpoint exported from an RL Task, evaluated closed-loop against the plant.

Other controller policies — teleop, navigation, motion, and mlmodel/vla — do not use the online-controller host path. They run on their own command-triggered or cloud inference paths.

How controllers are routed

Routing is decided by the explicit policy type plus a structured controller family — never by keyword or name matching. When you start a run, the backend resolves the assigned policy and dispatches it to the matching controller host.

Online controller	Resolves by	Runtime view
`code` (and code + weights)	`code` policy type	MuJoCo-shaped sim view
`random`	structured `random` family	MuJoCo-shaped sim view
`rltask`	structured RL-task family	`SimulationLike` interface

Runtime interfaces

Each online controller interacts with its plant through a sim-shaped interface, so your controller code reads state and writes commands without knowing whether the plant is simulated or live.

code and code + weights controllers see a MuJoCo-shaped sim view — a familiar sim.data / sim.model surface for reading joint state and writing controls.
rltask (RL) policies use a SimulationLike interface — the same observation/action contract an RL policy expects during training.

Keep these as conceptual contracts: your controller reads observations and writes actions each step; the host handles transport to and from the plant.

Authoring code controllers

Code controllers support two authoring modes.

Function mode (default)

Define a control function. The host calls it each control step.

def control(sim, sim_time, artifacts=None):
    # Read state from the sim view, compute, and write controls.
    sim.data.ctrl[:] = 0.0

sim — the MuJoCo-shaped sim view (read state, write ctrl).
sim_time — current simulation time in seconds.
artifacts — a dict of named weights/files (present only for code + weights controllers).

Class mode (`entrypoint_type="class"`)

For stateful controllers that load weights once and keep state across steps, use class mode. The host instantiates the class once, then calls it each step.

class Controller:
    def __init__(self, sim, artifacts=None):
        # Load weights, allocate buffers, set up state once.
        self.sim = sim

    def __call__(self, sim_time):
        # Called each control step.
        self.sim.data.ctrl[:] = 0.0

Set entrypoint_type="class" on the policy to opt into class mode. Use it whenever your controller needs to load model weights or maintain internal state between steps.

Named artifacts and weights

A code + weights controller attaches one or more named binary files — typically .pt, .onnx, or .safetensors. Each artifact carries:

Field	Meaning
Filename	The runtime key your code uses to look the artifact up.
Role	Optional label describing what the artifact is.
Primary	A flag marking the main artifact for the controller.

The artifacts reach your code differently per authoring mode:

Function mode — delivered as the third positional argument, the artifacts dict.
Class mode — delivered to __init__ as the artifacts argument, so you can load them once.

Class mode plus named artifacts is the canonical pattern for a trained policy: load the primary checkpoint in __init__, then run inference each step in __call__.

Running a skill from the control agent

In Simulate → Agent, describe the skill and any run limit, then select Plan. Check the selected robot, policy and limits before executing; start the required simulation first. The assistant follows the controller’s current run status, and cancelling that action stops only that run. A completed run does not prove task success—check its policy evidence and Replay separately. The assistant keeps a trained skill’s saved settings unless it exposes a supported command input. Use a policy-step limit to bound these runs; a duration alone is not currently supported. A robot accepting velocity commands does not mean every policy on that robot accepts speed or gait overrides.

CPU vs GPU compute

Controller policies that carry a model — mlmodel/vla, random, or code-with-weights — accept an inference device. This choice selects where the controller host runs inference and is independent of the simulation’s physics device.

`device`	Where it runs	When to use
`cpu` (default)	A cheap CPU host	Lightweight inference; the default for any model-carrying policy.
`gpu`	A GPU host	Heavier policy inference that benefits from a GPU.

Key rules:

cpu is the default. It runs on an inexpensive CPU host.
The saved device is just the default. You can override it per-run at deploy time without changing the saved policy.
device is rejected for policies that carry no model — for example a plain code controller or a teleop policy. Those have nothing to run inference on.

The device choice is purely about controller inference. It does not affect which device the plant uses to step physics.

Live mode

Because the controller host talks to its plant purely over MQTT and WebRTC, the same code, random, or rltask controller can target a live robot plant instead of cyberwave-sim — with no controller code changes. The controller reads state and writes commands exactly as it does in simulation; only the plant on the other end of the wire changes.

Simulation backends

Online controllers run against two simulation backends over the same wire:

Basic MuJoCo — a single MjModel / MjData plant.
Vectorized mjlab — a manager-based, GPU-capable plant.

Your controller does not need to know which backend the plant uses; the runtime interface is the same.

Quick example

Create a code controller policy, then run it against a twin.

Create the controller policy

Create a code policy with your control function (or class).

POST /api/v1/controller-policies

Run it on a twin

Execute the policy against a robot twin. The backend dispatches the controller to its host, which drives the plant.

POST /api/v1/controller-policies/{uuid}/execute

Stop the run

Stop a single policy run, or stop every online controller in an environment at once.

POST /api/v1/controller-policies/{uuid}/stop
POST /api/v1/controller-policies/stop-environment-controllers

A minimal code controller body:

def control(sim, sim_time, artifacts=None):
    # Hold all joints at zero command.
    sim.data.ctrl[:] = 0.0

Deploy a trained RL policy

An rltask controller is created by publishing a trained checkpoint, then assigned to a twin like any other controller. Using the OpenArm pick-up policy from the RL task walkthrough:

import requests
from cyberwave import Cyberwave

cw = Cyberwave()

# 1. Publish a trained checkpoint as an rltask controller policy.
publish = requests.post(
    f"{cw.config.base_url}/api/v1/rl-tasks/<rl-task-uuid>/checkpoints/<checkpoint-uuid>/publish-controller",
    headers={"Authorization": f"Bearer {cw.config.api_key}"},
    json={"controller_name": "openarm-pickup-policy"},
)
publish.raise_for_status()
controller_uuid = publish.json()["controller_policy_uuid"]

# 2. Assign it to the arm twin (first argument is the twin UUID).
cw.twins.update("<openarm-twin-uuid>", controller_policy_uuid=controller_uuid)

Then start a simulation from the environment’s Simulate tab in the dashboard — the backend resolves the assigned policy and dispatches it to its controller host automatically. See Uploading Policies for how the checkpoint and controller are produced.

API reference

Method	Path	Purpose
`GET`	`/api/v1/controller-policies`	List controller policies.
`POST`	`/api/v1/controller-policies`	Create a controller policy.
`GET`	`/api/v1/controller-policies/{uuid}`	Get a controller policy.
`PUT`	`/api/v1/controller-policies/{uuid}`	Update a policy, including the saved `device`.
`DELETE`	`/api/v1/controller-policies/{uuid}`	Delete a controller policy.
`POST`	`/api/v1/controller-policies/{uuid}/execute`	Run the policy on a twin.
`POST`	`/api/v1/controller-policies/{uuid}/stop`	Stop a policy/twin run.
`POST`	`/api/v1/controller-policies/stop-environment-controllers`	Stop all online controllers in an environment.
`POST`	`/api/v1/controller-policies/{uuid}/clone`	Duplicate a controller policy.
`GET`	`/api/v1/controller-policies/{uuid}/rl-task-provenance`	Get RL-task provenance for a policy.

Control setup

In Workbench / Control, select a twin. Overview shows its configured inputs, policies and workflow-backed services together. Each saved service links to its action setup, including any missing inputs or changed references. Select an action to review Autonomy and logic, its input, and Advanced settings. Other controls retains the original shared settings. Related workflows appear in Overview. The selected model shows the kind of output it produces. Relative depth has no metric distances; Metric depth still needs camera calibration and a suitable mapping pipeline. A path predicted in an image is not a robot navigation route. Catalog services identify reusable Workflow templates; Workbench shows the state of the environment workflow. If a required workflow input comes from a disabled or removed node, Control shows the missing input. Use Edit model & inputs to restore or replace its source. Restoring the configuration does not start the workflow. In Maps, Point projection identifies a grid made from point-cloud observations. Unobserved cells remain unknown. Legacy grid preserves an older grid for inspection; review its source and calibration before navigation. Viewing these maps keeps their original downloads. Waiting for first map means the stream has not supplied a map image yet. Maps remains available in the right panel in Edit, Simulate and Live, including when no robot is selected. Select a robot to use its declared mapping service. Monitor keeps mapping controls read-only. Control requires edit access; in Simulate, start a simulation before starting a map. Saved maps remain viewable when the run stops. Generating a map from authored geometry remains in Edit. For a configured mapping service, Maps shows the robot’s service under Autonomy and logic and offers its supported map types. Missing sensor setup blocks Start mapping. Legacy sensor mapping retains an older configuration for review. Requesting mapping does not confirm that its runtime is connected or that a map has arrived. Map details shows the source robot, status, resolution and recorded service. Expand Technical details to inspect or copy the complete record. If a simulation ends before mapping finishes, the map is marked Interrupted and received snapshots are retained. A saved map still needs coverage and alignment checks before use for navigation. Catalog Control has three sections: Control services, Hardware drivers and Catalog preview. Control services uses the same action organization as Workbench. Editors can change setup rules under an action’s Advanced settings; hardware capabilities remain in Capabilities. Adding a twin copies saved asset action settings into that twin. Workbench edits stay local to it; the reusable input preset and asset defaults are unchanged. From asset defaults and Customized for this twin identify the saved scope. These action settings do not activate inputs yet. Use Add input to select an existing preset. Supported joint keys appear From preset. Edit keys customizes the action; Reset to preset removes that customization. Clearing every key keeps the action empty until you reset or map new keys. The reusable preset is unchanged. During editing, expand Current input setup to inspect the existing controls. From Overview, Edit mapping opens that action’s input settings directly. You can collapse the settings without losing unsaved changes. Read-only users can View mapping. For a standard command keyboard, Use standard keys fills supported keys for the selected action. Review them, then Save. The same keyboard can serve Drive, Camera and Lights with separate mappings. Existing custom keys are retained; use Edit keys to add commands that need your own values or choices. Save stores your action settings without starting a robot. The selected service appears under Autonomy and logic; its configuration details stay beside the selector. Use the operating panels in Workbench to control a robot. Saving does not activate inputs; pairing, calibration and runtime readiness are checked on the twin. Direct control means the action uses its configured manual inputs without an action policy. When compatible policies exist, you can select one or return to Direct control while retaining your input mappings. Actions that require a policy still show Not configured until one is selected. This choice does not certify that the simulator or hardware is ready. The operating panels can list supported joints even before the 3D model loads. Enter targets in the displayed units and review them before moving. Changing a target requires a new review; motion requires a ready execution route. Control setup remains configuration only. For an immediate simulation move, Queued means the command was sent, not that the robot reached its target. Updated simulators report progress while running and confirm completion from measured joint positions. Older simulators may report only when the simulation ends. A pending status alone is not a reason to repeat the move. Publishing failures are reported as errors. When a keyboard command needs values, its mapping editor shows a Parameters step after you choose a key. For example, a configured gripper can offer grip, release or reset. Complete required values before saving. Reopening the same preset in Catalog or Workbench preserves the saved parameters. Editing parameters requires saving them; Assign as-is uses only an unchanged, complete preset. Saving a mapping does not verify a connected device or execute its command. In Workbench / Control, Add action opens the same picker as the catalog. Choose a declared action to configure its manual inputs and logic inline. Configuration pages do not start a robot or embed a test panel. Additional legacy setup paths remain under More actions. Opening setup does not start control.

Where to go next

RL Tasks

Train and export RL policies to run as rltask online controllers.

Uploading Policies

Bring your own code and weights as a controller policy.

Simulation

How the simulation plant steps physics and publishes state.

In an action’s Advanced settings, use Show operator panel to hide its on-screen target control. Catalog settings apply when adding new twins; Workbench settings apply to the selected twin. A saved pin stays in your layout with a hidden-state message. SDK, agent and workflow access are unchanged. Existing shared keyboard guides are managed separately. In Workbench → Control → Overview, use Edit mapping to change supported keyboard keys for that twin. Joint and command keyboards reuse their existing editors. Command-key edits preserve the saved movement, camera and lighting commands and their values. Saving preserves the shared preset and other twins’ mappings. If the input or keys changed elsewhere, reload before saving. For a robot with attached twins, select each twin’s saved keyboard mappings in Workbench → Control → Overview. Distinct keys can stay selected together. Pause input affects only the selected twin; conflicting keys explain what to change before activation. Restore previous environment inputs returns all twins to their previous input assignments. Multiple gamepad inputs cannot yet be selected together. With driver-based keyboard controls, switching windows pauses held input. After returning or restoring the command connection, release held keys and press again. For a calibrated leader-arm preset, use Map joints to pair each servo with a robot joint. Arrange mapping enables drag placement; Done hides it. Optional aliases stay under Advanced. Catalog edits update the shared preset; calibrate the connected leader on a twin before operating. In Workbench, Use input assigns an unchanged preset; Save & use input saves mapping edits and assigns it. Those edits affect every twin using the preset. Existing legacy presets keep their current editor. New input choices follow the selected action. A saved input that conflicts with that action shows Deprecated mapping. Use Review migration to remove or replace it, then Save. The shared preset is retained. Needs mapping means setup is incomplete; saving does not verify a connected device. Keyboard and gamepad mappings stay visible while a physics simulation starts or is stopped. Controls pause until the simulator is ready; Playground controls remain available without starting a backend simulation. The compact joint guide shows the last commanded Target and Δ, the difference from the reported position. No feedback or Feedback stale means it cannot confirm the current position. In Playground, the readout follows the scene; a physics simulation needs its own feedback. Angle units can change without enabling control; linear joints remain in metres. Pinned navigation and joint target panels follow the same readiness state. You can enter targets while waiting; they are checked automatically when the simulator is ready. Checking a target does not move the robot.

Get started

AI agents

AI models

Control

Learn

Run on edge or cloud

Platform

For integrators

Help

Find controls in the Workbench

What is an online controller?

Online controller types

Code

Random

RL Task

How controllers are routed

Runtime interfaces

Authoring code controllers

Function mode (default)

Class mode (`entrypoint_type="class"`)

Named artifacts and weights

Running a skill from the control agent

CPU vs GPU compute

Live mode

Simulation backends

Quick example

Deploy a trained RL policy

API reference

Control setup

Where to go next

RL Tasks

Uploading Policies

Simulation

​Find controls in the Workbench

​What is an online controller?

​Online controller types

Code

Random

RL Task

​How controllers are routed

​Runtime interfaces

​Authoring code controllers

​Function mode (default)

​Class mode (entrypoint_type="class")

​Named artifacts and weights

​Running a skill from the control agent

​CPU vs GPU compute

​Live mode

​Simulation backends

​Quick example

​Deploy a trained RL policy

​API reference

​Control setup

​Where to go next

RL Tasks

Uploading Policies

Simulation

Find controls in the Workbench

What is an online controller?

Online controller types

How controllers are routed

Runtime interfaces

Authoring code controllers

Function mode (default)

Class mode (`entrypoint_type="class"`)

Named artifacts and weights

Running a skill from the control agent

CPU vs GPU compute

Live mode

Simulation backends

Quick example

Deploy a trained RL policy

API reference

Control setup

Where to go next