Run OpenClaw in an Isolated Docker Container

Why Docker Instead of Bare Metal?

Prerequisites

• Docker Desktop (macOS/Windows) or Docker Engine with Compose v2 (Linux)
• At least 2 GB RAM available (pnpm install will OOM-kill on 1 GB with exit code 137)
• Git installed
• An API key for your chosen LLM provider (Claude, GPT, Gemini, etc.)

Method 1: Official docker-setup.sh (Recommended)

The fastest way to get OpenClaw running inside Docker:

Step 1: Clone the Repository

Step 2: Configure Environment Variables (Optional)

Step 3: Run the Setup Script

This builds the Docker image, runs onboarding, and starts the gateway via Docker Compose. To skip the local build and use a pre-built image:

What the Docker Compose File Does

The official docker-compose.yml defines two services:

Method 2: Security-Hardened Docker Compose

For maximum isolation, use a hardened Compose configuration that adds several layers beyond the official defaults:

version: "3.8"

services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    user: "1000:1000"
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    deploy:
      resources:
        limits:
          cpus: "2.0"
          memory: 4096m
    ports:
      - "127.0.0.1:18789:18789"
      - "127.0.0.1:18790:18790"
    volumes:
      - ~/.openclaw:/home/node/.openclaw
      - ~/.openclaw/workspace:/home/node/.openclaw/workspace
    environment:
      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
    networks:
      - claw_isolated_net
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://127.0.0.1:18789/healthz"]
      interval: 30s
      timeout: 10s
      retries: 3

networks:
  claw_isolated_net:
    driver: bridge

Key security features of this configuration:

Before starting, generate a gateway token:

Volume Configuration: The Sandbox

Two host directories are mounted into the container for persistence:

To add extra mounts:

Enable the Agent Sandbox (Tool Isolation Inside Docker)

The sandbox runs tool execution inside separate short-lived containers while the main gateway stays running. This means even if a tool misbehaves, it can't affect the main agent container.

Or configure it in openclaw.json:

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "agent",
        "workspaceAccess": "none",
        "docker": {
          "image": "openclaw-sandbox:bookworm-slim",
          "network": "none",
          "memory": "1g",
          "cpus": 1
        }
      }
    }
  }
}

Connecting Messaging Channels Inside Docker

Use the CLI service to manage channels:

Health Monitoring

The Docker image includes a built-in HEALTHCHECK that pings these endpoints automatically:

Fixing Permission Issues

Since the container runs as node (UID 1000), bind mounts owned by root on the host will fail. Fix with:

Method 3: Manual Docker Workflow

For full control over each step:

For CI/non-interactive automation (suppress TTY):

Need a Production-Grade Docker Deployment?

At Codeloop, we build containerized AI agent deployments for production — with monitoring, automated restarts, log aggregation, security hardening, and multi-agent orchestration. For managing multiple Docker-deployed agents, consider Paperclip for team-level orchestration. Let us handle the infrastructure so your agents can focus on delivering value.