Docker & Containerization
Relevant source files
The following files were used as context for generating this wiki page:
Docker and containerization are core components of the Clawdbot infrastructure, primarily used to provide a secure, isolated runtime environment for agents and for end-to-end (E2E) testing. By leveraging Docker, Clawdbot ensures that agents execute in a sandboxed runtime, preventing direct access to the host system unless explicitly permitted. This containerized approach also facilitates consistent testing environments for plugins and system diagnostic tools.
Sources: src/agents/system-prompt.ts:257-260, scripts/e2e/plugins-docker.sh:1-5
Agent Sandboxing & Runtime
Clawdbot utilizes Docker to create a sandboxed runtime for its agents. When an agent is executed in this mode, all tool executions occur within a Docker container. This isolation is a security measure designed to protect the host environment from potentially unsafe operations performed by AI agents.
Sandbox Policy and Capabilities
The system prompt explicitly informs agents of their sandboxed status and the resulting policy restrictions. Sub-agents inherit this sandboxed status and are generally restricted from host access.
The diagram shows how the main agent routes tool calls through a Docker sandbox when enabled, and how sub-agents are restricted to the same containerized environment.
Sources: src/agents/system-prompt.ts:257-310
Host Browser Control
While agents are sandboxed, the system can be configured to allow or block control of the host's browser. Specific URLs can be provided to allow the agent to observe or control a browser instance through noVNC or dedicated control URLs.
| Sandbox Parameter | Description |
|---|---|
workspaceDir | The path to the workspace inside the container. |
workspaceAccess | Access level (none, ro, rw) for the agent's workspace mount. |
browserControlUrl | URL for the agent to control the sandbox browser. |
browserNoVncUrl | URL for observing the browser via noVNC. |
hostBrowserAllowed | Boolean indicating if the host browser can be controlled. |
Sources: src/agents/system-prompt.ts:265-290
Setup and Configuration
The project includes specialized logic for preparing the Docker environment. The system generates a .env file and passes build arguments to Docker to ensure the container is provisioned with necessary system packages.
Environment Variable Plumbing
The setup process (often tested via docker-setup.sh mocks) handles several critical environment variables that determine the container's capabilities.
| Variable | Usage |
|---|---|
CLAWDBOT_DOCKER_APT_PACKAGES | List of Linux packages (e.g., ffmpeg, build-essential) to install during build. |
CLAWDBOT_GATEWAY_TOKEN | Authentication token for the gateway service within the container. |
CLAWDBOT_CONFIG_DIR | Path to the configuration directory mounted in the container. |
CLAWDBOT_EXTRA_MOUNTS | Additional host volumes to be mounted into the Docker instance. |
Sources: src/docker-setup.test.ts:92-120
Docker Compose Services
Clawdbot typically orchestrates its environment using two primary services:
- clawdbot-gateway: The core service running the gateway process.
- clawdbot-cli: The command-line interface service used for interacting with the gateway.
Sources: src/docker-setup.test.ts:133-135
Testing Infrastructure
Docker is extensively used in the Clawdbot CI/CD pipeline for End-to-End (E2E) testing. This ensures that features like plugin loading and system repairs function correctly across different installation variants (e.g., global npm install vs. local git checkout).
Plugin E2E Testing
The plugins-docker.sh script builds a dedicated Docker image (clawdbot-plugins-e2e) to test the lifecycle of plugins. This includes:
- Registering tools and gateway methods.
- Installing plugins from
.tgztarballs. - Loading plugins from local folders and npm specs (
file:).
The sequence shows the automated build and verification process for plugin functionality within a clean Docker environment.
Sources: scripts/e2e/plugins-docker.sh:1-150
Diagnostic and Repair Testing
Docker environments are used to verify the "doctor" command, which repairs system installations. The doctor-install-switch-docker.sh script simulates switching between an npm-based installation and a git-based installation, verifying that the ExecStart entrypoint in systemd unit files is correctly updated by the repair logic.
# Example logic for asserting entrypoints in Docker E2E
assert_entrypoint() {
local unit_path="$1"
local expected="$2"
exec_line=$(grep -m1 "^ExecStart=" "$unit_path" || true)
entrypoint=$(echo "$exec_line" | awk "{print \$2}")
if [ "$entrypoint" != "$expected" ]; then
exit 1
fi
}
Sources: scripts/e2e/doctor-install-switch-docker.sh:84-100
Summary
Clawdbot integrates Docker to provide a secure, sandboxed execution environment for AI agents and a robust framework for automated testing. By utilizing docker-compose and custom setup scripts, the project manages complex dependencies and environment variables, ensuring that both the runtime and the developer tools remain stable and isolated from the host machine. Docker serves as the primary barrier for security in agent tool execution and the standard for verifying plugin and system-level repairs.