​

Docker (optional)

​

Is Docker right for me?

• Yes: you want an isolated, throwaway gateway environment or to run Clawdbot on a host without local installs.
• No: you’re running on your own machine and just want the fastest dev loop. Use the normal install flow instead.
• Sandboxing note: agent sandboxing uses Docker too, but it does not require the full gateway to run in Docker. See Sandboxing.

• Containerized Gateway (full Clawdbot in Docker)
• Per-session Agent Sandbox (host gateway + Docker-isolated agent tools)

​

Requirements

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

​

Containerized Gateway (Docker Compose)

​

Quick start (recommended)

./docker-setup.sh

• builds the gateway image
• runs the onboarding wizard
• prints optional provider setup hints
• starts the gateway via Docker Compose
• generates a gateway token and writes it to .env

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

• ~/.clawdbot/
• ~/clawd

​

Manual flow (compose)

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

​

Provider setup (optional)

docker compose run --rm clawdbot-cli providers login

docker compose run --rm clawdbot-cli providers add --provider telegram --token "<token>"

docker compose run --rm clawdbot-cli providers add --provider discord --token "<token>"

​

Health check

docker compose exec clawdbot-gateway node dist/index.js health --token "$CLAWDBOT_GATEWAY_TOKEN"

​

E2E smoke test (Docker)

scripts/e2e/onboard-docker.sh

​

QR import smoke test (Docker)

pnpm test:docker:qr

​

Notes

• Gateway bind defaults to lan for container use.
• The gateway container is the source of truth for sessions (~/.clawdbot/agents/<agentId>/sessions/).

​

Agent Sandbox (host gateway + Docker tools)

​

What it does

• scope: "agent" by default (one container + workspace per agent)
• scope: "session" for per-session isolation
• per-scope workspace folder mounted at /workspace
• optional agent workspace access (agent.sandbox.workspaceAccess)
• allow/deny tool policy (deny wins)
• inbound media is copied into the active sandbox workspace (media/inbound/*) so tools can read it (with workspaceAccess: "rw", this lands in the agent workspace)

​

Per-agent sandbox profiles (multi-agent)

• Full access (personal agent)
• Read-only tools + read-only workspace (family/work agent)
• No filesystem/shell tools (public agent)

​

Default behavior

• Image: clawdbot-sandbox:bookworm-slim
• One container per agent
• Agent workspace access: workspaceAccess: "none" (default) uses ~/.clawdbot/sandboxes
  • "ro" keeps the sandbox workspace at /workspace and mounts the agent workspace read-only at /agent (disables write/edit)
  • "rw" mounts the agent workspace read/write at /workspace
• Auto-prune: idle > 24h OR age > 7d
• Network: none by default (explicitly opt-in if you need egress)
• Default allow: bash, process, read, write, edit, sessions_list, sessions_history, sessions_send, sessions_spawn
• Default deny: browser, canvas, nodes, cron, discord, gateway

​

Enable sandboxing

{
  agent: {
    sandbox: {
      mode: "non-main", // off | non-main | all
      scope: "agent", // session | agent | shared (agent is default)
      workspaceAccess: "none", // none | ro | rw
      workspaceRoot: "~/.clawdbot/sandboxes",
      docker: {
        image: "clawdbot-sandbox:bookworm-slim",
        workdir: "/workspace",
        readOnlyRoot: true,
        tmpfs: ["/tmp", "/var/tmp", "/run"],
        network: "none",
        user: "1000:1000",
        capDrop: ["ALL"],
        env: { LANG: "C.UTF-8" },
        setupCommand: "apt-get update && apt-get install -y git curl jq",
        pidsLimit: 256,
        memory: "1g",
        memorySwap: "2g",
        cpus: 1,
        ulimits: {
          nofile: { soft: 1024, hard: 2048 },
          nproc: 256
        },
        seccompProfile: "/path/to/seccomp.json",
        apparmorProfile: "clawdbot-sandbox",
        dns: ["1.1.1.1", "8.8.8.8"],
        extraHosts: ["internal.service:10.0.0.5"]
      },
      tools: {
        allow: ["bash", "process", "read", "write", "edit", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn"],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"]
      },
      prune: {
        idleHours: 24, // 0 disables idle pruning
        maxAgeDays: 7  // 0 disables max-age pruning
      }
    }
  }
}

​

Build the default sandbox image

scripts/sandbox-setup.sh

​

Sandbox common image (optional)

scripts/sandbox-common-setup.sh

{
  agent: { sandbox: { docker: { image: "clawdbot-sandbox-common:bookworm-slim" } } }
}

​

Sandbox browser image

scripts/sandbox-browser-setup.sh

• Headful (Xvfb) reduces bot blocking vs headless.
• Headless can still be used by setting agent.sandbox.browser.headless=true.
• No full desktop environment (GNOME) is needed; Xvfb provides the display.

{
  agent: {
    sandbox: {
      browser: { enabled: true }
    }
  }
}

{
  agent: {
    sandbox: { browser: { image: "my-clawdbot-browser" } }
  }
}

• a sandbox browser control URL (for the browser tool)
• a noVNC URL (if enabled and headless=false)

​

Custom sandbox image

docker build -t my-clawdbot-sbx -f Dockerfile.sandbox .

{
  agent: {
    sandbox: { docker: { image: "my-clawdbot-sbx" } }
  }
}

​

Tool policy (allow/deny)

• deny wins over allow.
• If allow is empty: all tools (except deny) are available.
• If allow is non-empty: only tools in allow are available (minus deny).

​

Pruning strategy

• prune.idleHours: remove containers not used in X hours (0 = disable)
• prune.maxAgeDays: remove containers older than X days (0 = disable)

• Keep busy sessions but cap lifetime: idleHours: 24, maxAgeDays: 7
• Never prune: idleHours: 0, maxAgeDays: 0

​

Security notes

• Hard wall only applies to tools (bash/read/write/edit).
• Host-only tools like browser/camera/canvas are blocked by default.
• Allowing browser in sandbox breaks isolation (browser runs on host).

​

Troubleshooting

• Image missing: build with scripts/sandbox-setup.sh or set agent.sandbox.docker.image.
• Container not running: it will auto-create per session on demand.
• Permission errors in sandbox: set docker.user to a UID:GID that matches your mounted workspace ownership (or chown the workspace folder).