Clawdbot Docker Installation

Clawdbot Docker Overview

Docker is optional for Clawdbot. Use it only if you want a containerized gateway or to validate the Docker flow.

Is Docker Right for Me?

Note: Agent sandboxing uses Docker too, but it does not require the full gateway to run in Docker.

Requirements

• Docker Desktop (or Docker Engine) + Docker Compose v2
• Enough disk space for images + logs

Containerized Gateway (Docker Compose)

Quick Start (Recommended)

From repo root:

./docker-setup.sh

This script:

1. Builds the gateway image
2. Runs the onboarding wizard
3. Prints optional provider setup hints
4. Starts the gateway via Docker Compose
5. Generates a gateway token and writes it to .env

Optional environment variables:

After it finishes:

1. Open http://127.0.0.1:18789/ in your browser
2. Paste the token into the Control UI (Settings → token)

Need the tokenized URL again?

docker compose run --rm clawdbot-cli dashboard --no-open

Manual Flow (Compose)

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

Control UI Token + Pairing (Docker)

If you see "unauthorized" or "disconnected (1008): pairing required":

docker compose run --rm clawdbot-cli dashboard --no-open
docker compose run --rm clawdbot-cli devices list
docker compose run --rm clawdbot-cli devices approve <requestId>

Extra Mounts (Optional)

Mount additional host directories into containers:

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

Persist Container Home (Optional)

Persist /home/node across container recreation:

export CLAWDBOT_HOME_VOLUME="clawdbot_home"
./docker-setup.sh

Install Extra Packages (Optional)

Install system packages inside the image:

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

Agent Sandbox (Docker Tools)

Clawdbot can use Docker for agent sandboxing, isolating agent tools in containers.

What It Does

• Runs agent tools (exec, browser, etc.) in isolated Docker containers
• Provides security boundaries between agents
• Allows per-agent sandbox profiles

Enable Sandboxing

In your clawdbot.json:

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main"
      }
    }
  }
}

Build the Sandbox Image

clawdbot sandbox build

Per-Agent Sandbox Profiles

{
  "routing": {
    "agents": {
      "main": {
        "workspace": "~/.clawdbot/workspace",
        "sandbox": {
          "mode": "off"
        }
      },
      "untrusted": {
        "sandbox": {
          "mode": "always"
        }
      }
    }
  }
}

Health Check

docker compose run --rm clawdbot-cli health
docker compose run --rm clawdbot-cli status

Troubleshooting

Permission Errors (EACCES)

If you see permission errors, check that the mounted directories have correct permissions.

Container Won't Start

1. Check Docker logs: docker compose logs clawdbot-gateway
2. Verify port 18789 is not in use
3. Ensure Docker has enough resources

Token Issues

Regenerate the gateway token:

docker compose run --rm clawdbot-cli configure --reset-token

Next Steps

• Clawdbot Installation - Other install methods
• Clawdbot Gateway - Gateway configuration
• Clawdbot Setup - Complete setup guide