Online Controllers

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__.

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.

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.

Concepts

Platform Features

Cyberwave Edge

Technical Reference

Use-Case Recipes

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

CPU vs GPU compute

Live mode

Simulation backends

Quick example

Deploy a trained RL policy

API reference

Where to go next

RL Tasks

Uploading Policies

Simulation

​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

​CPU vs GPU compute

​Live mode

​Simulation backends

​Quick example

​Deploy a trained RL policy

​API reference

​Where to go next

RL Tasks

Uploading Policies

Simulation

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

CPU vs GPU compute

Live mode

Simulation backends

Quick example

Deploy a trained RL policy

API reference

Where to go next