Claude Code Container (ccc)

Single command. Isolated environment. No setup required.

Features

• Per-project isolated containers
• Runs on Docker or Podman — auto-detect, Podman preferred when both are installed
• Host env vars, SSH keys, locale, timezone auto-forwarded
• Auto-cleanup on session exit
• mise tool version management (auto-detect mise.toml)
• Built-in Chromium for headless testing
• Auto-pull container image on first run

Installation

From npm (end users)

npm install -g claude-code-container

The postinstall hook builds the desktop UI binary automatically. Timing:

• First install: ~3 min (requires cargo and, on Linux, libwebkit2gtk-4.1)
• Incremental rebuilds: ~30 sec (cargo incremental compilation)
• If the UI build fails (e.g. missing cargo), the CLI still installs successfully and prints a warning with manual recovery steps
• The UI uses a debug binary to keep install time reasonable

From source (developers)

git clone <repo>
cd claude-code-container
npm install
npm run install:global          # prompts for sudo when writing /usr/local/bin

Do NOT use sudo npm run install:global — cargo/rustup refuse to run under sudo. The install script invokes sudo internally only for the /usr/local/bin writes. To uninstall: npm run uninstall:global.

For development setup, see CONTRIBUTING.md.

Quick Start

ccc                        # Run Claude in current project
ccc --continue             # Continue previous session
ccc shell                  # Open bash shell
ccc npm test               # Run arbitrary command

Commands

ccc                        # Run Claude
ccc shell                  # Open bash shell
ccc <command>              # Run command in container
ccc stop                   # Stop container
ccc rm                     # Remove container
ccc status                 # Show all containers
ccc doctor                 # Health check
ccc clean                  # Clean stopped containers/images
ccc runtime                # Print detected container runtime + flavor
ccc ui                     # Launch the desktop app (Tauri 2). Set CCC_DEV=1 for live reload.

Container Runtime (Docker or Podman)

ccc works with either Docker or Podman. At startup it detects which runtime is available and picks it automatically.

ccc runtime                # e.g. runtime=podman version=5.2.3 flavor=podman-rootless socket=...

Selection order (first hit wins):

1. --runtime <docker|podman> CLI flag
2. CCC_RUNTIME=docker|podman environment variable
3. podman on PATH → Podman
4. docker on PATH → Docker

Podman specifics handled automatically:

• Rootless Podman on Linux: --userns=keep-id is added so host UID maps to the container ccc user. No manual UID remapping needed.
• SELinux: bind mounts get the :Z relabel suffix when SELinux is enforcing. Gate via CCC_SELINUX_RELABEL=auto|force|off (default auto).
• podman machine (macOS/Windows): treated like Docker Desktop — host.docker.internal rewriting and the localhost proxy both apply.
• Podman socket: $XDG_RUNTIME_DIR/podman/podman.sock (rootless) or /run/podman/podman.sock (rootful) is substituted for /var/run/docker.sock on the host side; containers still see /var/run/docker.sock. Start it with systemctl --user start podman.socket if tools inside the container need to talk to the runtime. Override the path with CCC_RUNTIME_SOCKET=/custom/socket when needed.

If neither runtime is installed, ccc exits with a clear error.

Profiles

Switch between different Claude accounts or credential sets. Each profile gets its own ~/.claude directory and container, fully isolated.

ccc profile add work       # Create profile
ccc profile list           # List profiles
ccc profile rm work        # Remove profile

CCC_PROFILE=work ccc       # Run with profile

Profiles are for credential directory isolation only. For environment variables (API keys, backend URLs), use mise environments:

# mise.toml
[env]
ANTHROPIC_BASE_URL = "http://host.docker.internal:11434/v1"
ANTHROPIC_API_KEY = "dummy"

Worktree Workspaces

ccc @feature               # Create workspace + run Claude
ccc @feature --continue    # Continue in workspace
ccc @                      # List workspaces
ccc @feature rm            # Remove workspace

Each workspace has its own container and can run simultaneously.

SSH

SSH keys and agent are auto-mounted from host. No setup required.

Every local container invocation mounts the registered credential directories for all supported coding tools (Claude, Codex, Gemini, and OpenCode), regardless of which tool or shell command starts the container.

# If SSH isn't working:
ssh-add ~/.ssh/id_ed25519   # Add key to agent
ccc rm && ccc               # Recreate container

Environment Variables

Host env vars are auto-forwarded (except system vars like PATH, HOME).

For per-project env configuration (API keys, LLM backends), see mise environments guide.

For running a local LLM (llama.cpp) with ccc, see local LLM guide.

Contributing

See CONTRIBUTING.md for architecture, development setup, and release process.

License

MIT