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 reactor.yaml’s build.runtime_version 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> --shm-size <size> -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, --shm-size, --tty, --weights, -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. --shm-size sets the container’s /dev/shm (default 2g; docker’s own default is 64m). The runtime moves step inputs and results between processes through shared memory, so a model with large frame chunks needs more than docker gives. Accepts docker’s <n>[b|k|m|g] syntax. This shapes only the local container; a deployed model’s /dev/shm is sized by the platform. The weights source resolves from three layers, highest precedence first: --weights, then $REACTOR_WEIGHTS_PATH in your shell, then runtime.weights_path in reactor.yaml. Each layer accepts a filesystem folder OR an hf://org/repo[@rev] reference. A filesystem folder is bind-mounted at the same absolute path on both sides by default and exported as REACTOR_WEIGHTS_PATH. When no layer supplies a value nothing is mounted and REACTOR_WEIGHTS_PATH is left unset - there is no Reactor-owned default directory, so the runtime falls back to its own default. Set REACTOR_HOST_WEIGHTS_PATH to the real host path when reactor run itself executes inside a container with only the host’s docker socket mounted in (Docker-outside-of-Docker); it overrides the host side of the mount only. For an hf:// source (at any layer), reactor run pins the revision to a commit sha and reuses your local Hugging Face cache (HFHUBCACHE,elseHF_HUB_CACHE, else HF_HOME/hub, else ~/.cache/huggingface/hub) when the pinned snapshot is present; otherwise it downloads the pinned files into that same Hugging Face cache (no-symlink snapshots layout). Either way the resolved directory is bind-mounted and REACTOR_WEIGHTS_PATH points at the weights inside it - the container never sees the hf:// reference itself, and hf:// weights are pulled from Hugging Face at startup, never uploaded to Reactor storage. Before a download (not a cache reuse) reactor run prints the file count and total size and asks to confirm; --yes skips that prompt and a non-interactive stdin declines. -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). For local-only testing, match the host (e.g. --platform linux/arm64 on arm64 hosts) for a native build without QEMU emulation. Publish/deploy requires linux/amd64: build from source for that platform at least once, even if local tests use another platform. 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