> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dreamscalelabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Treat the Dreamscale CLI and Python SDK as the supported public integration surfaces.
> Prefer `dreamscale run <robot>` for supported robots and `dreamscale.connect(model)` with `predict` or `next_action` in Python.
> Do not infer or recommend internal control-plane APIs.

# Python SDK quick start

> Install the Python SDK, get your first action chunk without a robot, then drive your robot with next_action.

Call a model on a cloud GPU from your own robot, simulator or pipeline. No GPU
or robot needed to try it.

## What you need

* Python 3.11 or newer, in a project (`uv init` makes one).
* A Dreamscale account. Sign in once with `uv run dreamscale login`, or set
  `DREAMSCALE_API_KEY` to a key from
  [Settings → API keys](https://app.dreamscalelabs.com/dashboard/settings#api-keys).

## Install

```bash theme={null}
uv add dreamscale
```

`uv run python -c "import dreamscale; print(dreamscale.__version__)"` prints
`0.1.0a105` or newer.

## Get one action chunk

This runs as-is. It sends blank frames and a zero state to `pi05-libero`, the
π0.5 model for the LIBERO simulator:

```python theme={null}
import numpy as np

import dreamscale

policy = dreamscale.connect("pi05-libero")
frame = np.zeros((256, 256, 3), dtype=np.uint8)  # H×W×3 uint8 RGB
observation = dreamscale.libero.observe(
    agent_frame=frame,
    wrist_frame=frame,
    state=[0.0] * 8,
)
chunk = policy.predict(observation, instruction="pick up the black bowl")
print(len(chunk.actions), "x", len(chunk.actions[0]))
```

It prints `20 x 7`: 20 actions of 7 values. `connect` returns when a GPU is
ready; if every GPU is busy, it waits in a queue and shows your position. Now
replace the frames and state with your own. See [Models](/models) for each
robot's observation and actions.

## Drive a robot

<Warning>
  The robot will move. Enforce joint, speed and workspace limits locally, and
  keep a physical e-stop within reach. Cloud inference does not replace your
  robot's safety controller.
</Warning>

Call `next_action` once per control tick. It returns one action on the model's
clock, so the loop needs no timing code. This loop drives an SO-101; pick a
model for your robot from `uv run dreamscale models`.

```python theme={null}
import dreamscale

policy = dreamscale.connect("flux-3-action-so101")
while True:
    action = policy.next_action(read_observation(), instruction="pick up the red block")
    robot.send(action)
```

Pass a new instruction at any time to switch tasks.

## What the SDK handles

The SDK checks each observation before sending it and names the field that is
wrong. It prepares images, streams to the GPU over the fastest path your network
allows, and blends chunks so motion stays smooth. If the connection drops, it
reconnects and holds the robot still until actions arrive. It releases the GPU
after a minute without calls and reconnects on the next one. Sessions close
when your program exits, or call `policy.close()`. In async code, use
`await dreamscale.aconnect(...)`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.