> ## 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.

# Deploy a model

> Deploy the current workspace, activate an existing release, or roll back.

`reactor model deploy` is the normal way to ship a workspace. It registers the model when needed,
publishes the release, applies the current model settings, and routes client sessions to it.

## Deploy from a workspace

Run it from your workspace and it reads the model name and release tag from `reactor.yaml`:

```sh theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
reactor model deploy
```

The command builds and pushes the image when the release is not published yet. When the release
needs a new weights bundle, publish it with the bundle before deploying:

```sh theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
reactor model publish --weights ./weights
reactor model deploy
```

When the release already has an image, deploy skips the build and push. You can still use
[`reactor model publish`](/deploy/platform/publish) separately for CI or staging.

When a workspace deploy builds the release, you can pass `--build-env` and `--build-secret` to that
build. See [`reactor model deploy`](/deploy/cli-reference/reactor_model_deploy).

When you have a prebuilt image, pass `--source` and the deploy publishes it instead of building one.
The flag works on a workspace deploy only. See
[`reactor model deploy`](/deploy/cli-reference/reactor_model_deploy).

```sh theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
reactor model deploy --source docker.io/acme/my-model:v1.0.0
```

## Roll back

To roll back, name an earlier published release explicitly. This form does not rebuild the release
or apply settings from `reactor.yaml`. A local `deployment.yaml` still controls the regional
instance plan.

```sh theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
reactor model deploy my-awesome-model:v0.9.0
```

The previously active release stops receiving new sessions; in-flight sessions continue against the
version they connected on.

## Choose a rollout strategy

By default a deploy replaces instances one at a time, so the model keeps serving during the rollout.
Pass `--strategy replace-all` to cut the whole fleet over at once. An idle fleet turns over in
seconds. A busy one serves at reduced capacity until the new instances finish loading.

```sh theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
reactor model deploy --strategy replace-all
```

Sessions already in flight keep their full grace period under either strategy.

## Cut over immediately

`--immediate` disconnects the model's live sessions after the rollout starts, so the new release
serves in seconds instead of minutes. It implies `--strategy replace-all`, and the CLI asks you to
confirm unless you pass `--yes`.

> [!WARNING]
>
> `--immediate` ends every session that is live when it runs. Use it to take a bad release out of
> service now. Do not use it for a routine deploy.

```sh theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
reactor model deploy --immediate
```

## Set the deployment plan

The deployment plan lists which regions to run in and how many instances to run in each. New
workspaces use the `deployment:` block in `reactor.yaml`. `reactor init` requests one instance in
`us-west`. The [`reactor.yaml` reference](/deploy/platform/reactor-yaml#deployment) documents every
key in that block. Your account needs capacity there before this plan can succeed:

```yaml reactor.yaml theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
deployment:
  instances:
    - region: us-west
      count: 1
```

If the workspace also has a `deployment.yaml`, that file takes precedence over the `deployment:`
block. The CLI warns when both declare a plan. Read the command's `Using deployment plan from ...`
output to check which one applies. Changing the ignored block does not change the deployment.

Edit the `instances:` list to scale out or add regions. Each entry is a `region` and a `count` of
instances to run there. The GPU is a model attribute you set once in `model.resources.gpu`, not per
entry.

To list the names you can use in the `region` field, run `reactor regions`. Add `--json` to get the
list as a JSON array for a script.

```sh theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
reactor regions
```

> [!WARNING]
>
> A deploy with no plan provisions nothing. Your `reactor.yaml` declares no instances when the
> `instances:` list is empty, or the `deployment:` block is missing. In that case `reactor model
>     deploy` warns and leaves your per-region capacity unchanged. Set at least one region and count to
> place the model.

A plan that exceeds your allocated capacity is rejected with a conflict error. Reduce the per-region
counts or contact Reactor to raise your allocation. An unknown region or invalid count fails
validation; check the names with `reactor regions`.

To check your config before you deploy, run `reactor validate`. It checks the schema and structure
of each file. It does not contact the server, so it does not catch an unknown region or a capacity
problem.

```sh theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
reactor validate
```

## Weights at deploy time

If the release being deployed has no weights of its own, the deploy reuses the most recently
deployed release's bundle server-side and prints a notice naming the source. When neither the
release nor any previously deployed release has weights, the deploy still succeeds and warns you to
upload them with [`reactor weights upload`](/deploy/platform/publish#weights).

When a workspace deploy publishes the release, it runs the same weights step as publish.
Pass `--weights <path>`, or an `hf://org/repo[@rev]` reference, to publish a different source for
this release. `--no-weights` skips the step even when `reactor.yaml` declares
`runtime.weights_path`. See [`reactor model deploy`](/deploy/cli-reference/reactor_model_deploy).

## Next

> **[Check status](/deploy/platform/status.md)**
>
> Confirm the release is live and inspect deployment state.

> **[Quick iteration](/deploy/platform/iteration.md)**
>
> The develop, test, ship loop for every release after the first.


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