Mamba-Claude Docker Container

English | 中文

A multi-architecture Docker container integrating Mamba (conda-forge) package manager and Claude Code CLI tool, providing a persistent development environment.

Features

🚀 Multi-architecture Support: Supports linux/amd64 and linux/arm64 architectures
🐍 Mamba Environment Management: Pre-installed Miniforge3 and Mamba for fast Python environment creation and management
🤖 Claude Code Integration: Built-in Claude Code CLI (ccc) for direct use in container
💾 Persistent Storage:
- Claude configuration /home/claude/.claude can be automatically mapped to host (~/.claude-docker) , persisted independently (separated from host Claude: ~/.claude). Edit configuration file on host, it will be immediately effective.
- Mamba environments and package cache persistence
- Automatic workspace directory mapping
🔧 Development Tools: Pre-installed git, vim, nano, build-essential, Node.js v20, and more
🎯 Convenient Scripts:
- build.sh - Multi-architecture image building
- run.sh - Temporary container execution
- run-persistent.sh - Persistent container management
📦 Pre-created Environments: Includes base and dev (Python 3.11) environments by default

🚀 Quick Start (30 seconds)

# change to your working directory on host machine
cd ~/projects/myproject

# Option 1: Temporary container (removed after exit)
docker run -it --rm \
  -v ~/.claude-docker:/home/claude/.claude \
  -v mamba-claude-envs:/opt/conda/envs \
  -v mamba-claude-pkgs:/opt/conda/pkgs \
  -v $(pwd):/workspace \
  -w /workspace \
  ychen94/mamba-claude:latest

# Option 2: Persistent container (keeps state)
docker run -it \
  --name mamba-claude \
  -v ~/.claude-docker:/home/claude/.claude \
  -v mamba-claude-envs:/opt/conda/envs \
  -v mamba-claude-pkgs:/opt/conda/pkgs \
  -v $(pwd):/workspace \
  -w /workspace \
  ychen94/mamba-claude:latest

# For persistent container, re-enter with:
# docker start -ai mamba-claude

# 2. Inside container, use Claude Code
ccc  # or use 'claude' command

# 3. (Optional) Configure Claude by editing ~/.claude-docker/settings.json on !host machine!
# Changes take effect immediately after restarting the Claude Code, without restarting the container.

# That's it! You're ready to go 🎉

Getting Started

Method 1: Using Docker Hub Image (Recommended)

# Pull image (automatically selects correct architecture)
docker pull ychen94/mamba-claude:latest

# Create configuration directory
mkdir -p ~/.claude-docker

# Run container in your working directory, the working directory will be automatically mapped to `/workspace` in the container
docker run -it --rm \
  -v ~/.claude-docker:/home/claude/.claude \
  -v $(pwd):/workspace \
  -w /workspace \
  ychen94/mamba-claude:latest

# Or download scripts for convenient use
curl -O https://raw.githubusercontent.com/YuChenSSR/claudecode-mamba/main/run-persistent.sh
chmod +x run-persistent.sh
./run-persistent.sh start

Method 2: Build from Source

1. Clone Repository

git clone https://github.com/YuChenSSR/claudecode-mamba.git
cd claudecode-mamba

2. Build Image

# Grant execute permissions to scripts
chmod +x build.sh run.sh run-persistent.sh

# Choose based on your system architecture:
# Apple Silicon Mac (M1/M2/M3/...)
./build.sh --load -p linux/arm64

# Intel Mac or Linux/Windows
./build.sh --load -p linux/amd64

# Or use docker-compose (requires manual build first)
docker-compose build

3. Initial Configuration

# Start persistent container
./run-persistent.sh start

# Enter container
./run-persistent.sh enter

# Configure Claude Code in container (first time)
ccc configure
# Follow prompts to enter configuration
# Configuration saved in ~/.claude-docker/ directory

# Or edit configuration file directly on host
# vim ~/.claude-docker/settings.json

# Exit container (container keeps running)
exit

4. Daily Usage

Using Persistent Container (Recommended)

# Start persistent container
./run-persistent.sh start

# Enter container for work
./run-persistent.sh enter

# Check container status
./run-persistent.sh status

# Stop container (preserves state)
./run-persistent.sh stop

# Restart container
./run-persistent.sh restart

# Remove container
./run-persistent.sh remove

Using Temporary Container

# Start container in current directory (removed on exit)
./run.sh

# Use specific mamba environment
./run.sh -e dev

# Mount specific directory as workspace
./run.sh -d ~/projects/myproject

# Run command directly
./run.sh python script.py
./run.sh ccc  # Start Claude Code

Detailed Usage

Using run-persistent.sh Script (Recommended)

run-persistent.sh provides persistent container management, suitable for long-term development:

# View help
./run-persistent.sh help

# Commands
start       # Start persistent container
stop        # Stop container (preserve state)
restart     # Restart container
enter       # Enter running container
status      # Show container status
logs        # View container logs
remove      # Remove container

# Workflow example
./run-persistent.sh start    # First start
./run-persistent.sh enter    # Enter for work
exit                         # Exit (container keeps running)
./run-persistent.sh enter    # Re-enter (state preserved)

Using run.sh Script (Temporary Tasks)

run.sh provides temporary containers, suitable for one-time tasks:

# View help
./run.sh -h

# Options
-e, --env ENV_NAME     # Activate specific mamba environment (default: base)
-d, --dir DIRECTORY    # Mount specific directory as workspace (default: current directory)
-n, --name NAME        # Container name (default: mamba-claude)
-r, --rebuild          # Rebuild image before running
-h, --help            # Show help information

Using docker-compose

# Start container
docker-compose up -d

# Enter container
docker-compose exec mamba-claude bash

# Stop container
docker-compose down

# Specify mamba environment
MAMBA_ENV=dev docker-compose up -d

Using Native Docker Commands

# Run container
docker run --rm -it \
  -v ~/.claude-docker:/home/claude/.claude \
  -v mamba-claude-envs:/opt/conda/envs \
  -v mamba-claude-pkgs:/opt/conda/pkgs \
  -v $(pwd):/workspace \
  -e MAMBA_ENV=dev \
  mamba-claude:latest

# Run in background
docker run -d --name mamba-claude \
  -v ~/.claude-docker:/home/claude/.claude \
  -v $(pwd):/workspace \
  mamba-claude:latest

# Enter running container
docker exec -it mamba-claude bash

Mamba Environment Management

Container comes with pre-installed Miniforge for convenient Python environment management:

# Create new environment
mamba create -n myenv python=3.11

# Activate environment
mamba activate myenv

# Install packages
mamba install numpy pandas scikit-learn

# List installed environments
mamba env list

# Export environment
mamba env export > environment.yml

# Create environment from file
mamba env create -f environment.yml

Environments are persisted in Docker volumes and remain available after container restart.

Claude Code Usage

Container includes integrated Claude Code CLI for direct use:

# Using persistent container (recommended)
./run-persistent.sh enter
ccc

# Or using temporary container
./run.sh ccc

Configuration Management

Claude configuration files are saved in ~/.claude-docker directory (independent from host's ~/.claude):

Host path: ~/.claude-docker/settings.json
Container path: /home/claude/.claude/settings.json
Configuration persists after container restart
Can edit configuration file directly on host for immediate effect

Updating Claude Code

Update Claude Code within container:

# Enter container
./run-persistent.sh enter

# Update using sudo
sudo npm install -g @anthropic-ai/claude-code@latest

🚀 Complete Workflow

Step 1: Clone and Prepare

git clone https://github.com/YuChenSSR/claudecode-mamba.git
cd claudecode-mamba
chmod +x build.sh run.sh run-persistent.sh

Step 2: Build Image (Choose Your Architecture)

# Apple Silicon Mac (M1/M2/M3)
./build.sh --load -p linux/arm64

# Intel Mac/Linux/Windows
./build.sh --load -p linux/amd64

Step 3: Initial Setup and Configuration

# Start persistent container
./run-persistent.sh start

# Enter container
./run-persistent.sh enter

# Configure Claude Code in container (if needed)
ccc configure
# Or edit configuration file directly on host: ~/.claude-docker/settings.json

# Create a Python environment (optional)
mamba create -n myenv python=3.11
mamba activate myenv

# Exit container (container keeps running)
exit

Step 4: Daily Usage

# Using persistent container (recommended)
cd ~/projects/myproject
~/claudecode-mamba/run-persistent.sh start
~/claudecode-mamba/run-persistent.sh enter

# Activate environment and use Claude Code in container
mamba activate myenv
ccc

Multi-Architecture Building

Use build.sh script to build multi-architecture images:

# Build and load locally (must specify single architecture)
./build.sh --load -p linux/arm64   # Apple Silicon
./build.sh --load -p linux/amd64   # Intel/AMD

# Build and push to Docker Hub (supports multi-architecture)
./build.sh --push -r docker.io/ychen94

# Build to cache only (no loading)
./build.sh -p linux/amd64,linux/arm64

Persistence Explanation

The following data persists after container restart:

Claude Configuration: ~/.claude-docker directory mapped to host (independent from host Claude)
Mamba Environments: Stored in mamba-claude-envs Docker volume
Mamba Package Cache: Stored in mamba-claude-pkgs Docker volume
Working Directory: Current or specified directory mapped to container's /workspace

Note: Container uses ~/.claude-docker as Claude configuration directory, completely separated from host's ~/.claude to avoid configuration conflicts.

Managing Docker Volumes

# View volumes
docker volume ls | grep mamba-claude

# Clean volumes (Warning: will delete all mamba environments)
docker volume rm mamba-claude-envs mamba-claude-pkgs

Common Use Cases

1. Data Science Projects

# Create data science environment
./run-persistent.sh enter
mamba create -n ds python=3.11 jupyter pandas numpy matplotlib
mamba activate ds
jupyter lab --ip=0.0.0.0 --no-browser

2. Web Development

# Run in project directory
cd ~/projects/webapp
./run-persistent.sh start
./run-persistent.sh enter
mamba create -n web python=3.11
mamba activate web
mamba install fastapi uvicorn
uvicorn main:app --reload --host 0.0.0.0

3. Machine Learning Experiments

# Use Claude Code for development assistance
./run-persistent.sh start
./run-persistent.sh enter
mamba activate dev
ccc  # Start Claude Code for programming assistance

Troubleshooting

Issue: Build Failure

# Clean Docker cache and retry
docker system prune -a
./build.sh --load

Issue: Permission Errors

# Ensure scripts have execute permissions
chmod +x build.sh run.sh run-persistent.sh

Issue: Claude Code Connection Issues

# Check Claude configuration files on host
ls -la ~/.claude-docker/

# Method 1: Edit configuration file directly
vim ~/.claude-docker/settings.json

# Method 2: Reconfigure in container
./run-persistent.sh enter
ccc configure

# Method 3: Configure using temporary container
./run.sh ccc configure

Issue: Updating Claude Code Permission Error

# Use sudo in container
./run-persistent.sh enter
sudo npm install -g @anthropic-ai/claude-code@latest

Issue: Missing Mamba Environments

# Check Docker volumes
docker volume inspect mamba-claude-envs

# Backup environments if needed
docker run --rm \
  -v mamba-claude-envs:/envs \
  -v $(pwd):/backup \
  alpine tar czf /backup/envs-backup.tar.gz -C /envs .

Issue: Need to change workspace of an existing persistent container

You cannot modify mounts or the default working directory of a running container. Stop and recreate the container with the new host path.

docker stop mamba-claude
docker rm mamba-claude

docker run -it \
  --name mamba-claude \
  -v ~/.claude-docker:/home/claude/.claude \
  -v mamba-claude-envs:/opt/conda/envs \
  -v mamba-claude-pkgs:/opt/conda/pkgs \
  -v /new/host/path:/workspace \
  -w /workspace \
  ychen94/mamba-claude:latest

Custom Configuration

Modify Default Python Environment

Edit Dockerfile to add more pre-installed environments:

RUN /opt/conda/bin/mamba create -n ml python=3.11 \
    numpy pandas scikit-learn matplotlib -y && \
    /opt/conda/bin/mamba clean -a -y

Add More Tools

Add required packages in the apt-get install section of Dockerfile:

RUN apt-get update && apt-get install -y \
    # ... existing packages ...
    postgresql-client \
    redis-tools \
    htop \
    && rm -rf /var/lib/apt/lists/*

Contributing

Issues and Pull Requests are welcome!

License

MIT License

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.gitignore		.gitignore
DOCKERHUB.md		DOCKERHUB.md
DOCKERHUB.zh.md		DOCKERHUB.zh.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
README.zh.md		README.zh.md
build.sh		build.sh
docker-compose.yml		docker-compose.yml
push-dockerhub.sh		push-dockerhub.sh
quick-start.sh		quick-start.sh
run-persistent.sh		run-persistent.sh
run.sh		run.sh

License

YuChenSSR/claudecode-mamba

Folders and files

Latest commit

History

Repository files navigation

Mamba-Claude Docker Container

Features

🚀 Quick Start (30 seconds)

Getting Started

Method 1: Using Docker Hub Image (Recommended)

Method 2: Build from Source

1. Clone Repository

2. Build Image

3. Initial Configuration

4. Daily Usage

Using Persistent Container (Recommended)

Using Temporary Container

Detailed Usage

Using run-persistent.sh Script (Recommended)

Using run.sh Script (Temporary Tasks)

Using docker-compose

Using Native Docker Commands

Mamba Environment Management

Claude Code Usage

Configuration Management

Updating Claude Code

🚀 Complete Workflow

Step 1: Clone and Prepare

Step 2: Build Image (Choose Your Architecture)

Step 3: Initial Setup and Configuration

Step 4: Daily Usage

Multi-Architecture Building

Persistence Explanation

Managing Docker Volumes

Common Use Cases

1. Data Science Projects

2. Web Development

3. Machine Learning Experiments

Troubleshooting

Issue: Build Failure

Issue: Permission Errors

Issue: Claude Code Connection Issues

Issue: Updating Claude Code Permission Error

Issue: Missing Mamba Environments

Issue: Need to change workspace of an existing persistent container

Custom Configuration

Modify Default Python Environment

Add More Tools

Contributing

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages