Skip to main content

​
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:

​
Global options

​
See also

  • reactor - The CLI for the Reactor platform