Skip to main content

​
Prerequisites

Before you begin, make sure you have:
  • Python 3.8 or higher
  • Access to the Reactor repository
  • AWS credentials configured (for model weight downloads)

​
Step 1: Install the Runtime

Install the Reactor runtime: 
pip install reactor-runtime
After installation, you’ll have access to the reactor CLI command.

​
Step 2: Install LiveKit Server

If this is your first time running the runtime, you’ll need to install the local LiveKit server. 
brew update && brew install livekit
For more details, see the LiveKit self-hosting documentation.
Why LiveKit? Reactor uses LiveKit to power real-time video streaming between your model and frontends. LiveKit handles all WebRTC complexity: room management, peer connections, adaptive streaming, and more. Running it locally gives you production-quality streaming with zero latency and zero cost during development.

​
Step 3: Configure AWS Credentials

Model weights are stored in Reactor’s Model Registry (S3). Configure your AWS credentials to enable automatic downloads: 
aws configure
Enter your AWS API key and secret when prompted. These credentials allow the runtime to fetch model weights automatically.
Developing a new model or using local weights? You can skip this step! Continue using your existing model loading process (downloading from Hugging Face, local files, etc.). Reactor’s Model Registry is optimized for production deployments. When you’re ready to deploy, the Reactor team will handle uploading your weights to our registry—your code barely changes.

​
Step 4: Navigate to a Model

Go to any model directory (where manifest.json is located): 
cd path/to/your-model
Install Model Dependencies First: Before running the model, make sure all required dependencies are installed. This guide is generic to any model, so specific setup steps vary. Typically, you’ll need to set up the model environment the same way you would to run it without Reactor Runtime (e.g., installing requirements.txt, CUDA, Flash Attention, etc.).

​
Step 5: Run the Model

Start the runtime: 
reactor run
What happens during startup:

​
Phase 1: Model Loading

The runtime reads your manifest.json and instantiates your VideoModel class: 
class YourModelImplementation(VideoModel):
  def __init__(self, fps=30, size=(480, 640), **kwargs):
      self.model = load_model()  # Heavy operations happen here
      self.model.load_weights()  # Weights loaded into GPU
      # It's really important that weights are loaded in here, as it allows to only do all the heavy
      # operations once.
This phase can take several minutes for large models. This only happens once when the runtime starts, not when users connect.

​
Phase 2: Component Startup

Three components start simultaneously:
  1. Runtime Server (Port 8081) - FastAPI server hosting your model
  2. Local LiveKit Server (Port 7880) - WebRTC streaming server
  3. Development services - Session management and coordination

​
Phase 3: Ready State

Once you see “Ready to accept connections”, your model is:
  • Loaded in GPU memory
  • Listening for session requests
  • Connected to LiveKit
  • Ready to stream to clients instantly

​
Step 6: Connect from a Client

Node.js Required: The following steps use npx which requires Node.js to be installed. If you don’t have Node.js installed, download it from nodejs.org.
Now you’ll connect a frontend to your running model. This is a great opportunity to think about what your demo will look like! If you’re demoing an existing model: The pre-built frontends from npx create-reactor-app are perfect starting points—they’re already set up with working examples. If you’re building a custom model with your own directives: You can code your own demo frontend at the same time! Reactor handles all the networking, streaming, and real-time communication for you. You just focus on building your UI and user experience. Learn more in the Usage Guide and API Reference. The fastest way to test is with a pre-built example: 
npx create-reactor-app
Choose an example similar to your model. Important: The example projects are configured for production by default. To connect to your local runtime, you must add the local flag. After the project is created, navigate to /app/page.tsx and update the ReactorProvider component: 
// Before (default example - connects to production)
<ReactorProvider modelName="example-model">
  {/* Your app components */}
</ReactorProvider>

// After (add local flag for local development)
<ReactorProvider modelName="your-model-name" local>
  {/* Your app components */}
</ReactorProvider>
Make sure to:
  1. Add the local prop - This tells the SDK to connect to your local runtime instead of production
  2. Replace your-model-name with the name of the model you’re running locally. This should match the model_name in your manifest.json.

​
Option 2: Using Your Own Frontend

If you’re building a custom React application from scratch, set the local flag on ReactorProvider: 
<ReactorProvider local>{/* Your app components */}</ReactorProvider>
This tells the SDK to connect to your local runtime instead of production.
Building your own demo? This option is perfect for creating custom frontends tailored to your model’s unique capabilities. Check out the Usage Guide and API Reference to learn how to build interactive Reactor applications with React hooks and components.

​
Step 7: Start Testing

pnpm Required: If you don’t have pnpm installed, install it first with npm install -g pnpm (requires Node.js from Step 6). See the pnpm installation guide for more options.
Run your frontend: 
pnpm run dev
Open the URL in your browser and click “connect”.

​
What Happens When You Connect:

1. Frontend connects to your local runtime
2. Runtime calls your start_session() method
3. Runtime and Frontend join a LiveKit "room"
4. Video frames flow: Runtime → LiveKit → Frontend
Your model’s start_session() method runs, and frames stream in real-time to your browser.

​
Understanding Components in Action

ComponentRole During SessionPort
FrontendDisplays video, sends commands to model3000
Runtime ServerRuns your model, generates frames8081
LiveKit ServerStreams video frames between runtime and frontend7880

​
Development Workflow

The streamlined local development loop: 
# Terminal 1: Start runtime (leave running)
reactor run

# Terminal 2: Start frontend
pnpm run dev
Then in your browser:
  1. Connect - Click “connect” button
    • Runtime starts a new session
    • Your start_session() method executes
    • Video streams to your browser
  2. Test - Interact with your model in real-time
    • Send commands via the SDK
    • See results instantly
  3. Disconnect - Click “disconnect” or close tab
    • Your end_session() method executes (if implemented)
    • Session cleans up
    • Model stays loaded and ready
  4. Reconnect - Click “connect” again
    • New session starts instantly (model already loaded)
    • No restart needed

​
Hot Reload Tips

  • Model Code Changes: Restart reactor run
  • Frontend Changes: Hot reloads automatically
  • Manifest Changes: Restart reactor run
  • Between Sessions: No restart needed

​
Troubleshooting Quick Tips

​
”Connection failed”

Check that all three components started: 
# Should see runtime components running
lsof -i :8081  # Runtime
lsof -i :7880  # LiveKit

​
What’s Next?

Coding Models

Learn how to implement your own VideoModel from scratch

CLI Reference

Explore all available Reactor CLI commands and options

VideoModel Lifecycle

Understand when each method is called

Deploy Your Model

Take your model from local dev to production