Quickstart

Everything runs through the reactor CLI. Install it, scaffold a project, and run it. The CLI builds a container with the runtime already inside, so there is nothing to install on your host but the CLI itself and Docker.

Install the CLI

curl -fsSL https://reactor.inc/install | bash

reactor version

Pinning a release in CI? See Install the CLI.

Scaffold a project

reactor init my-model

This creates a ready-to-run project:

my-model/
├── model.py            # Your model. The only file you need to edit to start
├── reactor.yaml        # Model name, version, runtime entrypoint, and the image
├── config.yaml         # Model config, handed to your model at load time
├── requirements.txt    # Python dependencies
├── deployment.yaml     # Which GPUs and regions to run on, once you deploy
├── .dockerignore       # Paths kept out of the image build
└── README.md

reactor.yaml describes the image. The scaffolded build: block is one line that pins the runtime release:

reactor.yaml

build:
  runtime_version: "3.2.5"

Build the image covers the full build: block. Bump runtime_version to upgrade the runtime; releases are immutable, so there is no latest to track. The scaffolded model.py is a small working ReactorModel that generates frames on its own and takes one command, so you can stream something before you write any code. Run it first, then replace it with your own model.

Run it

cd my-model
reactor run

The first run builds the image, which takes a minute. Then the runtime starts and waits:

INFO __main__: starting reactor runtime version=3.2.5 model=model:MyModel host=0.0.0.0 port=8080
INFO reactor_runtime.runner.runner: model loaded; session ready model=MyModel tracks=1 commands=1
INFO reactor_runtime.service: runtime started components="['http', 'runner']"

Nothing is generated yet. The model produces frames only while a client is connected, so the next step is to attach one.

Connect a client

The fastest option is the Reactor Sandbox: open it, pick Local (Direct), and click Connect. Frames start streaming immediately. To build your own frontend, point the JS SDK at your local model with local: true:

import { ReactorProvider, ReactorView } from "@reactor-team/js-sdk";

<ReactorProvider modelName="my-model" local={true} autoConnect={true}>
  <ReactorView className="w-full aspect-video" />
</ReactorProvider>

import { Reactor } from "@reactor-team/js-sdk";

const reactor = new Reactor({ modelName: "my-model", local: true });
await reactor.connect();
const stream = reactor.getMediaStream("main_video");
document.querySelector("video").srcObject = stream;

The iteration loop

reactor build and reactor run share one image tag, and run reuses whatever image is already there. So the loop is always the same two commands:

Edit your model

Change model.py, config.yaml, or anything else in the project.

Rebuild

reactor build

This bakes your current code and dependencies into the image.

Run

reactor run

Boots the image you just built and starts serving on port 8080.

Editing a file does not change the running container, and reactor run on its own will not pick the change up: it reuses the existing image. Chain them while you iterate:

reactor build && reactor run

What `reactor run` actually does

Builds the image defined by the build: block in reactor.yaml if it does not exist yet, and reuses it otherwise.
Starts the container, maps port 8080 to your host, and sets PORT to match.
Inside the container, the runtime reads reactor.yaml and resolves runtime.import (model:MyModel means the class MyModel in model.py).
It calls your model’s load() once, passing the path to runtime.config.
It serves WebRTC signaling on that port and waits.

The runtime reads its settings from environment variables. HOST and PORT name the address it binds, so reactor run --port maps the host port and sets PORT in the container to match. When a client connects, the runtime wakes your run() loop and streams whatever it emits.

Command reference

reactor run starts the model.

Flag	Description
`--port <number>`	Host port mapped onto the container. Default 8080.
`--gpus <value>`	Forwarded to `docker run --gpus`. No GPUs are attached unless you set it.
`--device <path>`	Forwarded to `docker run --device`. Repeatable.
`-e <KEY>` / `--env <KEY=VALUE>`	Forward a host environment variable into the container. Repeatable.
`--env-file <path>`	Dotenv-style file forwarded into the container.
`--tty`	Allocate a TTY.
`--platform <value>`	Target platform of the auto-build. Default `linux/amd64`.

reactor build builds the image without running it.

Flag	Description
`-f <path>` / `--dockerfile <path>`	Use a non-default Dockerfile, for example `Dockerfile.gpu`.
`--no-cache`	Skip the layer cache and rebuild every step.
`--build-secret id=<name>,env=<var>`	Forward a BuildKit secret, for private package pulls.
`--platform <value>`	Target platform. Default `linux/amd64`.

Builds target linux/amd64, the platform Reactor serves models on, so on an Apple Silicon Mac the default build runs under emulation. Pass --platform linux/arm64 for a faster local loop, and drop it before publishing.

Model Anatomy

Replace the scaffold with your own model, line by line.

The Run Loop

Emitting frames, batches, and frame rates.

Load Your Weights

Resolve checkpoints the same way locally and in production.

Get Started

CLI & Platform

Build a Model

Media & Transport

Releases

Install the CLI

Scaffold a project

Run it

Connect a client

The iteration loop

What `reactor run` actually does

Command reference

Next

Model Anatomy

The Run Loop

Load Your Weights

Deploy to Reactor

​Install the CLI

​Scaffold a project

​Run it

​Connect a client

​The iteration loop

​What reactor run actually does

​Command reference

​Next

Model Anatomy

The Run Loop

Load Your Weights

Deploy to Reactor

Install the CLI

Scaffold a project

Run it

Connect a client

The iteration loop

What `reactor run` actually does

Command reference

Next