Uploading policies

What is a trained policy?

A trained policy is a checkpoint — the model weights produced by training an RL task locally with cyberwave-rl or cyberwave-rl-experimental (for example a best_agent.pt). The checkpoint belongs to the RL task it was trained against: you author and export the task, train it on your own machine or GPU, then upload the resulting checkpoint back to the same RL task so the platform can serve it. Once a checkpoint lives on its RL task you can:

Publish it as an online controller and assign it to a twin.
Run cloud inference that loops live joint state through the policy.
Pull it back into MuJoCo locally to replay it with the Python SDK.

Everything below happens in the Policies tab of the RL task editor (or through the matching REST / Python SDK calls).

Supported checkpoint contract

Read this section before training or uploading. File storage accepts weights; successful upload does not establish that the hosted controller can execute them. The current legacy hosted path loads skrl agent checkpoints produced for an exported Cyberwave RL task using cyberwave-rl or cyberwave-rl-experimental. Register genuine skrl checkpoints with metadata={"checkpoint_format": "skrl"} through the MCP checkpoint registration operation. File extensions such as .pt do not identify the runtime format. Arbitrary PyTorch modules, TorchScript actors, and Stable-Baselines3 checkpoints are not currently supported by this path; renaming files or declaring them as skrl does not convert them. Follow RL Tasks for the exported task/source contract and Train an RL Policy for the training workflow. Keep the checkpoint paired with its task’s observation ordering and history, preprocessing, action ordering/scaling and units, control timing, runtime versions and dependencies. Custom observation/action logic belongs in the task’s supported source/configuration interfaces, not just in a weights file or dimension metadata. Manifest-based policies retain their separate provenance/evaluation requirements. With MCP, call cw_deploy_rl_policy(operation="inspect", rl_task_uuid=...) before training for documentation links and again after registration for compatibility blockers. Checks at publication, assignment and start are static checks, not proof of successful execution. Validate the complete policy in simulation before live use.

Resetting a hosted simulation

Use cw_stop_simulation, then cw_start_simulation to reset. Each start creates a fresh simulation workload and worker with new MuJoCo model/data loaded from the current scene configuration. Stop also stops the environment’s controllers. Wait for the new simulation to be running before starting the assigned controller, or explicitly request auto_run_controllers when starting the simulation. There is no separate in-place episode-reset API. Keep scene configuration, initial conditions and any randomization consistent when comparing trials.

The happy path

Train locally

Export your RL task, then train it with cyberwave-rl / cyberwave-rl-experimental on your own machine. Training produces a checkpoint file such as best_agent.pt.

Upload the checkpoint

Upload the checkpoint file back to its RL task — via the dashboard, the Python SDK, or REST. Runtime and policy-interface fields are inherited from the parent RL task.

Use the policy

Choose one (or more):

Publish as a controller — turn the checkpoint into an assignable online controller.
Run inference — dispatch a cloud workload that drives a twin through the policy over MQTT.
Use in MuJoCo locally — download the checkpoint with the SDK and replay it locally.

Upload a checkpoint

Uploading stores the weights and registers the checkpoint against the RL task in a single call. The new checkpoint inherits the parent task’s runtime target, accelerator, version pins, and policy interface.

File uploads accept .pt, .pth, or .zip only, up to a maximum size of 512 MB. For weights that exceed this limit, register an external URL instead.

Dashboard
Python SDK
REST

Open the RL task and go to the Policies tab.
Choose Upload checkpoint and select your .pt / .pth / .zip file.
Optionally give it a name and description.

Uploaded checkpoints appear in the list with an Uploaded badge (URL-registered ones show a URL badge). Each row exposes Download and Delete.

from cyberwave import Cyberwave
from cyberwave.rl_tasks import RLTaskClient

cw = Cyberwave()          # reads CYBERWAVE_BASE_URL + CYBERWAVE_API_KEY
rl = RLTaskClient(cw)

checkpoint = rl.upload_checkpoint(
    "<rl-task-uuid>",
    "logs/openarm-pickup/run-1/checkpoints/best_agent.pt",
    name="best_agent",
    description="OpenArm pick-up, 1M steps",
)
print(checkpoint["uuid"])

curl -X POST \
  "$CYBERWAVE_BASE_URL/api/v1/rl-tasks/<rl-task-uuid>/checkpoints/upload" \
  -H "Authorization: Bearer $CYBERWAVE_API_KEY" \
  -F "file=@logs/openarm-pickup/run-1/checkpoints/best_agent.pt" \
  -F "name=best_agent" \
  -F "description=OpenArm pick-up, 1M steps"

Register an external URL

If your weights are already hosted elsewhere, register them by URL instead of uploading bytes. This path also lets you override the inherited runtime target, accelerator, version pins, and policy interface.

Python SDK
REST

from cyberwave import Cyberwave
from cyberwave.rl_tasks import RLTaskClient

cw = Cyberwave()
rl = RLTaskClient(cw)

checkpoint = rl.register_checkpoint(
    "<rl-task-uuid>",
    name="best_agent (remote)",
    weights_url="https://example.com/weights/best_agent.pt",
)

curl -X POST \
  "$CYBERWAVE_BASE_URL/api/v1/rl-tasks/<rl-task-uuid>/checkpoints" \
  -H "Authorization: Bearer $CYBERWAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "weights_url": "https://example.com/weights/best_agent.pt",
    "name": "best_agent (remote)"
  }'

List, inspect, and remove checkpoints with GET .../checkpoints, GET .../checkpoints/{checkpoint-uuid}, and DELETE .../checkpoints/{checkpoint-uuid}. See the endpoint reference.

Publish as a controller

Publishing a checkpoint creates a ControllerPolicy — an rltask online controller that you can assign to a twin. The controller runs the policy in its own controller-host cloud node and drives the plant over MQTT, so the same policy can target a simulated or a live robot.

Dashboard
REST

From the Policies tab, select a checkpoint and choose Publish as controller. Optionally set a controller name and description.

curl -X POST \
  "$CYBERWAVE_BASE_URL/api/v1/rl-tasks/<rl-task-uuid>/checkpoints/<checkpoint-uuid>/publish-controller" \
  -H "Authorization: Bearer $CYBERWAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "controller_name": "my-policy-online",
    "controller_description": "Published from best_agent checkpoint"
  }'

The response includes the new controller policy’s controller_policy_uuid and controller_policy_slug. From there it behaves like any other online controller — see Online controllers for assigning and running it.

Run inference

Inference dispatches a cloud workload that loads the checkpoint, loops Cyberwave joint state through the policy, and publishes commands over MQTT.

This inference path does not run MuJoCo. It is a state-through-policy loop — live joint state in, policy commands out — not a physics rollout. If you want a full physics simulation, use a simulated plant with an online controller instead.

Python SDK
REST

from cyberwave import Cyberwave
from cyberwave.rl_tasks import RLTaskClient

cw = Cyberwave()
rl = RLTaskClient(cw)

run = rl.launch_inference(
    "<rl-task-uuid>",
    checkpoint_uuid="<checkpoint-uuid>",
    twin_uuid="<twin-uuid>",   # the robot twin to drive
    max_steps=1000,
    control_rate_hz=50,
)
print(run["uuid"])

# Later: list past runs (each row links to its cloud workload).
for r in rl.list_inference_runs("<rl-task-uuid>"):
    print(r["uuid"], r.get("workload_uuid"))

curl -X POST \
  "$CYBERWAVE_BASE_URL/api/v1/rl-tasks/<rl-task-uuid>/inference" \
  -H "Authorization: Bearer $CYBERWAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "checkpoint_uuid": "<checkpoint-uuid>",
    "twin_uuid": "<twin-uuid>",
    "max_steps": 1000,
    "control_rate_hz": 50
  }'

checkpoint_uuid (preferred) selects which policy to run.
twin_uuid is the robot twin the policy drives.
mode, max_steps, and control_rate_hz are optional and tune the loop.

List past inference runs with GET /api/v1/rl-tasks/{uuid}/inference.

Use in MuJoCo locally

To replay a checkpoint in MuJoCo on your own machine, select it in the Policies tab — the dashboard reveals a copy-paste snippet that uses the Python SDK to download the checkpoint, stage it into the layout cyberwave-rl’s play step expects, and play it locally.

from cyberwave import Cyberwave
from cyberwave.rl_tasks import RLTaskClient

cw = Cyberwave()
rl = RLTaskClient(cw)

# 1. Download the registered checkpoint's weights.
local = rl.download_checkpoint(
    "<rl-task-uuid>",
    "<checkpoint-uuid>",
    destination="/tmp/best_agent.pt",
)

# 2. Stage it into the layout cyberwave-rl's play step expects:
#    logs/<task_id>/uploaded/checkpoints/best_agent.pt
staged = RLTaskClient.prepare_checkpoint_for_play(
    task_id="OpenArm-pick-up-demo",
    checkpoint_path=local,
)
print(f"Staged checkpoint at: {staged}")

# 3. Run cyberwave-rl's play entrypoint against the staged run.

The Python SDK exposes upload_checkpoint(...), download_checkpoint(...), and the static prepare_checkpoint_for_play(...) helper on RLTaskClient, so the full round trip — train, upload, replay — stays in one place.

Endpoint reference

Method	Path	Purpose
`POST`	`/api/v1/rl-tasks/{uuid}/checkpoints/upload`	Upload a checkpoint file (`.pt` / `.pth` / `.zip`, max 512 MB) and register it.
`POST`	`/api/v1/rl-tasks/{uuid}/checkpoints`	Register a checkpoint by external `weights_url`.
`GET`	`/api/v1/rl-tasks/{uuid}/checkpoints`	List checkpoints for an RL task.
`GET`	`/api/v1/rl-tasks/{uuid}/checkpoints/{checkpoint_uuid}`	Get a single checkpoint.
`DELETE`	`/api/v1/rl-tasks/{uuid}/checkpoints/{checkpoint_uuid}`	Delete a checkpoint.
`POST`	`/api/v1/rl-tasks/{uuid}/checkpoints/{checkpoint_uuid}/publish-controller`	Publish a checkpoint as an `rltask` online controller.
`POST`	`/api/v1/rl-tasks/{uuid}/inference`	Dispatch a cloud inference run (state-through-policy, no MuJoCo).
`GET`	`/api/v1/rl-tasks/{uuid}/inference`	List inference runs.

Where to go next

RL Tasks

Author, export, and train the RL task a checkpoint belongs to.

Online controllers

Run a published policy in its own controller host against a simulated or live robot.

Model catalog

Explore other model types and training flows on the platform.

Get started

AI agents

AI models

Control

Learn

Run on edge or cloud

Platform

For integrators

Help

What is a trained policy?

Supported checkpoint contract

Resetting a hosted simulation

The happy path

Upload a checkpoint

Register an external URL

Publish as a controller

Run inference

Use in MuJoCo locally

Endpoint reference

Where to go next

RL Tasks

Online controllers

Model catalog

​What is a trained policy?

​Supported checkpoint contract

​Resetting a hosted simulation

​The happy path

​Upload a checkpoint

​Register an external URL

​Publish as a controller

​Run inference

​Use in MuJoCo locally

​Endpoint reference

​Where to go next

RL Tasks

Online controllers

Model catalog

What is a trained policy?

Supported checkpoint contract

Resetting a hosted simulation

The happy path

Upload a checkpoint

Register an external URL

Publish as a controller

Run inference

Use in MuJoCo locally

Endpoint reference

Where to go next