Everything so far has run on your local machine. For a real agent that runs twenty-four seven, you need isolation and reproducibility. Docker gives you both — a portable, sandboxed environment that works the same everywhere.
Your agent can’t touch the host filesystem. Sandbox mode non-main runs non-main sessions in per-session Docker containers automatically.
Same image everywhere — dev, staging, production. Pre-built images available on GitHub Container Registry with version-specific tags. No “works on my machine” surprises.
Containers provide a hard security boundary. Combined with gVisor for kernel isolation, your agent runs in a sandboxed environment with controlled access to resources.
agents.defaults.sandbox.modeInstall Docker Desktop or Docker Engine. Pre-built OpenClaw images are hosted at ghcr.io/openclaw/openclaw. Pull the latest image to get started.
Run docker compose up -d and your agent is running in a container. All your existing config in ~/.openclaw carries over seamlessly via the volume mount.
| off | No sandboxing. All sessions run on the host. |
| non-main | Non-main sessions run in per-session Docker containers. Main agent runs on host. |
| all | Every session — including main — runs inside a Docker container. |
| session | Each session gets its own isolated container. |
| agent | All sessions for an agent share one container. |
| shared | All agents share a single container. |
| none | Sandbox only, no workspace mount. (Default) |
| ro | Read-only access to /agent |
| rw | Read-write access to /workspace |
For maximum containment, enable gVisor — an application kernel that intercepts system calls and provides an additional isolation layer between the container and the host kernel.
Pass API keys via environment variables rather than baking them into the image. Use env_file: .env or inline environment: blocks in your compose file.
unless-stopped for productionUse sandbox.docker.setupCommand to run custom setup scripts when sandbox containers start — install additional packages, configure tools, or set up environment-specific dependencies.
Docker bypasses host UFW rules entirely. If you rely on UFW for firewall management, you must add explicit rules to the DOCKER-USER iptables chain to restrict container network access.
Docker isolation + sandbox mode + tool policies + gateway auth = four independent security layers. Each one can fail independently without compromising the whole system.
Create a systemd service file that starts your Docker container on boot. Use Restart=always and RestartSec=10 for automatic recovery from crashes.
Your workspace is just Markdown files — back up with git or rsync. Version control your SOUL.md, AGENTS.md, and MEMORY.md. Daily notes are time-stamped files, easy to archive.
gateway.channelHealthCheckMinutesPull new image, restart the container. Your workspace and config persist in volumes, so updates are non-destructive. Tags include latest, main, and version-specific — docker compose pull && docker compose up -d
Install Docker Desktop (macOS/Windows) or Docker Engine (Linux). Verify with docker --version and docker compose version. Make sure the Docker daemon is running.
Write a compose file that mounts your ~/.openclaw directory, your workspace, and exposes port 18789. Use restart: unless-stopped for resilience.
Run docker compose up -d and verify your agent is reachable. Test it from your configured channels — Telegram, Discord, or the web interface. Confirm your existing config carries over.
Set agents.defaults.sandbox.mode: "non-main" in your config. Spawn a sub-agent and verify it runs in its own Docker container. Check that the sub-agent can’t access the host filesystem.
Your agent runs in a container. Now it needs a home that never sleeps. On Day 13 we take everything from your local Docker setup and deploy it to a VPS — a cloud server that runs your agent around the clock, handles restarts, and stays online while your laptop sleeps.