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:

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

  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

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

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

   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:

   docker ps                           # Find your container ID
   docker attach claude-docker-session # Reattach to the session
   

4. Stop when done with project:

   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

🔑 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, 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:

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

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

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