claude-code-docker

Run Claude Code on Apple silicon

This Docker template is used to run Claude Code in an isolated container on Apple silicon Mac running macOS.

Containers are isolated from macOS host (only explicitly mounted directories are shared) and run as non-root user with all capabilities dropped. Claude Code data is persisted using claude-data volume.

If you wish to support this project, please star repo and consider a donation.

Setup

Step 1: clone repo

Heads-up: running git will trigger “Command Line Tools” install unless already installed.

$ git clone https://github.com/sunknudsen/claude-code-docker.git

$ cd claude-code-docker

Step 2: install Homebrew

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

$ echo 'export PATH=$PATH:/opt/homebrew/bin' >> ~/.zshrc && source ~/.zshrc

Step 3: disable Homebrew analytics

$ brew analytics off

Step 4: install dependencies

$ brew install colima docker docker-buildx

Step 5: configure Docker

$ mkdir -p $HOME/.docker

$ cp config.json.sample $HOME/.docker/config.json

Step 6: configure .env

Heads-up: setting CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 or DISABLE_TELEMETRY=1 environment variables may break Remote Control, see troubleshooting.

$ cp .env.sample .env

Step 7: start Colima

$ colima start \
  --cpu 2 \
  --disk 20 \
  --memory 4 \
  --profile claude-code

Step 8: cap build cache

Heads-up: Docker keeps build cache of every image build (including ephemeral session images) until pruned, so cache grows unbounded — cap makes BuildKit delete least recently used cache once total exceeds budget (images, containers and volumes are not affected). Applies on next Colima start.

Edit $HOME/.colima/claude-code/colima.yaml and replace docker: {} with following.

docker:
  builder:
    gc:
      enabled: true
      defaultKeepStorage: 5GB

Step 9: build claude-code image

Heads-up: use --target claude-node to include Node.js and --build-arg node_version=<version> to override default Node.js version.

Heads-up: npm prefix is set to ~/.local so npm install --global works as non-root user (globally installed packages do not persist when exiting container).

Heads-up: npm is configured to ignore lifecycle scripts (NPM_CONFIG_IGNORE_SCRIPTS=true) so npm install behaves like npm install --ignore-scripts (use npm install --ignore-scripts=false to run scripts when required).

$ docker build \
  --file Dockerfile \
  --tag claude-code:latest \
  .

Usage

Use Ctrl+D to exit container and stop Colima (unless another instance is running).

Run Claude Code

Heads-up: replace $HOME/Code/project with absolute path to project (more than one path can be specified).

Heads-up: use --publish <port>[:<port>] to publish container port to host and --no-stop to keep Colima running when exiting container.

Heads-up: to prevent leaking secrets to Claude, mounting directories that contain .env files is refused (.env.sample and .env.example are ignored).

Heads-up: use --allow-env <path|pattern> to bypass safeguard for .env files matching path (file or directory) or glob pattern (for example --allow-env "$HOME/Code/project/.env.*", patterns must be quoted and can be specified multiple times, and --allow-env "*" bypasses safeguard entirely).

$ utilities/run.sh $HOME/Code/project

Run Claude Code with session packages

Heads-up: replace gnupg with desired package (more than one package can be specified) and $HOME/Code/project with absolute path to project.

Heads-up: session packages are installed in ephemeral session image which is automatically removed when exiting container.

$ utilities/run.sh --package gnupg $HOME/Code/project

Upgrade

Step 1: upgrade dependencies

$ brew upgrade colima docker docker-buildx

Step 2: upgrade repo

$ git pull

Step 3: rebuild claude-code image

Heads-up: requires Colima to be running (see setup step 7).

Heads-up: rebuilding image will automatically upgrade Claude Code.

Heads-up: use --target claude-node if image was built with Node.js (see setup step 9).

$ docker build \
  --file Dockerfile \
  --no-cache \
  --tag claude-code:latest \
  .

Step 4: reclaim disk space

Heads-up: rebuilding image leaves previous image dangling and new build cache behind, see maintenance.

$ utilities/prune.sh

Maintenance

Reclaim disk space

Heads-up: can be run from another terminal while Claude Code is running (Colima is left running) or on its own (Colima is started and stopped).

Heads-up: claude-data volume is never touched — it holds Claude Code data and is detached (hence “unused” to Docker) whenever no container is running, so never run docker volume prune or docker system prune --volumes on claude-code profile.

Removes dangling images (previous claude-code images left behind by rebuilds) and build cache (recreated on demand by session image builds and claude-code image rebuilds), then releases freed space to macOS (Colima disk is sparse file, so space is only released once freed blocks are trimmed).

$ utilities/prune.sh

Extras

Create alias

Heads-up: replace $HOME/claude-code-docker with path to claude-code-docker folder and $HOME/Code/project with absolute path to project (more than one path can be specified).

Once alias has been created, one can run claude-code $HOME/Code/project to start Claude Code.

Use Ctrl+D to exit container and stop Colima (unless another instance is running).

$ cat << 'EOF' >> $HOME/.zshrc
# Set claude-code-docker alias
alias claude-code="$HOME/claude-code-docker/utilities/run.sh"
EOF

$ source $HOME/.zshrc