coderClaw

Docker (optional)

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

Is Docker right for me?

This guide covers:

Sandboxing details: Sandboxing

Requirements

Containerized Gateway (Docker Compose)

From repo root:

./docker-setup.sh

This script:

Optional env vars:

After it finishes:

It writes config/workspace on the host:

Running on a VPS? See Hetzner (Docker VPS).

Shell Helpers (optional)

For easier day-to-day Docker management, install ClawDock:

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/SeanHogg/coderClaw/main/scripts/shell-helpers/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh

Add to your shell config (zsh):

echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

Then use clawdock-start, clawdock-stop, clawdock-dashboard, etc. Run clawdock-help for all commands.

See ClawDock Helper README for details.

Manual flow (compose)

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

Note: run docker compose ... from the repo root. If you enabled CODERCLAW_EXTRA_MOUNTS or CODERCLAW_HOME_VOLUME, the setup script writes docker-compose.extra.yml; include it when running Compose elsewhere:

docker compose -f docker-compose.yml -f docker-compose.extra.yml <command>

Control UI token + pairing (Docker)

If you see “unauthorized” or “disconnected (1008): pairing required”, fetch a fresh dashboard link and approve the browser device:

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

More detail: Dashboard, Devices.

Extra mounts (optional)

If you want to mount additional host directories into the containers, set CODERCLAW_EXTRA_MOUNTS before running docker-setup.sh. This accepts a comma-separated list of Docker bind mounts and applies them to both coderclaw-gateway and coderclaw-cli by generating docker-compose.extra.yml.

Example:

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

Notes:

Persist the entire container home (optional)

If you want /home/node to persist across container recreation, set a named volume via CODERCLAW_HOME_VOLUME. This creates a Docker volume and mounts it at /home/node, while keeping the standard config/workspace bind mounts. Use a named volume here (not a bind path); for bind mounts, use CODERCLAW_EXTRA_MOUNTS.

Example:

export CODERCLAW_HOME_VOLUME="coderclaw_home"
./docker-setup.sh

You can combine this with extra mounts:

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

Notes:

Install extra apt packages (optional)

If you need system packages inside the image (for example, build tools or media libraries), set CODERCLAW_DOCKER_APT_PACKAGES before running docker-setup.sh. This installs the packages during the image build, so they persist even if the container is deleted.

Example:

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

Notes:

Power-user / full-featured container (opt-in)

The default Docker image is security-first and runs as the non-root node user. This keeps the attack surface small, but it means:

If you want a more full-featured container, use these opt-in knobs:

  1. Persist /home/node so browser downloads and tool caches survive:
export CODERCLAW_HOME_VOLUME="coderclaw_home"
./docker-setup.sh
  1. Bake system deps into the image (repeatable + persistent):
export CODERCLAW_DOCKER_APT_PACKAGES="git curl jq"
./docker-setup.sh
  1. Install Playwright browsers without npx (avoids npm override conflicts):
docker compose run --rm coderclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

If you need Playwright to install system deps, rebuild the image with CODERCLAW_DOCKER_APT_PACKAGES instead of using --with-deps at runtime.

  1. Persist Playwright browser downloads:

Permissions + EACCES

The image runs as node (uid 1000). If you see permission errors on /home/node/.coderclaw, make sure your host bind mounts are owned by uid 1000.

Example (Linux host):

sudo chown -R 1000:1000 /path/to/coderclaw-config /path/to/coderclaw-workspace

If you choose to run as root for convenience, you accept the security tradeoff.

To speed up rebuilds, order your Dockerfile so dependency layers are cached. This avoids re-running pnpm install unless lockfiles change:

FROM node:22-bookworm

# Install Bun (required for build scripts)
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"

RUN corepack enable

WORKDIR /app

# Cache dependencies unless package metadata changes
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts

RUN pnpm install --frozen-lockfile

COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build

ENV NODE_ENV=production

CMD ["node","dist/index.js"]

Channel setup (optional)

Use the CLI container to configure channels, then restart the gateway if needed.

WhatsApp (QR):

docker compose run --rm coderclaw-cli channels login

Telegram (bot token):

docker compose run --rm coderclaw-cli channels add --channel telegram --token "<token>"

Discord (bot token):

docker compose run --rm coderclaw-cli channels add --channel discord --token "<token>"

Docs: WhatsApp, Telegram, Discord

OpenAI Codex OAuth (headless Docker)

If you pick OpenAI Codex OAuth in the wizard, it opens a browser URL and tries to capture a callback on http://127.0.0.1:1455/auth/callback. In Docker or headless setups that callback can show a browser error. Copy the full redirect URL you land on and paste it back into the wizard to finish auth.

Health check

docker compose exec coderclaw-gateway node dist/index.js health --token "$CODERCLAW_GATEWAY_TOKEN"

E2E smoke test (Docker)

scripts/e2e/onboard-docker.sh

QR import smoke test (Docker)

pnpm test:docker:qr

Notes

Agent Sandbox (host gateway + Docker tools)

Deep dive: Sandboxing

What it does

When agents.defaults.sandbox is enabled, non-main sessions run tools inside a Docker container. The gateway stays on your host, but the tool execution is isolated:

Warning: scope: "shared" disables cross-session isolation. All sessions share one container and one workspace.

Per-agent sandbox profiles (multi-agent)

If you use multi-agent routing, each agent can override sandbox + tool settings: agents.list[].sandbox and agents.list[].tools (plus agents.list[].tools.sandbox.tools). This lets you run mixed access levels in one gateway:

See Multi-Agent Sandbox & Tools for examples, precedence, and troubleshooting.

Default behavior

Enable sandboxing

If you plan to install packages in setupCommand, note:

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared (agent is default)
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.coderclaw/sandboxes",
        docker: {
          image: "coderclaw-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: "coderclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
        },
        prune: {
          idleHours: 24, // 0 disables idle pruning
          maxAgeDays: 7, // 0 disables max-age pruning
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

Hardening knobs live under agents.defaults.sandbox.docker: network, user, pidsLimit, memory, memorySwap, cpus, ulimits, seccompProfile, apparmorProfile, dns, extraHosts.

Multi-agent: override agents.defaults.sandbox.{docker,browser,prune}.* per agent via agents.list[].sandbox.{docker,browser,prune}.* (ignored when agents.defaults.sandbox.scope / agents.list[].sandbox.scope is "shared").

Build the default sandbox image

scripts/sandbox-setup.sh

This builds coderclaw-sandbox:bookworm-slim using Dockerfile.sandbox.

Sandbox common image (optional)

If you want a sandbox image with common build tooling (Node, Go, Rust, etc.), build the common image:

scripts/sandbox-common-setup.sh

This builds coderclaw-sandbox-common:bookworm-slim. To use it:

{
  agents: {
    defaults: {
      sandbox: { docker: { image: "coderclaw-sandbox-common:bookworm-slim" } },
    },
  },
}

Sandbox browser image

To run the browser tool inside the sandbox, build the browser image:

scripts/sandbox-browser-setup.sh

This builds coderclaw-sandbox-browser:bookworm-slim using Dockerfile.sandbox-browser. The container runs Chromium with CDP enabled and an optional noVNC observer (headful via Xvfb).

Notes:

Use config:

{
  agents: {
    defaults: {
      sandbox: {
        browser: { enabled: true },
      },
    },
  },
}

Custom browser image:

{
  agents: {
    defaults: {
      sandbox: { browser: { image: "my-coderclaw-browser" } },
    },
  },
}

When enabled, the agent receives:

Remember: if you use an allowlist for tools, add browser (and remove it from deny) or the tool remains blocked. Prune rules (agents.defaults.sandbox.prune) apply to browser containers too.

Custom sandbox image

Build your own image and point config to it:

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

{
  agents: {
    defaults: {
      sandbox: { docker: { image: "my-coderclaw-sbx" } },
    },
  },
}

Tool policy (allow/deny)

Pruning strategy

Two knobs:

Example:

Security notes

Troubleshooting

This site is open source. Improve this page.