Run the Engine in Docker
The engine ships as a published container image — the same one the VS Code extension's Docker mode pulls:
ghcr.io/rocketride-org/rocketride-engine
Setting up from a coding agent? The coding-agents start page has a ready-to-run
docker runcommand plus the health check, the client key and the MCP connection, in one place.
Quickstart
docker run -d --name rocketride-engine --platform linux/amd64 \
-p 127.0.0.1:5565:5565 \
-v rocketride-data:/opt/data \
--restart unless-stopped \
ghcr.io/rocketride-org/rocketride-engine:latest
This command is enough for the CLI and SDK. For the built-in MCP server use the
command in MCP on this engine instead, which adds two -e
settings. Both commands carry --platform linux/amd64, which Apple Silicon needs
and Intel and AMD machines ignore (see The image).
Point any client at it and go. A client needs a non-empty key, and an engine started without one accepts any value:
export ROCKETRIDE_URI=ws://localhost:5565
export ROCKETRIDE_APIKEY=rr_local
The 127.0.0.1: prefix keeps the engine reachable only from the machine
itself — the right default, since an engine started without a key accepts any
non-empty one. Widen it only behind TLS and authentication (see
Security).
The image
-
Tags: each release publishes its version tag plus
latest; prerelease builds carry a-prereleasesuffix. Pin a version tag in production. -
Platform:
linux/amd64only. On Apple Silicon add--platform linux/amd64(Docker runs it under emulation — fine for development; the VS Code extension does the same). -
Carries the node archive in
/opt/nodes, so runs get their nodes without internet access. -
Runs as non-root (user
rocketride, uid 1000), listens on 5565, and starts the engine bound to all container interfaces — the port mapping above is what controls actual exposure. -
Signed: images are cosign-signed from CI. Verify keyless:
cosign verify \
--certificate-identity-regexp 'https://github.com/rocketride-org/rocketride-server/' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
ghcr.io/rocketride-org/rocketride-engine:latest
Configuration
The engine reads configuration from its environment — pass variables with
-e/--env-file:
- Provider credentials for your pipelines (OpenAI, Anthropic, database
DSNs, …): set them in the engine's environment and reference them from
node config as
${VAR}— see Self-hosting. - MCP OAuth settings if AI assistants will connect to
/mcpon this engine:MCP_EXPECTED_AUDIENCEand friends — see MCP self-hosting.
MCP on this engine
The image binds all container interfaces, so the engine treats itself as a
public bind. For the built-in MCP server at http://localhost:5565/mcp to work,
start the container with an rr_ key. Engine image 3.6.0 and earlier also need
ROCKETRIDE_URI (see below); the command sets it because it is safe on any
version. If you already ran the quickstart command, remove that container first with docker rm -f rocketride-engine; the rocketride-data volume is kept.
docker run -d --name rocketride-engine --platform linux/amd64 \
-p 127.0.0.1:5565:5565 \
-v rocketride-data:/opt/data \
--restart unless-stopped \
-e ROCKETRIDE_APIKEY=rr_local \
-e ROCKETRIDE_URI=ws://127.0.0.1:5565 \
ghcr.io/rocketride-org/rocketride-engine:latest
MCP clients then send Authorization: Bearer rr_local. The key must start with
rr_. When neither ROCKETRIDE_URI nor MCP_RESOURCE_IDENTIFIER is set, the
engine runs MCP tool calls against itself (ws://127.0.0.1:<port>). Engine image 3.6.0
and earlier instead connect them to RocketRide Cloud, where they fail with
Invalid or revoked API key; on those versions set ROCKETRIDE_URI as in the
command above (setting it is safe on an engine that listens on loopback or on all interfaces, which is the default and the Docker image). The CLI and SDK must send the same
ROCKETRIDE_APIKEY the engine was started with. See MCP self-hosting.
Persistence
The engine writes runtime data to /opt/data (declared as a volume). Mount a
named volume or host path there — it's the only path that needs to survive
container replacement, and the one to back up. It must be writable by uid 1000;
the engine checks at startup and refuses to start, naming the fix, if it is not.
Health and upgrades
The image has a built-in healthcheck against the engine's public version
endpoint, so docker ps shows real health:
curl http://localhost:5565/version
(Use /version, not /ping: /version is the address that answers without
a key. Every unknown path, including /ping, /health and /healthz,
answers 401.)
Upgrading is pull-and-replace; state lives in the volume:
docker pull --platform linux/amd64 ghcr.io/rocketride-org/rocketride-engine:latest
docker rm -f rocketride-engine
# re-run the same docker run command you started it with
Upgrading from an image that ran as a system user (uid 999): the existing volume
still belongs to that user, so the new engine cannot write to it and exits with
/opt/data is not writable by uid 1000. Hand the volume over once, before
starting the new image:
docker run --rm -v rocketride-data:/opt/data alpine chown -R 1000:1000 /opt/data
For a host path, run sudo chown -R 1000:1000 <path> instead.
Compose
A minimal production compose file:
services:
engine:
image: ghcr.io/rocketride-org/rocketride-engine:latest
platform: linux/amd64
ports:
- '127.0.0.1:5565:5565'
volumes:
- rocketride-data:/opt/data
env_file: .env # provider credentials
restart: unless-stopped
volumes:
rocketride-data:
The repository's own
docker/docker-compose.ymlis a development stack: it builds the image from a local source build and bundles Postgres, Milvus, and Chroma with default passwords. Use it for hacking on RocketRide, not for serving it.
Next
- Kubernetes: the Helm chart, for clustered deployments.
- Production: topology and sizing.
- Security: TLS, authentication, and exposure.