Docker (optional)

Scope

Docker is optional. Use it when you want a containerized Gateway (repeatable builds, clean isolation), or when you’re validating the Docker flow.

Agent sandboxing also uses Docker, but you do not need to run the full Gateway in Docker to use sandboxed tools. See /docs/gateway/sandboxing/.

Is Docker right for me?

Yes: you want an isolated Gateway, or you’re running on a host where you don’t want to install Node/tooling globally.
No: you want the fastest local dev loop. Use the normal install flow: /docs/install/.

Requirements

Docker Desktop (macOS/Windows) or Docker Engine (Linux) + Docker Compose v2
Enough disk space for images and logs

Containerized Gateway (Docker Compose)

Quick start (recommended)

From the Moltbot repo root:

./docker-setup.sh

What it does:

builds the Gateway image
runs onboarding
writes a Gateway token to .env
starts the Gateway via docker compose

After it finishes:

open http://127.0.0.1:18789/
paste the token (Control UI → Settings → token)

Where data lives (persistence)

Containers are ephemeral; long-lived state should be on the host:

~/.moltbot/ (config, credentials, sessions)
~/clawd/ (workspace, memory, artifacts)

Manual flow (compose)

docker build -t moltbot:local -f Dockerfile .
docker compose run --rm moltbot-cli onboard
docker compose up -d moltbot-gateway

Verify

docker compose logs -f moltbot-gateway

Health probe (token required):

docker compose exec moltbot-gateway node dist/index.js health --token "$MOLTBOT_GATEWAY_TOKEN"

Installing extra system packages (optional)

If you need packages inside the image (e.g. ffmpeg), install them at image build time:

export MOLTBOT_DOCKER_APT_PACKAGES="ffmpeg build-essential"
./docker-setup.sh

Extra mounts (optional)

Mount additional host folders into the containers:

export MOLTBOT_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

Persist the entire container home (optional)

If you want /home/node to survive container recreation, use a named volume:

export MOLTBOT_HOME_VOLUME="moltbot_home"
./docker-setup.sh

Important: bake required binaries into the image

If a skill depends on external binaries, don’t install them inside a running container. Add them to the Dockerfile (or the image build step), then rebuild and restart.

Running on a VPS

Start with:

Hetzner (Docker VPS): /docs/platforms/hetzner/
GCP (Docker VM): /docs/platforms/gcp/

Agent Sandbox (host gateway + Docker tools)

When sandboxing is enabled, non-main sessions run tools inside Docker while the Gateway stays on the host. Deep dive: /docs/gateway/sandboxing/.