Dockerize Claude Code with a One‑Click Script: Install and Switch Proxies in 2 Minutes

Why containerize Claude Code

Running Claude Code inside Docker isolates it to the mounted project folder, preventing it from scanning the whole host filesystem. Four concrete benefits are:

Enable bypassPermissions (no‑confirm mode) – the container limits access to only the mounted directory, so accidental data exposure is confined to the project.

Reproducible environment – Node, global packages and environment variables are packaged in the image; every machine pulls the same image and behaves identically.

Separate configurations for different proxies – each proxy (official, MiniMax, Zhipu) uses its own profile file; a fresh container starts clean and loads the selected profile without cross‑contamination.

Neutral, non‑root runtime – the container runs as a regular user with default locale and timezone, avoiding personal host settings.

Typical workflow differences (direct install vs. Docker) are:

New machine setup : direct install requires Node, global packages, many env vars; Docker requires a single script download and setting CC_IMAGE.

Bypass permissions : direct install gives Claude full host access; Docker restricts it to the mounted folder.

Switching accounts/proxies : direct install needs manual env‑var changes; Docker uses CC_PROFILE=<name> before the command.

Upgrading Claude Code : each host upgrades separately; Docker upgrades by pulling the latest image.

Multi‑machine consistency : manual per‑machine updates vs. identical behavior from a shared image.

What is cca

cca

is a standalone launch script that requires no project files. After placing it in PATH>, running <code>cca performs four actions:

Checks whether the Docker image defined by CC_IMAGE exists; if not, it runs docker pull to download it.

Mounts the current working directory into the container as /workspace, so Claude edits the real host files.

Creates a Docker volume to persist login state and chat history, then loads the configuration specified by CC_PROFILE.

On first run, writes a default configuration (Chinese UI, dark theme, bypassPermissions) to ~/.config/cca/seed.json.

The image includes Node 24, Python 3, OpenJDK 17 and common CLI tools, sufficient for Claude to run code and tests. Teams can bake shared Skills and MCP into the image by editing the Dockerfile.

Installation (one command per machine)

# Download the launch script to PATH
mkdir -p ~/.local/bin && curl -fsSL \
  https://raw.githubusercontent.com/liuy-byte/claude-code-docker/main/cca \
  -o ~/.local/bin/cca && chmod +x ~/.local/bin/cca

Set the image to use (you can fork the repo or use the provided Alibaba Cloud image):

# Add to ~/.zshrc for permanent effect
export CC_IMAGE=registry.cn-hangzhou.aliyuncs.com/bjqgkjyxgs/claude-code:latest

After these steps the new computer is ready.

Upgrading Claude Code

The version is baked into the Docker image; pulling the latest image upgrades everything:

docker pull registry.cn-hangzhou.aliyuncs.com/bjqgkjyxgs/claude-code:latest

Subsequent cca invocations use the new version.

Daily usage

# Change to your project directory (mounted into the container)
cd /your/project
# Run with default official account (first run requires login)
cca
# Run a single task without entering the chat UI
cca -p "Translate README to English"
# Open an interactive shell inside the container
cca bash

Switch projects : change directory then run cca; changes are written to the host files.

First login (official account) : the terminal prints a link; open it in a browser, authorize, paste the returned code back; the login state is saved in a Docker volume.

The default configuration includes bypassPermissions . To disable no‑confirm mode, edit ~/.config/cca/seed.json and replace the setting.

Third‑party proxies (one profile per provider)

Each proxy requires a profile file ~/.config/cca/<name>.env. The repository provides a template; generate it with:

# Generate a profile for Zhipu (glm)
cca init glm   # creates ~/.config/cca/glm.env
# Or fill the key in one step
CC_KEY=YOUR_KEY cca init glm

Run with a prefix to select the profile: CC_PROFILE=glm cca # uses Zhipu Each profile contains four fields: ANTHROPIC_BASE_URL – proxy endpoint. ANTHROPIC_AUTH_TOKEN – API key. ANTHROPIC_DEFAULT_*_MODEL – model name for the proxy. HTTP_PROXY / HTTPS_PROXY – optional network proxy.

The real key lives only in ~/.config/cca/ on the host; the repository contains only .example templates and a .gitignore that excludes .env files, preventing accidental commits.

Running multiple providers simultaneously

Login state and chat history for each provider are stored in separate Docker volumes, allowing side‑by‑side usage:

# Official account
cca
# Zhipu (alias defined as CC_PROFILE=glm cca)
ccg
# MiniMax (alias defined as CC_PROFILE=minimax cca)
ccm

Define convenient aliases in ~/.zshrc:

echo "alias ccg='CC_PROFILE=glm cca'" >> ~/.zshrc
echo "alias ccm='CC_PROFILE=minimax cca'" >> ~/.zshrc
source ~/.zshrc

Trade‑offs and limitations

Docker must be installed on the host.

The first pull downloads a several‑hundred‑megabyte image.

Accessing host services from inside the container requires using host.docker.internal (not 127.0.0.1).

On macOS, container file I/O is slightly slower than native access.

For occasional manual use the overhead may not be worth it, but for long‑running automated tasks (batch jobs, no‑confirm mode) the isolation and reproducibility outweigh the costs.

Related links

Project repository: https://github.com/liuy-byte/claude-code-docker Official Claude Code documentation:

https://docs.anthropic.com/en/docs/claude-code