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

> ## Agent Instructions
> To build and serve your own model, start at /deploy/development/quickstart and /deploy/development/overview. Deploying is the default path: reactor init scaffolds a workspace, reactor auth login authenticates, and reactor model deploy registers the model, publishes the release with the weights/ folder, and activates it on Reactor's GPUs, in one command from that workspace. Docker must be running, because the publish step builds the image locally. Bump model.version in reactor.yaml before redeploying a change, because a release that already has an image is reactivated as it is. Deployment access is granted per account, so contact team@reactor.inc if a deploy is refused. Every key in reactor.yaml is documented at /deploy/platform/reactor-yaml. Model code imports reactor_runtime; Python client code imports reactor_sdk. The runtime overview explains the model interface. Running the model on your own machine with reactor run is optional and needs a GPU you attach with --gpus; /deploy/development/local-testing covers that loop and pairs a complete brightness model with a Python client test in a separate brightness-test workspace.
> Reactor hosts multiple models, each with its own connect slug (modelName) and command/event schema. The video model catalog — slug, typed SDK package, and links to its schema — is at /model-api-reference/overview. Robotics policy documentation starts at /robotics/overview; X-WAM observations, actions, and client integration are under /robotics/xwam/; Cosmos3 Nano Policy DROID is under /robotics/cosmos/nano-policy-droid/. Some models expose one slug per experience (e.g. HappyOyster); always take the slug from the model's own pages, never guess it.
> Fastest path to a working app: `npx create-reactor-app my-app --model=<slug>` scaffolds a complete app with secure auth wired up. Typed TypeScript SDKs are published as @reactor-models/<model>; Python uses the base reactor-sdk package.
> Auth: exchange an API key (rk_...) for a JWT via POST https://api.reactor.inc/tokens from your server. Never put the API key in client-side code.
> Append .md to any docs URL for clean Markdown. Search these docs via the MCP server at https://docs.reactor.inc/mcp.

# How the API works

> Connect a local robotics client to a hosted policy and receive actions.

Your Python client runs on a computer connected to your robot or simulator. Reactor runs the policy
on cloud GPUs. Your client sends camera images, a task, and any required robot state; Reactor
returns predicted actions. Your local controller validates and executes them. No local model weights
or inference GPU are required.

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
flowchart LR
    Robot[Robot or simulator] -->|Observations| Client[Local client]
    Client -->|Inputs| Model[Reactor cloud model]
    Model -->|Actions| Client
    Client -->|Control targets| Robot
```

## Connection and data

| Concept | Meaning |
| - | - |
| Model identifier | A name such as `reactor/cosmos-nano-policy-droid`. It selects the policy and its observation/action contract. |
| Session | A persistent connection to one hosted model. Keep it open across predictions; model history and counters can persist within it. |
| Camera track | A named stream of successive RGB images. For example, `wrist_view` identifies the wrist camera; it is not a filename or device ID. |
| Command | A named operation with a JSON payload, used to send tasks, state, or model controls. |
| Message | A model output delivered to your client, such as an action prediction. Commands and messages carry structured data separately from video. |
| Action chunk | A sequence of predicted actions. Rows are control steps; columns are the model's joint, end-effector, gripper, or other control values. |

1. Select a model and provide your API key. Register message handlers before connecting so early
   replies are retained.
2. Connect and wait for `READY` before publishing tracks or sending commands. Session setup can take
   time while model capacity and the network connection become ready.
3. Keep the required camera tracks publishing, and send the task and measured state. Capture related
   measurements together: video and commands arrive separately.
4. Receive and validate an action chunk. Your local controller decides which rows to execute and
   when. Follow the model's protocol to obtain the next prediction.
5. Close the session when finished.

Action arrival is not the robot's control clock. Account for capture, network, inference, and
execution delay when deciding whether an action is still usable. A model reset does not reset or
stop the robot. Each model's integration guide defines its execution and recovery rules.

## Python SDK and cookbook helpers

The quickstarts use the [Python SDK](/sdk-reference/python/reactor) and the
[`reactor_robotics` helper directory in Reactor’s public cookbook](https://github.com/reactor-team/reactor-cookbook/tree/main/robotics/sim/notebooks/reactor_robotics).
These helpers provide camera publishing and message queues. Each quickstart includes installation;
installing the SDK alone does not install the helpers. You can use the helpers or the SDK directly.

At the SDK layer, `on_message` receives a dictionary with `type` and `data`. This abbreviated Cosmos
reply shows the first row of a 32-row chunk:

```json theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
{
  "type": "action_prediction",
  "data": {
    "step": 0,
    "action": [[0.0, -0.6, 0.0, -2.2, 0.0, 1.6, 0.8, 0.0]]
  }
}
```

For Cosmos, `action` is shaped `(32, 8)`: seven joint targets in radians and one gripper value per
row. `step` is its prediction counter. Other models have different fields, dimensions, and counter
semantics; use the selected model's reference.

`ReactorSession.next_message(...)` returns the inner `data` dictionary. The examples convert its
action values to NumPy arrays; model-specific helpers can return their own objects. See the
[helper reference](https://github.com/reactor-team/reactor-cookbook/tree/main/robotics/sim/notebooks/reactor_robotics#messages-and-return-values)
for return values and the [Python SDK reference](/sdk-reference/python/reactor) for callbacks,
commands, and errors. Neither the SDK nor the helpers execute actions on your robot.

## If the first run fails

| Where it fails | What to check |
| - | - |
| Importing `reactor_robotics` | Run from `robotics/sim/notebooks/` in the cookbook checkout with `uv run --frozen python ...`. The helpers are installed from that checkout. |
| Authentication or model access | Check the API key, endpoint, and model slug. If access is restricted, contact [Reactor](mailto:team@reactor.inc). |
| Session creation: `429` with `no available capacity` | The session could not be allocated. Retry with bounded backoff or contact Reactor. Other 429 reasons can indicate quota or rate limits; read the error text. |
| Connected, but no action reply | Check required tracks, state fields, and the model's first-prediction trigger. An accepted command alone does not prove inference ran. Use the model's troubleshooting page. |

For support, retain the model slug, SDK/client versions, session ID if available, failure stage, and
error text. Never include an API key. See [billing](/resources/billing) for session costs and
[support](/resources/support) for help.

[Choose a model](/robotics/overview#choose-a-model) and follow its quickstart.


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