Build the image

reactor build builds your workspace’s container image on the local Docker daemon:

reactor build

The image is tagged reactor-local/<name>:dev, where <name> is the name of the directory you run the command from (normally the workspace root), sanitized for Docker. reactor run derives the tag the same way, so reactor build && reactor run always boots the image you just built.

The build block

The build: block of reactor.yaml is the whole build. In the examples below, replace <runtime-version> with the value that reactor init generated in your workspace. The reactor.yaml reference documents every key in this block, next to the rest of the file. A minimal block is one line:

reactor.yaml

build:
  runtime_version: "<runtime-version>"

runtime_version pins the reactor-runtime release the image installs. To upgrade, choose a release from the runtime changelog and update this field. Releases are immutable, so there is no latest to track. The build resolves the runtime and the dependency file in a single pass, so a version conflict fails the build instead of surfacing when the model loads. Add fields as the model needs them:

reactor.yaml

build:
  runtime_version: "<runtime-version>"
  python_requirements: requirements.txt
  cuda_version: "12.9.1"
  system_packages: [ffmpeg, git]
  runtime_env:
    HF_HUB_OFFLINE: "1"

Every field the block accepts, with its type and its default, is tabulated in the reactor.yaml reference. The ones this page goes on to use are python_requirements for the dependency file, cuda_version to build against CUDA, system_packages for Debian packages, build_env and runtime_env for environment variables, and run for build steps and their build secrets. python_requirements carries the model’s own dependencies; the runtime version lives only in runtime_version, so the two cannot drift.

Build steps

The run list adds build commands to the image, in order. Each runs after the dependencies install and before your model code is copied in:

reactor.yaml

build:
  runtime_version: "<runtime-version>"
  run:
    - python -m spacy download en_core_web_sm

Each entry is one command on a single line. To run several commands as one step, join them with &&. Your model files are not in the image yet at this point, so a step cannot read them.

Build context

reactor build sends the workspace directory to Docker as the build context. Control what goes in with a .dockerignore file, the Docker standard. Anything it matches stays out of the context and the image. reactor init scaffolds one that excludes paths such as .venv/ and checkpoints/, which keeps the build fast and the image lean. With -f, a Dockerfile-specific ignore file next to it (for example Dockerfile.gpu.dockerignore) replaces the context-root .dockerignore for that build.

Do not bake model weights into the image. The image carries your code and dependencies only; Reactor mounts the weights into the container at runtime. See Weights for how they are mounted and resolved, and Publish a release for how they are uploaded.

Where build fits in the deployment flow

For an unpublished release, reactor model deploy runs the same image build before it publishes and activates the release. Run reactor build first as an optional preflight check. It finds build errors on your machine without changing the release on Reactor.

Flags

Flag	Description
`-f` / `--dockerfile <path>`	Build an explicit Dockerfile instead (see Hand-edited Dockerfile)
`--no-dockerfile`	Build from `reactor.yaml`, ignoring a Dockerfile on disk
`--no-cache`	Rebuild every layer instead of reusing the cache
`--build-secret <spec>`	Forward a BuildKit secret to the build (repeatable)
`--build-env <KEY=VALUE>`	Override a `build.build_env` value for this build (repeatable)
`--platform <value>`	Target build platform (default `linux/amd64`)

reactor build                         # from reactor.yaml, layer cache on
reactor build --no-cache              # rebuild from scratch
reactor build -f Dockerfile.gpu       # build an explicit Dockerfile instead
reactor build --no-dockerfile         # ignore a Dockerfile on disk
reactor build --build-env MAX_JOBS=16 # override one build_env value

--build-env changes a value for one build without an edit to reactor.yaml. It rejects a key that build.build_env does not declare. The value stays in the image metadata, so pass credentials with --build-secret instead. The generated CLI reference has the full flag list, including the global flags.

Build secrets

Some builds need a credential mid-build, such as a GitHub token for a private repository, or an index URL for a private PyPI mirror. Pass it as a BuildKit secret rather than writing it into reactor.yaml, where it would end up in version control, or into the image, where it would ship with the release:

reactor build --build-secret id=github_token,env=GITHUB_TOKEN

A run step opts into the secret by mounting it, and reads it from the mounted path:

reactor.yaml

build:
  run:
    - command:
        pip install "git+https://$(cat /run/secrets/github_token)@github.com/acme/private-pkg.git"
      mounts:
        - type: secret
          id: github_token

--build-secret uses docker’s standard --secret grammar (comma-separated key=value fields) and is repeatable for multiple secrets:

Spec	Reads the secret from
`id=github_token,env=GITHUB_TOKEN`	the `GITHUB_TOKEN` environment variable
`id=github_token,src=./token.txt`	a file
`type=env,id=GITHUB_TOKEN`	the environment variable named by `id`

The secret is visible at /run/secrets/<id> only to the step that mounts it, and it never lands in an image layer.

A --build-secret with no matching secret mount is silently unused. The build succeeds and the secret is simply never exposed. If a credential seems to be missing inside the build, check that the mounted id matches the id in the flag.

Publish with a build secret

reactor model publish takes the same --build-secret flag and passes it to its internal build. When a run step mounts the secret, pass the flag:

reactor model publish --build-secret id=github_token,env=GITHUB_TOKEN

The flag is repeatable here too. When you pass --source, publish ignores it because that image is already built. Everything else about publish is unchanged: it still registers the release tag, pushes the image, and uploads weights when you pass --weights. See Publish a release.

Hand-edited Dockerfile

Editing the build: block covers most models. When you need to shape the image itself, such as a custom base layout or a multi-stage build, you can hand-edit a Dockerfile instead. Run reactor init with --dockerfile to write the generated Dockerfile into the workspace as a starting point, and edit it from there:

reactor init my-model --dockerfile

A Dockerfile in the workspace takes the build over: the CLI builds it verbatim and ignores the build: fields, naming the ones it dropped in a note on stderr. Pass --no-dockerfile to build from reactor.yaml anyway.

ARG default values in a hand-edited Dockerfile apply as written, and --build-env overrides them at build time. Use --build-secret for credentials, and build.runtime_env / build.build_env in reactor.yaml for values the generated build consumes.

Good to know

Docker must be running. The build talks to the local Docker daemon (honouring DOCKER_HOST). When the daemon is unreachable the command fails with a docker daemon unreachable error. Install or start Docker Desktop or Docker Engine.
reactor run does not rebuild on changes. It auto-builds only when the reactor-local/<name>:dev tag is missing entirely. After you edit requirements.txt or the build: block in reactor.yaml (or a hand-edited Dockerfile), run reactor build again. Otherwise an old image with the previous contents keeps running.
Build uses the directory you run it in. Unlike publish and deploy, build does not walk up to the nearest reactor.yaml: the build context, the -f path, and the image tag all come from the current directory, so run it from the workspace root. Two directories with the same basename (say, ~/work/my-model and ~/scratch/my-model) share the reactor-local/my-model:dev tag and overwrite each other’s builds.
Images target linux/amd64, the platform Reactor’s production nodes run, so builds on Apple Silicon run under emulation and take noticeably longer. Most specific source wins: the --platform flag, then build.platform in reactor.yaml, then that default. With a hand-edited Dockerfile, an explicit FROM --platform= in it wins for its own stage. Use another platform for local tests only. Publish and deploy need a linux/amd64 image, so build for that platform at least once.

Deploy a model

Publish the workspace and activate its release.

Quick iteration

The edit, build, and deploy loop for later releases.

Get Started

CLI & Platform

Build a Model

Media & Transport

Releases

Build the image

The build block

Build steps

Build context

Where build fits in the deployment flow

Flags

Build secrets

Publish with a build secret

Hand-edited Dockerfile

Good to know

Next

Deploy a model

Quick iteration

​The build block

​Build steps

​Build context

​Where build fits in the deployment flow

​Flags

​Build secrets

​Publish with a build secret

​Hand-edited Dockerfile

​Good to know

​Next

Deploy a model

Quick iteration

The build block

Build steps

Build context

Where build fits in the deployment flow

Flags

Build secrets

Publish with a build secret

Hand-edited Dockerfile

Good to know

Next