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.
316 lines
12 KiB
Markdown
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. |