Platforms

Custom Platform

Run the Rivet control plane on any platform that can run a container.

The control plane is a single container image, rivetdev/engine. Any platform that can run it with a persistent volume and a stable address can host it.

Requirements

Your platform must provide:

A container runtime, or a Linux host you can run the binary on.
A persistent volume. The control plane is stateful. Storage that resets on redeploy will lose actor state.
A stable network identity, so workers keep reaching the same place.
Long-lived connections. Platforms that cap request duration or idle time below an hour will sever WebSockets. This rules out serverless platforms entirely.
SIGTERM plus a grace period, so the control plane can drain and flush state before it is killed.

Steps

Generate an admin token

openssl rand -hex 32

Store it wherever your platform keeps secrets. Without it, the API is unauthenticated.

Run the image

Pin the tag. Never run latest in production.

docker run -d \
  --restart unless-stopped \
  -p 6420:6420 \
  -p 6421:6421 \
  -v rivet-data:/data \
  -e RIVET__FILE_SYSTEM__PATH="/data" \
  -e RIVET__AUTH__ADMIN_TOKEN="<your-token>" \
  rivetdev/engine:2.3.3

For multi-node, drop the file system variable, set RIVET__POSTGRES__URL instead, and add NATS for pub/sub. Do not replicate or autoscale a node that is still on the file system backend: RocksDB is single-node. See Storage.

Expose the ports

6420 carries API, dashboard, and WebSocket traffic and should sit behind TLS. 6421 serves health checks and should stay internal. See Ports.

Raise the load balancer idle timeout

Set idle, read, and send timeouts to at least 3600 seconds on every proxy in the path. The 30 to 60 second defaults sever live WebSockets and cause reconnect storms.

Verify

curl -i http://<host>:6421/health

Expect 200. The dashboard is at /ui on port 6420.

Create the runner config

A runner config declares a pool that workers connect to. Without one the control plane refuses every worker, so create it before deploying any:

curl -X PUT "http://<host>:6420/runner-configs/default?namespace=default" \
  -H "Authorization: Bearer $RIVET_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"datacenters":{"default":{"normal":{}}}}'

Use normal for long-lived workers. See Runner configs.

Connect a worker

Point a worker at the control plane and confirm it appears under Runners:

RIVET_ENDPOINT="https://default:<admin-token>@your-control-plane.example.com"

Troubleshooting

Workers connect, then drop every 30 to 60 seconds. The load balancer idle timeout is still at its default.

State disappears after a deploy. The volume is not persistent, or the data path does not point at it.

The dashboard rejects your token. RIVET__AUTH__ADMIN_TOKEN is not reaching the container. Confirm the variable name, including the double underscores.