Docker

Containerized deployment with Docker Compose. Includes optional agent sandboxing, browser containers, and health checks.

Docker is the recommended deployment method for servers, VPS instances, and anyone who wants full isolation between OpenClaw and their host system. The containerized gateway runs inside Docker Compose, with built-in health checks, optional agent sandboxing, and support for browser containers — all managed through a single setup script. The setup flow is straightforward: clone the repo, run `./scripts/docker/setup.sh`, and the script handles building the image, running onboarding (provider selection, channel setup), and starting the gateway. You can skip the local build entirely by pointing to the pre-built GitHub Container Registry image with `OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"`. Pre-built images are tagged by version, with `latest` and `main` always available. Docker deployment is particularly powerful for its sandboxing capabilities. Agent sandboxing uses separate Docker containers to isolate tool execution — so when your AI agent runs shell commands or code, it does so in a throwaway container rather than on your host. This is critical for production use where you don't want an AI agent to have unrestricted access to your server. The Docker image also includes built-in health check endpoints (`/healthz` for liveness, `/readyz` for readiness) that orchestration systems can use for automatic restarts. The Docker Compose setup supports extensive customization through environment variables: `OPENCLAW_DOCKER_APT_PACKAGES` for extra system packages, `OPENCLAW_EXTENSIONS` for pre-installed extensions, `OPENCLAW_EXTRA_MOUNTS` for bind mounts, and `OPENCLAW_HOME_VOLUME` for persisting the home directory. Channels are configured through the CLI container: `docker compose run --rm openclaw-cli channels login` for WhatsApp, or `docker compose run --rm openclaw-cli channels add --channel telegram --token "<token>"` for Telegram. One important security note: if you're deploying on a VPS or any publicly accessible server, Docker's default networking can bypass UFW firewall rules. You need to configure the `DOCKER-USER` iptables chain to prevent Docker from inadvertently exposing ports. The OpenClaw security docs cover this in detail, and it's one of the most commonly missed steps in self-hosted deployments.

Tags: container, docker, portable, self-hosted, sandbox

Use Cases

  • Production deployment on a VPS or dedicated server with full isolation from the host
  • Self-hosted AI assistant with agent sandboxing for safe tool execution
  • Running OpenClaw alongside other Docker services (reverse proxy, monitoring) in a compose stack
  • CI/CD environments where containerized, reproducible deployments are required
  • Security-conscious deployments where you want container-level isolation from the host OS

Tips

  • Use pre-built GHCR images (ghcr.io/openclaw/openclaw:latest) to skip the 5-10 minute local build
  • Set OPENCLAW_SANDBOX=1 to enable agent sandboxing — isolates tool execution in throwaway containers
  • Use docker compose logs -f openclaw-gateway to tail gateway logs in real-time
  • Set up /healthz and /readyz endpoints in your monitoring stack for automatic restart on failures
  • Bind to 127.0.0.1 (not 0.0.0.0) unless you've hardened your firewall — the setup script does this by default
  • Use OPENCLAW_HOME_VOLUME to persist agent workspace data across container rebuilds
  • For VPS deployments, always use SSH tunneling or Tailscale to access the Control UI — don't expose it publicly

Known Issues & Gotchas

  • Docker's default networking bypasses UFW firewall rules — configure the DOCKER-USER iptables chain on public servers to prevent unintended port exposure
  • The image build requires 2GB+ RAM — 1GB hosts will get OOM-killed (exit code 137) during pnpm install
  • Docker Desktop on macOS has performance overhead for file I/O — consider native install for development workflows
  • Don't expose port 18789 to the public internet without authentication — the gateway token is your only auth layer
  • If you enable OPENCLAW_EXTRA_MOUNTS, include the generated docker-compose.extra.yml with -f flag when running docker compose commands
  • WhatsApp channel login requires an interactive terminal — use docker compose run --rm (not exec) for the QR code flow
  • Pre-built images from GHCR may lag behind the latest npm release by a few hours

Alternatives

  • Podman
  • Installer Script
  • Ansible
  • Fly.io / Railway

Community Feedback

I run mine on a Pi in Docker as a good first step. Secondly you need to separate the agent from you 100%. Never give the agent access to any of your stuff.

— Reddit r/selfhosted

It runs in its own VM (not the docker image) that is allowed out to the internet, and has read access to one share on my NAS. Not connected to anything else.

— Reddit r/sysadmin

Running OpenClaw in the same Docker network as n8n is risky because OpenClaw has broad tool access by design. Isolate it.

— Reddit r/AI_Agents

OpenClaw reads 3 files from ~/.openclaw/. The Docker setup makes this clean — mount the volume, configure env vars, done.

— Reddit r/selfhosted

Frequently Asked Questions

Does the gateway have to run inside Docker?

No. Docker is optional. You can install OpenClaw directly on your machine and still use Docker only for agent sandboxing. The gateway itself runs fine as a native Node.js process.

How do I access the Control UI when running in Docker?

Open http://127.0.0.1:18789/ in your browser. On remote servers, use SSH tunneling: ssh -N -L 18789:127.0.0.1:18789 user@server. The gateway token from .env is needed to authenticate.

Can I use Docker Desktop on macOS?

Yes, but Docker Desktop has file I/O overhead on macOS due to the Linux VM layer. For personal development, the native install via Homebrew or npm is faster. Docker is better suited for server deployments.

How do I update the Docker deployment?

Pull the latest image with docker compose pull, then docker compose up -d openclaw-gateway. If building locally, run git pull, then docker compose build and up -d.

What's the difference between agent sandboxing and running the gateway in Docker?

Running the gateway in Docker isolates the OpenClaw process itself. Agent sandboxing uses separate containers for tool execution — shell commands, code runs, browser sessions. You can use sandboxing without running the gateway in Docker.

Does Docker bypass my firewall?

Yes, by default Docker's iptables rules can bypass UFW. On a public server, configure the DOCKER-USER chain to restrict external access. The OpenClaw security docs cover this — it's the most common self-hosting security mistake.

How much RAM does the Docker deployment need?

The build requires 2GB+ RAM. Running the gateway needs about 256-512MB. For agent sandboxing with multiple concurrent sandbox containers, 2-4GB total is recommended.