> ## 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 Python SDK and CLI as the supported public integration surfaces.
> Prefer context-managed sessions and model-specific observation helpers.
> Do not infer or recommend internal control-plane APIs.

# Deploy your fine-tune

> Serve your own Isaac 0.5 fine-tune from Hugging Face for your robot, connect to it from Python or the CLI, and keep its GPU warm between robots.

A deployment serves your own Isaac 0.5 fine-tune from Hugging Face, shaped to
your robot, in one region. It is serverless: when a robot connects, the session
starts its own GPU, and you pay for the session. This guide creates a
deployment, connects to it, and optionally keeps its GPU warm so robots attach
without a cold start.

## Prerequisites

You need:

* SDK and CLI 0.1.0a100 or later (`dreamscale --version`; see
  [Upgrade](/installation#upgrade));
* a Dreamscale sign-in (`dreamscale login`) or an
  [API key](/installation#use-an-api-key-without-signing-in);
* Isaac 0.5 enabled for your organization. Isaac 0.5 is granted per
  organization; check [Models](https://app.dreamscalelabs.com/dashboard/models)
  or email [team@dreamscalelabs.com](mailto:team@dreamscalelabs.com);
* a Hugging Face repo with your fine-tune of Isaac 0.5, published as a full
  Hugging Face export, with the normalization statistics from its training
  data;
* a Hugging Face read token if the repo is private.

## What a deployment contains

| Part | What you choose |
| - | - |
| Weights | Your Hugging Face repo, and optionally a branch or commit |
| Robot | What your robot sends and expects: cameras, image size, actions per chunk, control rate, action and state widths, context frames, and robot unit conversion |
| Region | US West (Oregon) or US East (Virginia). Sessions run only in this region |

Dreamscale builds a deployment once. It checks the architecture, downloads and
converts the weights, and tests them on a GPU before the deployment serves.
A build usually takes about 15 minutes. Your organization builds one
deployment at a time.

## Create a deployment in the dashboard

1. Open [Deployments](https://app.dreamscalelabs.com/dashboard/deployments)
   and choose **Create deployment**.
2. Under **Weights**, enter your Hugging Face repo as `owner/name`. Add a
   branch or commit if you do not want `main`. For a private repo, add a
   **Read token**; it is used once to download the weights and never stored.
3. Choose **Detect**. Dreamscale reads the repo's deployment adapter and
   training statistics, which can take up to a minute. If the repo declares its
   robot, **Detected from repo** fills every robot field.
4. Under **Robot**, check the values, or start from another choice:

   * **Bimanual YAM** or **SO-101** presets fill every field for that robot;
   * **Custom** starts from your own values.

   Editing any field of a preset makes the robot custom. Each field shows
   where its value came from. Some organizations can run only the presets; ask
   Dreamscale for custom robots.
5. Check **Robot unit conversion**. See
   [Choose the robot unit conversion](#choose-the-robot-unit-conversion).
6. Under **Region**, choose the region nearest your robot.
7. Choose **Create deployment**.

<Check>
  The deployment page shows the build steps, then **Ready**. Its **Connect**
  card shows the Python code for this deployment and, for a preset robot, the
  CLI command. If the build fails, the page shows the error and its fix.
</Check>

### Choose the robot unit conversion

The model works in its own scaled numbers. Robot unit conversion turns the
model's outputs into your robot's joint angles and gripper positions, and your
robot's state into the model's numbers.

The conversion comes from your checkpoint's normalization statistics, which
were measured on the dataset it was trained on, so each conversion is named
after its dataset. A checkpoint trained on several datasets has one conversion
for each.

Choose the conversion measured on data recorded **on this robot**. With the
wrong one, the robot moves to the wrong positions.

* If the repo's adapter names one, Dreamscale reads it from your repo.
* If only one fits the robot's action and state widths, Dreamscale selects it.
* If several fit, choose the one recorded on this robot.
* If none fit, check the action and state widths. Without normalization
  statistics in the repo, the model's outputs can't be turned into your
  robot's units.

## Create a deployment with the CLI

Inspect the repo first. It prints the robot the repo declares and the
conversions its statistics cover:

```bash theme={null}
dreamscale deployments inspect hf://your-org/isaac-finetune
```

Then create the deployment. Without `--preset`, the CLI uses the robot the
repo declares:

```bash theme={null}
dreamscale deployments create hf://your-org/isaac-finetune --region us-west
```

Or name a preset:

```bash theme={null}
dreamscale deployments create hf://your-org/isaac-finetune --preset so101
```

Or describe a custom robot. A custom robot needs at least its cameras, image
size, and robot unit conversion:

```bash theme={null}
dreamscale deployments create hf://your-org/isaac-finetune \
  --camera side_cam=primary \
  --camera wrist_cam=wrist \
  --image-size 256x256 \
  --dataset your_dataset_name
```

For a private repo, set `HF_TOKEN` in the environment instead of passing
`--hf-token`, which shell history can expose. The token is not stored.

The command waits for the build and shows each step:

```text theme={null}
Building ckpt_... (deployment) from hf://your-org/isaac-finetune for SO-101 · ... in us-west (one-time build: download, convert, GPU check).
Building · step 3 of 6 · Downloading · ...: 240s elapsed (usually about 15 min)
```

<Check>
  The command ends with the deployment's details and `status:   ready`. Check
  it again at any time with `dreamscale deployments show ckpt_...`.
</Check>

See the [CLI reference](/reference/cli#deployments) for every option.

## Connect to your deployment

Pass the deployment ID to `dreamscale.connect()` with the Isaac 0.5 base
model:

```python theme={null}
import dreamscale


with dreamscale.connect("perceptron-isaac05", deployment="ckpt_...") as policy:
    print(policy.session_id, policy.region)
```

The session runs in the deployment's region. Send observations shaped like the
deployment's **Robot shape** on its dashboard page, then use `predict()`,
`next_action()`, or `run()` as described in [Python SDK](/sdk/overview).

<Warning>
  A returned action is a model output, not a safe robot command. Before any
  motion, implement robot-side position, velocity, and acceleration limits,
  workspace and collision checks, a watchdog, hold behavior, and a physical
  e-stop. Cloud inference does not replace your local safety controller.
</Warning>

For a preset robot, the CLI runs an attended task loop on the robot. Complete
the robot's setup and safety checks first, for example the
[SO-101 guide](/guides/so101):

<CodeGroup>
  ```bash SO-101 theme={null}
  dreamscale run so101 --model perceptron-isaac05-so101 --deployment ckpt_...
  ```

  ```bash Bimanual YAM theme={null}
  dreamscale run yam --model perceptron-isaac05-yam --deployment ckpt_...
  ```
</CodeGroup>

<Check>
  The connection prints startup progress. A cold start usually takes about 2
  to 3 minutes while the GPU starts and loads your weights. With
  [keep-warm](#keep-a-deployment-warm) on, a robot attaches to the warm GPU in
  a few seconds.
</Check>

## Keep a deployment warm

By default, a deployment's GPU stops when the session ends, and the next robot
waits through a cold start of about 2 to 3 minutes. Keep-warm keeps the GPU up
after the last robot disconnects, so the next robot attaches to it in a few
seconds.

| Setting | What happens |
| - | - |
| Off (default) | The GPU stops when the session ends |
| 10 minutes, 30 minutes, 1, 2, 6, or 12 hours | After the last robot disconnects, the GPU stays up this long, then stops |
| Always | One GPU starts when you turn it on and stays ready around the clock |

Set it on the deployment page's **Keep warm** card and choose **Save**, or with
the CLI:

```bash theme={null}
dreamscale deployments keep-warm ckpt_... 30m
dreamscale deployments keep-warm ckpt_... always
dreamscale deployments keep-warm ckpt_... off
```

<Check>
  The card's badge and the CLI's `warm:` line show what the GPU is doing now:
  Warming up, Warm, In use, Replacing, Waiting for a GPU, Failed, or Off.
</Check>

<Warning>
  Warm time is billed like GPU time, whether or not a robot is attached. The
  **Keep warm** card shows the hourly rate and, for Always, the cost per day and
  how long your credits last. Turn keep-warm off when you no longer need it.
</Warning>

How a warm GPU behaves:

* **One robot per warm GPU.** The first robot attaches to the warm GPU. A
  second robot that connects at the same time starts its own GPU with a cold
  start.
* **Any member's robot can attach.** The warm GPU belongs to the deployment,
  not to the person who turned keep-warm on.
* **Stopping a session keeps the GPU warm.** Stopping a robot's session, from
  your code or the dashboard, does not release the GPU. It stops when its
  keep-warm window ends, when you turn keep-warm off, or when you delete the
  deployment. A setting changed while a robot is attached applies when that
  session ends.
* **Credits come first.** Without credits, Dreamscale does not start a warm
  GPU, and the status shows Failed (Out of credits).
* **Keep-warm replaces `connect(keep_warm=...)`.** When a deployment's
  keep-warm is on, it applies to every session on that deployment.

### Move Always-on to a new deployment

A new fine-tune is a new deployment with a new ID. To move Always-on to it
without a gap, open the new deployment's **Keep warm** card and choose
**Move Always-on here**. The new deployment starts a warm GPU, and the old one
turns off once the new one is warm. With the CLI:

```bash theme={null}
dreamscale deployments keep-warm ckpt_new always --take-over-from ckpt_old
```

Update the deployment ID in your code or commands to the new one.

### The 24-hour server limit

Each GPU server runs for at most 24 hours. If a robot is attached when its
server nears the limit, Dreamscale ends the session cleanly at about 23.5 hours
with `This session ended because its GPU server reached its 24-hour limit.`
Write long-running robot code to connect again after a session ends.

With Always, Dreamscale replaces an idle server before the limit. If a robot is
attached, it starts the replacement about 10 minutes before ending the
session, so the robot attaches to the replacement when it reconnects. With a
timed setting, an idle server near the limit is released instead, and the
next robot gets a cold start.

## Who can do what

Everything in a deployment belongs to your organization.

| Action | Who |
| - | - |
| Create a deployment and connect to it | Any member |
| Set keep-warm, including Always and Move Always-on here | Any member |
| Delete a deployment | Organization owners |
| Restore a deleted deployment, within 7 days | Organization owners |

Deleting a deployment stops new sessions, ends its running sessions now, and
releases its warm GPU. Usage history stays. In the dashboard, delete from the
deployment page's **Danger zone**; restore from **Recently deleted** on the
Deployments page. With the CLI:

```bash theme={null}
dreamscale deployments rm ckpt_...
dreamscale deployments restore ckpt_...
```

A restored deployment comes back with keep-warm off. Sessions that the delete
ended are not restored.

## Next steps

* Build observations and choose a prediction interface in
  [Python SDK](/sdk/overview).
* Look up every deployment command in the
  [CLI reference](/reference/cli#deployments).
* If a build, sign-in, or session fails, open
  [Troubleshooting](/troubleshooting) or email
  [team@dreamscalelabs.com](mailto:team@dreamscalelabs.com) with the deployment ID.


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