Related Pages

Related topics: Docker Architecture and Deployment, Configuration, Customization, and Agent Integrations

Introduction and Getting Started

docker-claudebox is a containerized wrapper that packages the Claude CLI/agent into an isolated Docker image, allowing users to run Claude in a reproducible environment without polluting the host system. The project ships a small set of shell scripts and a Dockerfile that orchestrate installation, container lifecycle, and credential handling.

Purpose and Scope

The repository provides three primary entry points:

• install.sh — bootstraps a host by downloading the wrapper script into a known location (typically ~/.local/bin or a similar user-writable path) and ensuring the Docker image is available locally. Source: install.sh:1-80
• wrapper.sh — the day-to-day entry point invoked by the user; it constructs the docker run command, mounts required volumes, forwards arguments to the Claude CLI inside the container, and manages environment variables for authentication. Source: wrapper.sh:1-60
• README.md — documents prerequisites, supported platforms, and quickstart examples. Source: README.md:1-120

The scope is intentionally narrow: docker-claudebox does not modify Claude itself, nor does it ship model weights. It only handles the surrounding container plumbing so that running claude inside Docker is a single-command experience.

Prerequisites

Before installing, the host must satisfy a short checklist:

1. A working Docker daemon (Docker Engine or Docker Desktop) reachable by the user invoking the scripts. Source: README.md:30-45
2. A POSIX-compatible shell (bash or zsh) capable of sourcing the wrapper. Source: wrapper.sh:1-15
3. Sufficient disk space for the pulled image layer and any project workspaces that will be bind-mounted.
4. Network access on first run so the image can be pulled from the configured registry.

Installation Flow

The recommended one-line installer pulls install.sh from the repository and executes it. The script is idempotent: re-running it updates the local wrapper to the latest version without disturbing existing configuration files.

flowchart LR
    A[User runs install.sh] --> B{Curl/fetch latest wrapper.sh}
    B --> C[Place wrapper in PATH]
    C --> D{Docker image present?}
    D -- No --> E[docker pull image]
    D -- Yes --> F[Ready]
    E --> F[Ready]
    F --> G[User invokes wrapper.sh]
    G --> H[docker run with mounts + env]
    H --> I[Claude CLI inside container]

Source: install.sh:20-70

A typical first-run interaction looks like:

# Fetch and execute the installer
curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-claudebox/main/install.sh | bash

# Verify the wrapper is on PATH
which claudebox || which docker-claudebox

# Run Claude through the container
claudebox

Source: README.md:50-90

Day-to-Day Usage

After installation, the user rarely interacts with install.sh again. Instead, wrapper.sh becomes the primary surface. It accepts the same arguments as the underlying Claude CLI and forwards them verbatim, so existing muscle memory and scripts continue to work.

Key responsibilities of the wrapper include:

• Mounting the current working directory into the container so generated files appear on the host. Source: wrapper.sh:30-55
• Forwarding authentication-related environment variables (for example ANTHROPIC_API_KEY) without writing them to disk. Source: wrapper.sh:55-90
• Optionally mounting a persistent config directory so settings, history, and cache survive container recreation. Source: wrapper.sh:90-130
• Pulling the image lazily on first use if install.sh was skipped. Source: wrapper.sh:130-160

A minimal invocation passes through positional arguments:

claudebox "explain this codebase"
claudebox --resume
claudebox -p "refactor the parser"

Source: README.md:90-130

Versioning and the Latest Release

The project follows semantic versioning, and the current shipping version is v2.3.6 per the latest community-visible release. The CHANGELOG.md file records every release with the date, a summary of changes, and any migration notes. Source: CHANGELOG.md:1-40

When upgrading from a prior version, re-running install.sh is sufficient; it refreshes wrapper.sh and, if the image tag changed, instructs the user to pull the new image. Existing mounted configuration directories are preserved across upgrades. Source: CHANGELOG.md:40-80

Next Steps

Once the wrapper runs successfully, the most common follow-up actions are:

1. Configure persistent mounts for credentials and project caches (documented in the README). Source: README.md:130-180
2. Pin the image tag for reproducible environments instead of using :latest. Source: wrapper.sh:160-200
3. Review the CHANGELOG.md entry for v2.3.6 to learn about behavior changes introduced in the current release. Source: CHANGELOG.md:1-20

From here, deeper pages in this wiki cover volume and permission handling, network configuration, image customization, and troubleshooting.

Related Pages

Related topics: Configuration, Customization, and Agent Integrations, Docker Architecture and Deployment

Operating Modes and Interfaces

docker-claudebox exposes the Claude runtime through several distinct operating modes, each tailored to a different interaction style. The modes share a common core but present different surfaces: a terminal REPL, a Python module, an HTTP API, and a Telegram bot. The adapter layer normalizes how the underlying Claude engine is invoked regardless of the surface chosen. Source: claudebox/claudebox/__init__.py

Mode Taxonomy

The project documents four primary operating modes, each living under docs/modes/:

All four are first-class entry points into the same Claude engine; the differences live in transport, session lifecycle, and input/output formatting. Source: docs/modes/interactive.md, docs/modes/programmatic.md, docs/modes/api.md, docs/modes/telegram.md

Interactive Mode

The interactive mode is the canonical human-facing surface. It launches a terminal session where prompts are typed and responses streamed back in real time.

Key characteristics:

• Line-oriented input from stdin, token-streamed output to stdout
• Local session state (history, working context) retained for the lifetime of the process
• Suitable for exploratory use, debugging prompts, and ad-hoc queries

Source: docs/modes/interactive.md

Programmatic Mode

The programmatic mode exposes Claude as an importable Python component rather than as a process to spawn. Applications embed the claudebox package directly and call into it.

Key characteristics:

• Imported via claudebox (see package entry point)
• Synchronous or streaming call patterns, depending on the helper used
• Shares the same adapter contract used by the other modes, ensuring behavior parity

This mode is the recommended integration path for libraries and tools that need to embed Claude without IPC overhead. Source: claudebox/claudebox/__init__.py, docs/modes/programmatic.md

API Mode

The API mode exposes Claude over HTTP, turning the runtime into a network service. Clients send requests to defined endpoints and receive responses using standard web formats.

Key characteristics:

• Request/response semantics suitable for remote callers
• Decouples the Claude process from the client process, enabling horizontal scaling and multi-client access
• Reuses the adapter layer so that HTTP-level concerns (serialization, routing, error mapping) stay separated from model interaction

Source: docs/modes/api.md

Telegram Mode

The Telegram mode wraps Claude behind a chat-bot interface, forwarding user messages from Telegram to the Claude engine and streaming replies back to the chat.

Key characteristics:

• Driven by Telegram's bot update stream
• Maps chat identifiers to per-conversation context
• Useful for non-technical end users who interact through messaging clients rather than terminals or HTTP clients

Source: docs/modes/telegram.md

The Adapter Layer

Beneath all four modes sits the adapter layer defined in claudebox/claudebox/adapter.py. The adapter abstracts the Claude engine behind a stable interface so that each mode can speak to the engine uniformly.

Responsibilities attributed to the adapter:

• Normalizing prompt construction and response parsing across modes
• Isolating mode-agnostic Claude calls from transport-specific code
• Providing a single point of extension when adding new surfaces

flowchart LR
    User --> Interactive
    App[Application Code] --> Programmatic
    HTTP[HTTP Client] --> API
    TG[Telegram Client] --> Telegram
    Interactive --> Adapter
    Programmatic --> Adapter
    API --> Adapter
    Telegram --> Adapter
    Adapter --> Engine[Claude Engine]

Source: claudebox/claudebox/adapter.py, claudebox/claudebox/__init__.py

Choosing a Mode

Selection criteria distilled from the documentation:

• Choose interactive when a human is driving the session through a terminal.
• Choose programmatic when Claude is a dependency of another Python application.
• Choose API when clients are remote, language-agnostic, or service-oriented.
• Choose Telegram when the end user lives inside a chat platform.

Because the adapter layer mediates every mode, switching surfaces does not require re-implementing model interaction logic; only the transport-specific shell changes. Source: claudebox/claudebox/adapter.py, docs/modes/programmatic.md, docs/modes/api.md

Version Context

As of the latest release noted in community context (v2.3.6), the four documented modes remain the supported set of operating interfaces. New surfaces are expected to plug in through the adapter rather than by duplicating engine bindings. Source: claudebox/claudebox/__init__.py, claudebox/claudebox/adapter.py

Related Pages

Related topics: Introduction and Getting Started, Operating Modes and Interfaces

Configuration, Customization, and Agent Integrations

docker-claudebox is a containerized harness for Claude Code that exposes three coordinated layers of configuration: environment variables that steer runtime behavior, init scripts that patch Claude's settings and seed persistent data, and a customization model that layers workspace, user, and project-level assets on top of a base image. The current release line is v2.3.6 (Source: .env.example:1-1).

Layered Configuration Model

Configuration flows through three tiers that are merged on container start.

Source: docs/environment-variables.md:1-40

The init system is straightforward: scripts prefixed with two-digit numbers execute in ascending order, giving an idempotent boot sequence where later steps can rely on earlier ones (Source: claudebox/init.d/10-claude-json-patch.sh:1-15).

Environment Variables and Claude Flag Injection

The .env.example file documents every knob the harness understands, and the env-var docs explain how values are mapped into Claude CLI invocations (Source: .env.example:1-120). Notable variables include:

• CLAUDE_FLAGS — extra flags appended to every claude invocation, used to enable/disable features such as telemetry or MCP transports (Source: docs/environment-variables.md:5-25).
• WORKDIR, USER_UID, USER_GIN, USER_NAME — control how the host workspace is mounted and the in-container user is created (Source: .env.example:30-80).
• TIMEZONE — propagated so log timestamps and Claude session metadata align with host time (Source: .env.example:90-100).

The init patch script consumes these variables at runtime and writes the resolved JSON to ~/.claude.json, so users never edit Claude's settings file directly (Source: claudebox/init.d/10-claude-json-patch.sh:20-60).

CLAUDE.md and Skills Seeding

Two init scripts own the agent-context layer:

1. 20-workspace-claude-md.sh ensures a CLAUDE.md exists in the mounted workspace, copying a default if the user has not provided one. This guarantees Claude always has project context on first run (Source: claudebox/init.d/20-workspace-claude-md.sh:1-25).
2. 30-always-skills-seed.sh seeds the .claude/skills/always directory with skill files that should be loaded on every session, regardless of the active project (Source: claudebox/init.d/30-always-skills-seed.sh:1-30).

flowchart TD
    A[Container start] --> B[10-claude-json-patch.sh<br/>write ~/.claude.json]
    B --> C[20-workspace-claude-md.sh<br/>ensure CLAUDE.md]
    C --> D[30-always-skills-seed.sh<br/>seed skills/always]
    D --> E[claude CLI ready<br/>with merged config]

Customization Workflow

The docs/customization.md guide documents the recommended workflow for extending the harness without forking the image (Source: docs/customization.md:1-60).

Key patterns covered:

• Workspace-level CLAUDE.md — drop a file at the mount root; the init script preserves it instead of overwriting (Source: docs/customization.md:10-30).
• Always-on skills — files placed under .claude/skills/always/ are mirrored into the container by the seed script on every boot (Source: claudebox/init.d/30-always-skills-seed.sh:15-30).
• Claude JSON overrides — users can pre-populate ~/.claude.json on the host because the patch script merges rather than replaces when a managed key is absent (Source: claudebox/init.d/10-claude-json-patch.sh:35-50).

This design lets a single image serve very different agent topologies (single-session, multi-agent MCP, headless CI) purely through configuration, which is the primary extension surface as of v2.3.6.

Cross-References and Operational Notes

• For the full env-var surface, see Source: docs/environment-variables.md:1-40.
• For hands-on customization recipes, see Source: docs/customization.md:1-60.
• For the canonical variable list and defaults, see Source: .env.example:1-120.

The configuration model deliberately avoids imperative provisioning: there is no entrypoint script that mutates user files outside of ~/.claude.json and the seeded skills directory, which keeps upgrades idempotent across minor releases within the v2.x line.

Related Pages

Related topics: Introduction and Getting Started, Operating Modes and Interfaces

The following source files were used to generate this page:

• Dockerfile
• Dockerfile.full
• .dockerignore
• claudebox-entrypoint.sh
• claudebox/pyproject.toml
• Makefile

Docker Architecture and Deployment

Docker-claudebox ships as a containerized environment that wraps the Claude CLI agent together with its supporting Python package, system tooling, and runtime configuration. The deployment story is intentionally minimal: a single image, a deterministic entrypoint, and a Makefile-driven build pipeline that supports both a slim default image and an extended "full" variant for users who need additional tooling.

Image Variants and Layering Strategy

The repository provides two distinct Dockerfiles that share a common base philosophy but differ in tool density.

The default Dockerfile builds a streamlined image optimized for size and startup latency. It pins a specific Python base image, installs the runtime dependencies declared by the Python package, copies the claudebox Python source into the image, and sets the entrypoint to the bundled shell script. Source: Dockerfile:1-40

The Dockerfile.full extends the default image with additional developer tooling — typically shell utilities, build tools, and language runtimes that are not required by the core CLI but are commonly requested by operators running Claude inside the container. The full variant is layered on top of the default image so that the slim build remains the canonical reference. Source: Dockerfile.full:1-30

A .dockerignore file tightly scopes the build context so that local virtual environments, test artifacts, Git metadata, and editor files are never sent to the Docker daemon. This keeps image builds reproducible and prevents stale local state from leaking into a layer. Source: .dockerignore:1-20

Build Pipeline and the Makefile

The Makefile is the canonical interface for building, tagging, and running the image. It exposes targets that map directly to the two Dockerfile variants and abstracts Docker invocations so users do not need to remember long docker build commands.

Source: Makefile:1-60

Tagging is governed by the project's semver release process, and the latest published version is v2.3.6. The Makefile typically derives the image tag from a VERSION variable or git tag, ensuring that the image built locally matches the version referenced in release notes. Source: Makefile:1-15

Runtime Configuration and Entrypoint

The container's behavior at startup is governed by claudebox-entrypoint.sh, which is copied into the image and registered as the container's ENTRYPOINT. This script is responsible for:

1. Validating that required environment variables (such as Anthropic API credentials) are present.
2. Sourcing any user-supplied runtime configuration mounted into the container.
3. Executing the Claude CLI agent with the parameters passed through docker run.

Source: claudebox-entrypoint.sh:1-50

Because the entrypoint is a shell script rather than a compiled binary, operators can override it for debugging by passing an alternative command to docker run, for example docker run --rm -it docker-claudebox:latest /bin/bash to obtain an interactive shell inside the image.

Python Package and Dependency Surface

The Python package that provides the Claude CLI integration lives under claudebox/ and is described by pyproject.toml. This file declares the package metadata, the Python version constraint, runtime dependencies, and optional development dependencies (such as test runners and linters).

graph TD
    A[Dockerfile base image] --> B[Install system deps]
    B --> C[Copy claudebox/ sources]
    C --> D[Install via pyproject.toml]
    D --> E[Register entrypoint script]
    E --> F[Image: docker-claudebox]
    G[Dockerfile.full] --> H[Extend F with extra tools]
    H --> I[Image: docker-claudebox-full]

Source: claudebox/pyproject.toml:1-40

During the image build, Docker installs the package in a non-editable mode, so the container is self-contained and does not require the source tree at runtime. This is what enables the image to be distributed as a portable artifact without requiring a bind mount of the host repository.

Deployment Workflow

A typical deployment session follows this sequence:

1. Clone the repository and run make build to produce the default image.
2. Provide an Anthropic API key, either via an environment variable or a .env file passed to docker run.
3. Invoke make run (or docker run --rm -it docker-claudebox:latest) to start the Claude CLI inside the container.
4. For users who need the bundled development tooling, run make build-full followed by make run-full.

Source: Makefile:1-60

The architecture intentionally separates concerns: the Dockerfile and Dockerfile.full handle image construction, the pyproject.toml handles Python-level dependency resolution, the entrypoint script handles runtime concerns, and the Makefile ties these pieces together into a developer-friendly command surface. This separation makes it straightforward to upgrade individual layers — for example, bumping the Python base image or adding a new CLI dependency — without rewriting the entire deployment pipeline.

Versioning and Reproducibility

The latest published release, v2.3.6, is the authoritative reference for the behavior described above. Users who require reproducible builds should check out the git tag corresponding to this release prior to invoking make build, ensuring that the image they produce matches the documented semantics. The combination of a pinned base image, a locked pyproject.toml dependency list, and a versioned Makefile target yields a deployment that is reproducible across hosts and CI environments. Source: Makefile:1-15

Doramagic Pitfall Log

Found 9 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/psyb0t/docker-claudebox

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/psyb0t/docker-claudebox

3. Runtime risk: Runtime risk requires verification

• Severity: medium
• Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: packet_text.keyword_scan | https://github.com/psyb0t/docker-claudebox

4. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/psyb0t/docker-claudebox

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/psyb0t/docker-claudebox

6. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: No sandbox install has been executed yet; downstream must verify before user use.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.safety_notes | https://github.com/psyb0t/docker-claudebox

7. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/psyb0t/docker-claudebox

8. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/psyb0t/docker-claudebox

9. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/psyb0t/docker-claudebox

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using docker-claudebox with real data or production workflows.

• Configuration risk requires verification - GitHub / issue