Self-hostingSelf-hosted only
Run the Rehearsal server, its workers and its sandboxes on your own machine. What the parts are, and where to start.
Rehearsal is one package. The same code that runs the hosted service runs on your machine: the API and console, the workers, and the sandboxes that worlds run in. You bring a Linux host with Docker, a PostgreSQL database and a model provider key.
Console
Browser
CLI
Terminal
Python SDK
Scripts and CI
MCP server
AI assistants
HTTPS, with a sign-in or an API key
API
One service on port 7800. It also serves the console.
PostgreSQL
Applications, worlds, runs, results, and the job queue.
workers take jobs and report back
Workers
Build worlds and run episodes. Add workers to do more at once.
Sandbox
One world's containers, on a network with no internet.
Sandbox
Removed when the work ends.
Model providers
The only outside service workers call. Keys stay on the server.
The parts
| Part | What it does | How it runs |
|---|---|---|
| API and console | Takes every request, and serves the console to browsers | One container, on port 7800 |
| PostgreSQL | Holds applications, worlds, runs and results. It is also the queue of work | A managed database, or a container on the same host |
| Workers | Take work from the queue: build worlds, run episodes, improve agents | One or more containers. More workers do more at once |
| Sandboxes | The containers of one world, on a network with no internet access | Started and removed by the workers, with the host's Docker |
| Model provider | The language models that build worlds and play the customer | An outside service. Its key stays on the server |
Two things follow from this design:
- Nothing runs without a worker. The API accepts a build or a run and puts it in the queue. If no worker is running, the work stays "queued".
- A worker controls Docker on its host. It starts containers from the images that applications name. Give Rehearsal a machine of its own.
Start here
RequirementsThe machine, the database and the model key you need.Install with Docker ComposeFrom a clone of the repository to a signed-in console.TroubleshootingEach message you can meet, why, and the fix.
What differs from the hosted service
| Hosted | Your server | |
|---|---|---|
| Plans and limits | Every workspace is on a plan | Off, unless you set REHEARSAL_PLANS=on |
| Sign-up | Open | Open, unless you set REHEARSAL_SIGNUP=closed. rehearsal users add puts a person in a project that exists |
| Model calls | On Rehearsal's model account, within the plan's allowance | On your provider keys. Your provider bills you |
| A spend limit | The plan's monthly allowance | REHEARSAL_MONTHLY_ALLOWANCE_USD for the whole server. Off by default |
| Application source from a folder | No | Yes, for folders inside REHEARSAL_SOURCE_ROOTS |
Checked against rehearsal-kit 0.1.2 on 11 October 2026.
Was this page helpful?