Sign inSign up

ychen94/mamba-claude

By ychen94

β€’Updated about 1 year ago

claude code and mamba https://github.com/YuChenSSR/claudecode-mamba

Image
Machine learning & AI
Developer tools
0

1.0K

ychen94/mamba-claude repository overview

⁠Mamba-Claude Docker Container

github URL: https://github.com/YuChenSSR/claudecode-mamba⁠

English | 中文⁠

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

Docker Hub Docker Pulls Architectures

⁠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)

# 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:

  1. Claude Configuration: ~/.claude-docker directory mapped to host (independent from host Claude)
  2. Mamba Environments: Stored in mamba-claude-envs Docker volume
  3. Mamba Package Cache: Stored in mamba-claude-pkgs Docker volume
  4. 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 .

⁠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

Tag summary

Content type

Image

Digest

sha256:e96a406e7…

Size

995.5 MB

Last updated

about 1 year ago

docker pull ychen94/mamba-claude