Claude Container

A portable, containerized environment for running Claude Code from anywhere on your system

Why?

Because it just feels better with protection.

Features

• 🐳 Fully containerized - No local installation required (except Docker)
• 📁 Directory mounting - Automatically mounts your current working directory
• ⚙️ Config preservation - Uses your existing ~/.claude.json configuration
• 💾 Session persistence - Claude settings, history, and conversations persist across sessions; automatically resumes where you left off
• 🛠️ Pre-configured - Includes Node.js, git, bash, and vim
• 🔧 Per-project customization - Add tools or auth logic per repo via .claude-container/
• 🚀 Portable - Run from any directory with a single command

Quick Start

# Clone the repository
git clone <your-repo-url>
cd claude-container

# Run the installer
./install.sh

# Start using it from any directory
cd ~/my-project
claude-container

Installation

Prerequisites

• Docker Desktop (or Docker Engine)
• ANTHROPIC_API_KEY set in your environment or ~/.zshrc

Automated Installation (Recommended)

Run the installer script which will handle everything for you:

./install.sh

The installer will:

• Check if Docker is running
• Build the Docker image if needed
• Install the wrapper script (system-wide or user-local)
• Set up permissions automatically

Manual Installation

Click to expand manual installation steps

1. Build the Docker Image

docker build -f Dockerfile.utility -t claude-container:latest .

Or use the justfile:

just build

2. Install the Wrapper Script

System-wide (requires sudo):

sudo cp claude-container /usr/local/bin/
sudo chmod +x /usr/local/bin/claude-container

User-local (no sudo):

mkdir -p ~/bin
cp claude-container ~/bin/
chmod +x ~/bin/claude-container
export PATH="$HOME/bin:$PATH"  # Add to ~/.bashrc or ~/.zshrc

Verify Installation

claude-container version

Usage

Navigate to any project directory and run:

claude-container

This launches a Docker container with:

• Your current directory mounted at /<dirname>
• Your ~/.claude.json configuration loaded
• Your Claude home (~/.claude-container/claude-home/) mounted for session persistence
• Claude Code CLI automatically started

Claude Code will start immediately, resuming your last conversation if one exists. When you're done, exit Claude Code and the container will be automatically removed.

Console Mode

To drop into a shell instead of starting Claude:

claude-container console

Flags

Flag	Description
--no-docker-extension	Skip .claude-container/Dockerfile and run the base claude-container:latest image directly
--base-image <image>	Use a fully custom local image instead of claude-container:latest, also skips .claude-container/Dockerfile

Examples:

# Skip per-project Dockerfile customization
claude-container --no-docker-extension

# Use a completely different image
claude-container --base-image my-custom-image:latest

# Drop into a shell with a custom image
claude-container --base-image my-custom-image:latest console

Per-Project Customization

You can customize the container on a per-repo basis by creating a .claude-container/ directory in your project.

Adding Tools (.claude-container/Dockerfile)

Create a Dockerfile that extends the base image:

FROM claude-container:latest

USER root

RUN apt-get update && apt-get install -y --no-install-recommends \
    golang-go python3 your-tool-here \
    && rm -rf /var/lib/apt/lists/*

USER claude

The first FROM line must be FROM claude-container:latest. The project image is built automatically and cached — it only rebuilds when the Dockerfile changes or the base image is updated.

Custom Auth (.claude-container/auth.sh)

For repos that need non-standard credentials (e.g. AWS Bedrock, custom tokens), create an executable .claude-container/auth.sh that prints KEY=VALUE pairs to stdout:

#!/bin/bash
echo "MY_TOKEN=abc123"
echo "MY_REGION=us-east-1"

chmod +x .claude-container/auth.sh

Each KEY=VALUE line is exported into the container's environment. Values never appear in docker inspect.

Example: AWS Bedrock

#!/bin/bash
PROFILE="my-sso-profile"
aws sso login --profile "$PROFILE" >&2
CREDS=$(aws configure export-credentials --profile "$PROFILE")
REGION=$(aws configure get region --profile "$PROFILE" 2>/dev/null || echo "us-east-1")
echo "AWS_ACCESS_KEY_ID=$(echo "$CREDS" | jq -r .AccessKeyId)"
echo "AWS_SECRET_ACCESS_KEY=$(echo "$CREDS" | jq -r .SecretAccessKey)"
echo "AWS_SESSION_TOKEN=$(echo "$CREDS" | jq -r .SessionToken)"
echo "AWS_DEFAULT_REGION=$REGION"
echo "CLAUDE_CODE_USE_BEDROCK=1"
echo "ANTHROPIC_DEFAULT_SONNET_MODEL=us.anthropic.claude-sonnet-4-6"

Rebuilding the Base Image

Use the justfile:

just build      # clean rebuild (--no-cache)
just rebuild    # rebuild using layer cache (faster)
just clean      # remove base image
just clean-all  # remove base image + all project images
just info       # show image details

Or manually:

docker build --no-cache -f Dockerfile.utility -t claude-container:latest .

Troubleshooting

Image not found error

Build the Docker image:

just build
# or
docker build -f Dockerfile.utility -t claude-container:latest .

Docker is not running

Start Docker Desktop or your Docker daemon before running the container.

Shell crashes after trust prompt

Try rebuilding with the latest version:

just build

Or check your config file permissions:

chmod 644 ~/.claude.json

Project Dockerfile fails to build

Ensure the first line is exactly:

FROM claude-container:latest

Also make sure the base image exists (docker image inspect claude-container:latest).

Project Dockerfile exists but tools are missing in the container

When ./claude-container runs, it will print Using project image: claude-container-proj-<name>:latest if your .claude-container/Dockerfile was detected. If you don't see this line, the project image was not picked up.

Common causes:

• Running a stale installed version of claude-container rather than the current ./claude-container from your repo — reinstall with ./install.sh
• The base image claude-container:latest doesn't exist — rebuild it with just build

To force a project image rebuild, delete the cached image and rerun:

docker rmi claude-container-proj-$(basename "$PWD" | tr '[:upper:]' '[:lower:]'):latest
claude-container

auth.sh not running

Make sure the script is executable:

chmod +x .claude-container/auth.sh

Permission issues with files

Ensure your Docker daemon is configured to map your user ID correctly. This is usually automatic on Docker Desktop.

Uninstallation

Run the automated uninstaller:

./uninstall.sh

Or manually:

# Remove the script
sudo rm /usr/local/bin/claude-container
# or
rm ~/bin/claude-container

# Remove the Docker image
docker rmi claude-container:latest

# Remove persisted Claude home
rm -rf ~/.claude-container/

Development

Creating a Release

Use the release script to create new versions:

./release.sh 1.0.1

This will:

1. Validate the version format (semantic versioning)
2. Update the version in claude-container
3. Create a git commit and tag
4. Prompt you to push changes

Push the release:

git push origin main --tags

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - See LICENSE file for details

Acknowledgments

Built for use with Claude Code by Anthropic.