Skip to main content

​
Docker (optional)

Docker is optional. Use it only if you want a containerized gateway or to run crocbot on a host without local installs.

​
Is Docker right for me?

  • Yes: you want an isolated, throwaway gateway environment or to run crocbot 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.
This guide covers:
  • Containerized Gateway (full crocbot in Docker)
  • Per-session Agent Sandbox (host gateway + Docker-isolated agent tools)
Sandboxing details: Sandboxing

​
Requirements

  • Docker Desktop (or Docker Engine) + Docker Compose v2
  • Node.js 22+ and pnpm (for building dist/ before Docker build)
  • Enough disk for images + logs

​
How the Dockerfile works

The Dockerfile is a simple runtime-only image. It copies the pre-built dist/, node_modules/, and static assets into a node:22-slim base. You must run pnpm build locally first — there is no build stage inside Docker.

​
Containerized Gateway (Docker Compose)

From repo root: 
# 1. Build the application
pnpm install
pnpm build

# 2. Build the Docker image
docker build -t crocbot:local .

# 3. Run onboarding
docker compose run --rm crocbot-cli onboard

# 4. Start the gateway
docker compose up -d crocbot-gateway
After it finishes:
  • Open http://127.0.0.1:18789/ in your browser.
  • Paste the token into the Control UI (Settings).
It writes config/workspace on the host:
  • ~/.crocbot/
  • ~/croc

​
Manual flow (compose)

pnpm build
docker build -t crocbot:local .
docker compose run --rm crocbot-cli onboard
docker compose up -d crocbot-gateway

​
Extra mounts (optional)

If you want to mount additional host directories into the containers, set CROCBOT_EXTRA_MOUNTS before running scripts/docker-setup.sh. This accepts a comma-separated list of Docker bind mounts and applies them to both crocbot-gateway and crocbot-cli by generating docker-compose.extra.yml. Example: 
export CROCBOT_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./scripts/docker-setup.sh
Notes:
  • Paths must be shared with Docker Desktop on macOS/Windows.
  • If you edit CROCBOT_EXTRA_MOUNTS, rerun scripts/docker-setup.sh to regenerate the extra compose file.
  • docker-compose.extra.yml is generated. Don’t hand-edit it.

​
Persist the entire container home (optional)

If you want /home/node to persist across container recreation, set a named volume via CROCBOT_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 CROCBOT_EXTRA_MOUNTS. Example: 
export CROCBOT_HOME_VOLUME="crocbot_home"
./scripts/docker-setup.sh
Notes:
  • If you change CROCBOT_HOME_VOLUME, rerun scripts/docker-setup.sh to regenerate the extra compose file.
  • The named volume persists until removed with docker volume rm <name>.

​
Channel setup (optional)

Use the CLI container to configure Telegram, then restart the gateway if needed. Telegram (bot token): 
docker compose run --rm crocbot-cli channels add --channel telegram --token "<token>"
Docs: Telegram

​
Health check

docker compose exec crocbot-gateway node dist/index.js health --token "$CROCBOT_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 (~/.crocbot/agents/<agentId>/sessions/).

​
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:
  • 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 (agents.defaults.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)
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:
  • Full access (personal agent)
  • Read-only tools + read-only workspace (family/work agent)
  • No filesystem/shell tools (public agent)
See Multi-Agent Sandbox & Tools for examples, precedence, and troubleshooting.

​
Default behavior

  • Image: crocbot-sandbox:bookworm-slim
  • One container per agent
  • Agent workspace access: workspaceAccess: "none" (default) uses ~/.crocbot/sandboxes
    • "ro" keeps the sandbox workspace at /workspace and mounts the agent workspace read-only at /agent (disables write/edit/apply_patch)
    • "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: exec, process, read, write, edit, sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
  • Default deny: browser, cron, gateway

​
Enable sandboxing

If you plan to install packages in setupCommand, note:
  • Default docker.network is "none" (no egress).
  • readOnlyRoot: true blocks package installs.
  • user must be root for apt-get (omit user or set user: "0:0"). crocbot auto-recreates containers when setupCommand (or docker config) changes unless the container was recently used (within ~5 minutes). Hot containers log a warning with the exact crocbot sandbox recreate ... command.
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared (agent is default)
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.crocbot/sandboxes",
        docker: {
          image: "crocbot-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: "crocbot-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", "cron", "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 crocbot-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 crocbot-sandbox-common:bookworm-slim. To use it: 
{
  agents: { defaults: { sandbox: { docker: { image: "crocbot-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 crocbot-sandbox-browser:bookworm-slim using Dockerfile.sandbox-browser. The container runs Chromium with CDP enabled and an optional noVNC observer (headful via Xvfb). Notes:
  • Headful (Xvfb) reduces bot blocking vs headless.
  • Headless can still be used by setting agents.defaults.sandbox.browser.headless=true.
  • No full desktop environment (GNOME) is needed; Xvfb provides the display.
Use config: 
{
  agents: {
    defaults: {
      sandbox: {
        browser: { enabled: true }
      }
    }
  }
}
Custom browser image: 
{
  agents: {
    defaults: {
      sandbox: { browser: { image: "my-crocbot-browser" } }
    }
  }
}
When enabled, the agent receives:
  • a sandbox browser control URL (for the browser tool)
  • a noVNC URL (if enabled and headless=false)
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-crocbot-sbx -f Dockerfile.sandbox .

{
  agents: {
    defaults: {
      sandbox: { docker: { image: "my-crocbot-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

Two knobs:
  • prune.idleHours: remove containers not used in X hours (0 = disable)
  • prune.maxAgeDays: remove containers older than X days (0 = disable)
Example:
  • Keep busy sessions but cap lifetime: idleHours: 24, maxAgeDays: 7
  • Never prune: idleHours: 0, maxAgeDays: 0

​
Security notes

  • Hard wall only applies to tools (exec/read/write/edit/apply_patch).
  • Host-only tools like browser/camera 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 agents.defaults.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).
  • Custom tools not found: crocbot runs commands with sh -lc (login shell), which sources /etc/profile and may reset PATH. Set docker.env.PATH to prepend your custom tool paths (e.g., /custom/bin:/usr/local/share/npm-global/bin), or add a script under /etc/profile.d/ in your Dockerfile.