claude-docker/README.md
Vishal Jain ddf35828e2 Simplify and clarify project documentation
Streamline documentation to focus on core functionality and conda
integration. Changes include:
- Clarify default design and conda environment usage
- Remove redundant workflow benefits section
- Simplify features list to focus on key capabilities
- Remove directory structure (available in repo)
- Add explicit push requirement in CLAUDE.md
- Update task completion requirements

This makes the documentation more focused and easier to understand while
emphasizing the project's integration with conda environments.
2025-06-18 14:58:59 +01:00

316 lines
12 KiB
Markdown

# Claude Docker
A Docker container setup for running Claude Code with full autonomous permissions and SMS notifications via Twilio MCP integration.
### CLAUDE.md Configuration
This codebase includes a custom `CLAUDE.md` template that configures Claude as an autonomous task executor. Located at `/templates/.claude/CLAUDE.md`, this file provides detailed instructions for how Claude should behave when executing tasks.
**Default Design:** The claude-docker agent expects a detailed `plan.md` file in your project root containing task specifications and which conda env to use. Claude will read this plan and execute it as faithfully as possible, documenting progress in `task_log.md`, send a text on completion if you set up your twilio credentials (optional). Simply tell it to make sure it has read the user scope claude md file and to execute.
## What This Does
- Runs Claude Code in an isolated Docker container with full autonomy.
- Integrates Twilio MCP for SMS notifications when tasks complete.
- Simple one-command setup and usage.
- Integrates existing conda environments to avoid custom env instructions in the Dockerfile.
- Documents work in a file `task_log.md`.
## Prerequisites
⚠️ **IMPORTANT**: Complete these steps BEFORE using claude-docker:
### 1. Claude Code Authentication (Required)
You must authenticate Claude Code on your host system first:
```bash
# Install Claude Code globally
npm install -g @anthropic-ai/claude-code
# Run and complete authentication
claude
# Verify authentication files exist
ls ~/.claude.json ~/.claude/
```
📖 **Full Claude Code Setup Guide**: https://docs.anthropic.com/en/docs/claude-code
### 2. Docker Installation (Required)
- **Docker Desktop**: https://docs.docker.com/get-docker/
- Ensure Docker daemon is running before proceeding
### 3. Git Configuration (Required)
Git configuration is automatically loaded from your host system during Docker build:
- Make sure you have configured git on your host system first:
```bash
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
```
- **Important**: Claude Docker will commit to your current branch - make sure you're on the correct branch before starting
### 4. Twilio Account (Optional - for SMS notifications)
If you want SMS notifications when tasks complete:
- Create free trial account: https://www.twilio.com/docs/usage/tutorials/how-to-use-your-free-trial-account
- Get your Account SID and Auth Token from the Twilio Console
- Get a phone number for sending SMS
### Why Pre-authentication?
The Docker container needs your existing Claude authentication to function. This approach:
- ✅ Uses your existing Claude subscription/API access
- ✅ Maintains secure credential handling
- ✅ Enables persistent authentication across container restarts
## Quick Start
```bash
# 1. Clone and enter directory
git clone https://github.com/VishalJ99/claude-docker.git
cd claude-docker
# 2. Setup environment
cp .env.example .env
nano .env # Add your API keys (see below)
# 3. Install
./scripts/install.sh
# 4. Run from any project
cd ~/your-project
claude-docker
```
### Environment Variables (.env)
```bash
# Optional - SMS notifications
TWILIO_ACCOUNT_SID=your_twilio_sid
TWILIO_AUTH_TOKEN=your_twilio_auth_token
TWILIO_FROM_NUMBER=+1234567890
TWILIO_TO_NUMBER=+0987654321
# Optional - Custom conda paths
CONDA_PREFIX=/path/to/your/conda
CONDA_EXTRA_DIRS="/path/to/envs /path/to/pkgs"
# Optional - System packages
SYSTEM_PACKAGES="libopenslide0 libgdal-dev"
```
⚠️ **Security Note**: Credentials are baked into the Docker image. Keep your image secure!
## Usage Patterns
### One-Time Setup Per Project
For the best experience, run `claude-docker` once per project and leave it running:
1. **Start Claude Docker:**
```bash
cd your-project
claude-docker
```
2. **Detach from the session (keep it running):**
- **Mac/Linux**: `Ctrl + P`, then `Ctrl + Q`
- Hold Control key, press P, then Q while still holding Control
- Container keeps running in background
3. **Reattach when needed:**
```bash
docker ps # Find your container ID
docker attach claude-docker-session # Reattach to the session
```
4. **Stop when done with project:**
```bash
docker stop claude-docker-session
```
## Features
### 🤖 Full Autonomy
- Claude runs with `--dangerously-skip-permissions` for complete access
- Can read, write, execute, and modify any files in your project
- No permission prompts or restrictions
### 📱 SMS Notifications
- Automatic SMS via Twilio when Claude completes tasks
- Configurable via MCP integration
- Optional - works without if Twilio not configured
### 🐍 Conda Integration
- Has access to your conda envs so do not need to add build instructions to the Dockerfile
- Supports custom conda installations (ideal for academic/lab environments)
- Mounts conda directories to preserve original paths and configurations
### 🗂️ Context Persistence
- Maintains project-specific Claude configuration
- Persistent across container sessions
- Helps Claude remember project context
### 🔑 Authentication Persistence
- Login once, use forever - authentication tokens persist across sessions
- No need to re-authenticate every time you start claude-docker
- Credentials stored securely in `~/.claude-docker/claude-home`
- Automatic UID/GID mapping ensures perfect file permissions between host and container
### 📝 Task Execution Logging
- Generates `task_log.md` documenting agent's execution process
- Stores assumptions, insights, and challenges encountered
- Acts as a simple summary to quickly understand what the agent accomplished
### 🐳 Clean Environment
- Each session runs in fresh Docker container
- Only current working directory mounted (along with conda directories specified in `.env`).
## How It Works
1. **Wrapper Script**: `claude-docker.sh` handles container lifecycle
2. **Auto-Setup**: Creates `.claude` directory with proper config on first run
3. **MCP Integration**: Twilio MCP server runs alongside Claude Code
4. **Project Mounting**: Your project directory mounts to `/workspace`
5. **Clean Exit**: Container removes itself when Claude session ends
## How This Differs from Anthropic's DevContainer
We provide a different approach than [Anthropic's official .devcontainer](https://github.com/anthropics/claude-code/tree/main/.devcontainer), optimized for autonomous task execution:
### Key Advantages
**🐍 Seamless Conda Integration**
- **claude-docker**: Your existing conda environments work out-of-the-box - no setup needed per project
- **Anthropic**: Requires environment setup in each DevContainer's Dockerfile
**🧠 Custom Prompt Engineering**
- **claude-docker**: Includes carefully engineered CLAUDE.md prompts for agentic task execution
- **Anthropic**: Basic Claude Code functionality without task-specific optimization
**🔑 One-Time Authentication**
- **claude-docker**: Authenticate once, use forever across all projects
- **Anthropic**: Re-authenticate for each new DevContainer
**📱 Additional Features**
- **claude-docker**: Built-in Twilio MCP for SMS notifications on task completion
- **Anthropic**: No notification system included
### Feature Comparison
| Feature | claude-docker | Anthropic's DevContainer |
|---------|--------------|-------------------------|
| **IDE Support** | Any editor/IDE | VSCode-specific |
| **Authentication** | Once per machine, persists forever | Per-devcontainer setup |
| **Conda Environments** | Direct access to all host envs | Manual setup in Dockerfile |
| **Prompt Engineering** | Optimized CLAUDE.md for tasks | Standard behavior |
| **Network Access** | Full access (firewall coming soon) | Configurable firewall |
| **SMS Notifications** | Built-in Twilio MCP | Not available |
| **Permissions** | Auto (--dangerously-skip-permissions) | Auto (--dangerously-skip-permissions) |
### When to Use Each
**Use claude-docker for:**
- 🚀 Autonomous task execution with optimized prompts
- 🐍 Projects requiring conda environments without Docker setup
- 📱 Long-running tasks with SMS completion notifications
- 🔧 Quick start without per-project configuration
- 💻 Non-VSCode development environments
**Use Anthropic's DevContainer for:**
- 🔒 Network-restricted environments (domain whitelisting)
- 🆚 Teams standardizing on VSCode
- 🛡️ Projects requiring strict network isolation today
**Note**: Network firewall functionality similar to Anthropic's implementation is our next planned feature.
## Configuration
During build, the `.env` file from the claude-docker directory is baked into the image:
- Credentials are embedded at `/app/.env` inside the container
- No need to manage .env files in each project
- The image contains everything needed to run
The setup creates `~/.claude-docker/` in your home directory with:
- `claude-home/` - Persistent Claude authentication and settings
- `config/` - MCP server configuration
Each project gets:
- `.claude/settings.json` - Claude Code settings with MCP
- `.claude/CLAUDE.md` - Instructions for Claude behavior
### Rebuilding the Image
The Docker image is built only once when you first run `claude-docker`. To force a rebuild:
```bash
# Remove the existing image
docker rmi claude-docker:latest
# Next run of claude-docker will rebuild
claude-docker
```
Rebuild when you:
- Update your .env file with new credentials
- Update the Claude Docker repository
### Conda Configuration
For custom conda installations (common in academic/lab environments), add these to your `.env` file:
```bash
# Main conda installation
CONDA_PREFIX=/vol/lab/username/miniconda3
# Additional conda directories (space-separated)
CONDA_EXTRA_DIRS="/vol/lab/username/.conda/envs /vol/lab/username/conda_envs /vol/lab/username/.conda/pkgs /vol/lab/username/conda_pkgs"
```
**How it works:**
- `CONDA_PREFIX`: Mounts your conda installation to the same path in container
- `CONDA_EXTRA_DIRS`: Mounts additional directories and automatically configures conda
**Automatic Detection:**
- Paths containing `*env*` → Added to `CONDA_ENVS_DIRS` (conda environment search)
- Paths containing `*pkg*` → Added to `CONDA_PKGS_DIRS` (package cache search)
**Result:** All your conda environments and packages work exactly as they do on your host system.
### System Package Installation
For scientific computing packages that require system libraries, add them to your `.env` file:
```bash
# Install OpenSlide for medical imaging
SYSTEM_PACKAGES="libopenslide0"
# Install multiple packages (space-separated)
SYSTEM_PACKAGES="libopenslide0 libgdal-dev libproj-dev libopencv-dev"
```
**Note:** Adding system packages requires rebuilding the Docker image (`docker rmi claude-docker:latest`).
## Next Steps
**Phase 2 - Security Enhancements:**
- Network firewall to whitelist specific domains (similar to Anthropic's DevContainer)
- Shell history persistence between sessions
- Additional security features
## Attribution & Dependencies
### Core Dependencies
- **Claude Code**: Anthropic's official CLI - https://github.com/anthropics/claude-code
- **Twilio MCP Server**: SMS integration by @yiyang.1i - https://github.com/yiyang1i/sms-mcp-server
- **Docker**: Container runtime - https://www.docker.com/
### Inspiration & References
- Anthropic's DevContainer implementation: https://github.com/anthropics/claude-code/tree/main/.devcontainer
- MCP (Model Context Protocol): https://modelcontextprotocol.io/
### Created By
- **Repository**: https://github.com/VishalJ99/claude-docker
- **Author**: Vishal J (@VishalJ99)
## License
This project is open source. See the LICENSE file for details.