> ## 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
> Reactor hosts multiple models, each with its own connect slug (modelName) and command/event schema. The catalog of every model — slug, typed SDK package, and links to its schema — is at /model-api-reference/overview. 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.

# reactor run

> Run the workspace's model container locally

```sh theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
reactor run [-- <flags forwarded to runtime>] [flags]
```

## Description

Run the model defined by the current workspace's reactor.yaml.

**reactor run shells out to the local docker daemon:**

1. Resolves the workspace image tag 'reactor-local/\<name>:dev', where
   \<name> is derived from the workspace directory name and sanitized
   for Docker. The runtime version is pinned in the workspace's
   requirements.txt by 'reactor init', not in this tag.
2. If the tag is missing locally, auto-builds it from the default
   Dockerfile ('./Dockerfile') with no extra build options. For any
   non-default build (a different Dockerfile, `--no-cache`, BuildKit
   secrets) run 'reactor build' first - both commands share the
   same tag, so a successful 'reactor build' followed by 'reactor
   run' boots that image.
3. Runs 'docker run `--rm` `-i` \[`-t`] `--name` \<unique> `--gpus` \<v>
   `-p` \<port>:\<port> `-v` \<weights>:\<weights>
   `-e` REACTOR\_WEIGHTS\_PATH=\<weights> `-e` PORT=\<port>
   \[`-e` KEY=VALUE ...] \<tag> run \[\<flags>...] `--port` \<port>',
   forwarding everything after 'run' (excluding `--port`, `--gpus`, `--tty`,
   `-e`/`--env`, `--env-file`, `--platform`) verbatim to the runtime entrypoint
   inside the container. `-t` is opt-in via `--tty` (off by default so log
   streaming works under Cursor/VS Code remote, tmux, CI, and pipes).

`--port` shifts both sides of the mapping to the same value (host:N ->
container:N) and tells the runtime to bind the same port, both as
'PORT=N' in the environment and as '`--port` N' on the container CMD.
`--gpus` exposes NVIDIA devices to the container. No GPUs are attached
unless you set it: pass `--gpus` all to expose every GPU (requires
nvidia-container-toolkit), or `--gpus` device=N to pin one.

The weights-cache directory is bind-mounted at the same absolute path
on both sides and exported as REACTOR\_WEIGHTS\_PATH.

`-e` / `--env` forwards env vars into the container. KEY (no value) emits
docker's bare '`-e` KEY' argv form so docker resolves the value from its
inherited environment at exec time - secret-safe (the value never
lands in 'ps', '/proc/\<pid>/cmdline', or 'docker inspect'). KEY=VALUE
materialises the literal into argv (use for non-secret values).
`--env-file` loads a dotenv-style KEY=VALUE file (always materialised:
the file isn't part of docker's environment).

If the workspace's reactor.yaml has a 'model.extra-args' list, those
tokens are appended to the args list before parsing - model authors
can pin always-on runtime flags (e.g. '`--batch-size` 4') without
partners having to remember them. They participate in the same
reactor-vs-passthrough split + last-write-wins resolution as partner
CLI tokens, so explicit flags from the model spec win on duplicates.
Tokens past '--' remain partner verbatim.

The auto-build generates its Dockerfile in memory from reactor.yaml's
'build:' block. A ./Dockerfile on disk takes it over and is built
verbatim; `--no-dockerfile` builds from reactor.yaml even when one exists.

`--platform` sets the auto-build's target platform (default linux/amd64,
the standard platform for Reactor model images). It overrides
build.platform in reactor.yaml; an explicit 'FROM `--platform`=' in
the Dockerfile still wins for that stage. Both 'reactor build' and
'reactor run' share the same tag, so pass it to whichever triggers the
build.

**Examples:**

```sh theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
reactor run                                  # auto-build (if missing) and start
reactor run --no-dockerfile                  # ignore the on-disk ./Dockerfile
reactor run --port 9000                      # host 9000 -> container 9000; runtime binds 9000
reactor run --gpus all                       # expose all GPUs (NVIDIA hosts with container-toolkit)
reactor run --gpus device=7                  # pin to host GPU 7 (re-indexed to 0 inside)
reactor run --device /dev/neuron0            # expose an AWS Neuron device (Trainium / Inferentia)
reactor run -e HF_TOKEN -e WANDB_API_KEY     # forward host env vars
reactor run --env-file .env                  # forward dotenv-style file
reactor run --platform linux/arm64           # build natively on Apple Silicon
```

## Global options

| Flag              | Description                                                                           |
| ----------------- | ------------------------------------------------------------------------------------- |
| `--server string` | Reactor API server URL (default "[https://api.reactor.inc](https://api.reactor.inc)") |
| `-v, --verbose`   | Enable verbose output                                                                 |

## See also

* [reactor](/deploy/cli-reference/reactor) - The CLI for the Reactor platform