The Operator Vault Docker Guide

OpenClaw Docker Setup Guide

Isolated. Reproducible. One Command.

We run OpenClaw in Docker on every production VPS we manage. This guide shares our proven setup for containerized gateways, sandboxed tool execution, and production-ready Docker Compose configs.

Start the $19 WorkshopVPS Deployment Guide

Honest assessment

Should you even use Docker?

In our experience, Docker adds a layer of complexity. For some setups it is the right call. For others, the native install is faster and simpler. Here is how we recommend thinking about it.

VPS production server

Running on a Hostinger, DigitalOcean, or any Linux VPS? We recommend Docker here. It gives you reproducible deploys, easy rollbacks, and clean container isolation.

Multi-agent sandboxing

Want isolated tool execution per agent or per session? Docker sandboxes give each agent its own container with locked-down permissions.

Local dev on your Mac

For day-to-day development on your own machine, we recommend skipping Docker. The native Node install gives you a faster feedback loop and no container overhead.

Quick testing or demos

Just want to try OpenClaw? Use the standard installer. Docker is for when you have already decided on containerized deployment.

Quick start

One script. Fully configured.

The docker-setup.sh script handles the entire setup. Build, configure, launch.

terminal
$ git clone https://github.com/openclaw/openclaw.git
$ cd openclaw
$ ./docker-setup.sh
# What this does under the hood:
# 1. Builds the gateway Docker image
# 2. Runs the onboarding wizard (model provider, channels)
# 3. Generates a gateway auth token, writes it to .env
# 4. Starts the gateway via Docker Compose
# 5. Writes config to ~/.openclaw/ on the host
Gateway running at http://127.0.0.1:18789/
OPENCLAW_DOCKER_APT_PACKAGES

Bake extra apt packages into the image at build time

OPENCLAW_EXTRA_MOUNTS

Comma-separated host bind mounts for both gateway and CLI

OPENCLAW_HOME_VOLUME

Named volume for /home/node so caches survive restarts

New to OpenClaw? The $19 workshop walks you through the full setup from scratch, including Docker configuration. 15 minutes, lifetime access.

Learn More

Architecture

Two ways to use Docker

You can run the entire Gateway in Docker, or keep the Gateway on your host and only use Docker for sandboxed tool execution. We have tested both extensively. Each approach has distinct tradeoffs.

Mode A

Full Gateway in Docker

Docker Container
Gateway + Agent Runtime
Node.js, Tools, Channels
|
Host: ~/.openclaw/ (bind mount)
  • Everything runs inside a single container
  • Config and workspace bind-mounted from host
  • Best for VPS production deployments
  • Use docker-setup.sh for one-command setup
Mode B

Host Gateway + Docker Sandbox

Gateway (runs on host)
|
Docker Sandbox Containers
execreadwriteedit
  • Gateway runs natively for best performance
  • Tool execution isolated in Docker containers
  • One sandbox per agent or per session
  • Best for multi-agent setups with mixed trust levels

Sandbox security

Locked down by default

In our testing, OpenClaw sandbox containers go well beyond basic Docker. They ship with defense-in-depth hardening, and every sandbox starts with the smallest attack surface possible.

capDrop: ALL

Every Linux capability is dropped. The container cannot change system settings, mount filesystems, or escalate privileges.

readOnlyRoot: true

The root filesystem is read-only. The only writable locations are /tmp, /var/tmp, /run (tmpfs), and the mounted workspace.

network: "none"

No network access by default. The sandbox cannot reach the internet, your LAN, or the host. You must opt-in for egress.

seccomp profile

Optional seccomp JSON profile restricts which system calls the container can make. Block ptrace, mount, and other sensitive syscalls.

user: 1000:1000

Runs as an unprivileged user by default. Never root inside the sandbox unless you explicitly override for package installs.

pidsLimit: 256

Process count is capped at 256. Fork bombs and runaway processes cannot consume host resources.

Additional hardening options include AppArmor profiles, memory and CPU limits, ulimit overrides (nofile, nproc), DNS pinning, and custom extra hosts. All configured under agents.defaults.sandbox.docker in your openclaw.json.

Want us to walk you through all of this?

The Operator Vault workshop covers Docker setup, security configuration, and your first working agent. Our team guides you through every step.

$19 Workshop

Reference config

Docker Compose, annotated

docker-compose.yml
services:
  openclaw-gateway:
    image: openclaw:local
    build: .                           # builds from repo Dockerfile
    restart: unless-stopped            # auto-restart on crash
    env_file:
      - .env                           # gateway token, API keys
    environment:
      - HOME=/home/node
      - NODE_ENV=production
      - OPENCLAW_GATEWAY_BIND=lan      # listen on all interfaces
      - OPENCLAW_GATEWAY_PORT=18789
    volumes:
      - ~/.openclaw:/home/node/.openclaw           # config
      - ~/.openclaw/workspace:/home/node/.openclaw/workspace  # agent data
    ports:
      - "127.0.0.1:18789:18789"       # loopback only
    command:
      ["node", "dist/index.js", "gateway",
       "--bind", "lan", "--port", "18789"]

  openclaw-cli:                        # one-off commands
    image: openclaw:local
    profiles: ["cli"]
    volumes:
      - ~/.openclaw:/home/node/.openclaw
      - ~/.openclaw/workspace:/home/node/.openclaw/workspace

Key detail: The port binding uses 127.0.0.1: prefix so the gateway is only reachable from localhost. Access it remotely via SSH tunnel or Tailscale VPN. Never expose port 18789 to the public internet without authentication configured.

Multi-agent profiles

Three agents. Three trust levels.

Run mixed access levels from a single gateway. Each agent gets its own sandbox profile, tool permissions, and workspace access.

Personal Agent

Full Access
Filesystemread/write
Shell execfull
Browserhost control
Networkunrestricted
Workspacerw

Your main agent. Full tool access, no sandbox. Runs on the host with complete trust.

Work Agent

Read Only
Filesystemread only
Shell execsandboxed
Browserdisabled
Networknone
Workspacero

Can read your workspace and run commands inside a sandbox, but cannot modify files or browse the web.

Public Agent

No Filesystem
Filesystemnone
Shell execdisabled
Browserdisabled
Networknone
Workspacenone

Conversation only. No tool access, no filesystem, no shell. Safe for external-facing chat sessions.

Channels

Pair your channels from Docker

WhatsApp, Telegram, Discord. We have tested all three from Docker and each one takes a single command to configure.

WhatsApp

$ docker compose run --rm openclaw-cli channels login

Scan the QR code with your phone to pair WhatsApp.

Telegram

$ docker compose run --rm openclaw-cli channels add --channel telegram --token "<BOT_TOKEN>"

Get your bot token from @BotFather on Telegram.

Discord

$ docker compose run --rm openclaw-cli channels add --channel discord --token "<BOT_TOKEN>"

Create a bot in the Discord Developer Portal first.

Troubleshooting

Common issues, quick fixes

EACCES: permission denied on /home/node/.openclaw

Why: Host bind mounts are not owned by uid 1000 (the container's node user).

Fix: sudo chown -R 1000:1000 ~/.openclaw
Port 18789 already in use

Why: Another process or a previous container is still bound to the gateway port.

Fix: docker compose down && docker compose up -d
Sandbox image not found: openclaw-sandbox:bookworm-slim

Why: The sandbox image has not been built yet on this host.

Fix: scripts/sandbox-setup.sh
Volume mount not working on macOS

Why: Docker Desktop requires explicit sharing of host directories.

Fix: Docker Desktop > Settings > Resources > File Sharing. Add ~/.openclaw/ to the shared paths.
Gateway says 'unauthorized' or 'disconnected (1008)'

Why: The browser device has not been approved, or the gateway token is stale.

Fix: docker compose run --rm openclaw-cli dashboard --no-open
Kevin Jeppesen, Founder of The Operator Vault

Written by

Kevin Jeppesen

Founder, The Operator Vault

Kevin is an early OpenClaw adopter who has saved an estimated 400 to 500 hours through AI automation. He stress-tests new workflows daily, sharing what actually works through step-by-step guides and a security-conscious approach to operating AI with real tools.

Docker FAQ

Docker-specific questions

Docker + VPS =
always-on AI agent for $5/month.

Our workshop walks you through OpenClaw setup from scratch. Install it, configure it, and send your first command. 15 minutes, $19, lifetime access.

>_Start the $19 WorkshopVPS Deployment Guide
Start HereInstallation GuideCloud VPS SetupSetup GuideSecurity GuideWorkshop