Python quickstart

This guide connects your existing robot stack to molmoact2-so101, requests one action chunk, prints its shape and timing, and closes the cloud session. It does not send an action to the robot.

Prerequisites

You need:

Python 3.11–3.14;
a Dreamscale account;
an existing robot controller that can read camera frames and state;
a robot/model pairing listed as live in Models;
uv, or another Python package manager.

A returned action is a model output, not a safe robot command. Do not actuate until you have implemented model-to-controller conversion, bounds, velocity and acceleration limits, collision checks, watchdogs, hold behavior, and a physical e-stop.

Install the CLI and add the SDK to your project:

uv tool install dreamscale
uv add dreamscale
dreamscale login
dreamscale doctor

dreamscale login opens the dashboard in your browser. After approval, Dreamscale saves a machine credential in ~/.dreamscale/config.toml.

dreamscale doctor should finish with the core authentication and network checks ready. If it does not, follow the recovery step printed by the command or open Troubleshooting.

2. Map your robot I/O

Create robot_adapter.py in your project and implement this boundary:

robot_adapter.py

from __future__ import annotations

from collections.abc import Sequence
from typing import Protocol

from dreamscale.policy import ObservationLike


class RobotIO(Protocol):
    """Boundary between Dreamscale and your local robot stack."""

    def read_observation(self) -> ObservationLike:
        """Read cameras and state, then build a model-specific observation."""
        ...

    def validate_action(self, action: Sequence[float]) -> None:
        """Reject an action that violates local robot safety constraints."""
        ...

    def apply_action(self, action: Sequence[float]) -> None:
        """Convert a validated model action and send it to the controller."""
        ...

    def hold(self) -> None:
        """Command a safe local hold after a stop, fault, or disconnect."""
        ...


# Export one adapter instance for the quickstart script.
robot: RobotIO

For molmoact2-so101, read_observation() must call dreamscale.so101.observe(...) with side and wrist RGB frames plus six joint positions in the model’s SO-101 coordinate frame. See Model contracts before converting units.

3. Request one prediction

Save the following as first_prediction.py:

first_prediction.py

import dreamscale

from robot_adapter import robot


observation = robot.read_observation()

with dreamscale.connect(model="molmoact2-so101") as policy:
    result = policy.predict(
        observation,
        instruction="pick up the red cube",
    )
    session_id = policy.session_id

print(f"session={session_id}")
print(f"actions={len(result.actions)} dimensions={len(result.actions[0])}")
print(f"observation_to_action_ms={result.timing.obs_to_action_ms:.1f}")
print(f"transport={result.transport_mode}")
print("No action was sent to the robot.")

Run it:

uv run python first_prediction.py

A successful run prints:

session=<session-id>
actions=30 dimensions=6
observation_to_action_ms=<measured latency>
transport=quic
No action was sent to the robot.

transport may be relay when UDP is unavailable. That is a supported automatic fallback, not a failed prediction.

4. Continue safely

You have now verified authentication, worker allocation, observation encoding, transport, inference, response decoding, and session cleanup.

Learn the full lifecycle in Python SDK.
Configure a supported arm with SO-101.
Integrate inference-only DROID actions with Franka.

Use a coding agent

Copy this prompt into your coding agent from the root of your robot project:

Implement robot_adapter.py for my existing robot SDK using the RobotIO protocol
from the Dreamscale quickstart. Use dreamscale.so101.observe for the observation.
Preserve the documented SO-101 camera order, joint order, and model units.
Keep prediction non-actuating: do not call apply_action. Add explicit validation,
hold, watchdog, and e-stop integration points, and never log my Dreamscale API key.
Show me the adapter and focused tests before adding any motion path.

Need help mapping your controller? Email team@dreamscalelabs.com.

Getting started

Build with Python

Robot guides

Reference

Help

Prerequisites

2. Map your robot I/O

3. Request one prediction

4. Continue safely

Use a coding agent

​Prerequisites

​1. Install and sign in

​2. Map your robot I/O

​3. Request one prediction

​4. Continue safely

​Use a coding agent

Prerequisites

1. Install and sign in

2. Map your robot I/O

3. Request one prediction

4. Continue safely

Use a coding agent