dclaude

Run Claude Code CLI in Docker - no local installation needed. Full MCP support, persistent sessions, and seamless host integration.

Why dclaude?

Claude Code CLI is powerful, but installing it locally means:

• Node.js version conflicts
• Global npm packages cluttering your system
• MCP servers needing specific Python/Node setups
• Different behavior across machines

dclaude solves this by running Claude in a container that feels native:

• Your files appear at the same paths (no /app or /workspace confusion)
• Docker commands work (socket is mounted)
• SSH keys and git config just work
• Homebrew included - easy migration from local macOS setup
• Works on Linux, macOS, and Windows
• Safer --dangerously-skip-permissions - container isolation means Claude can only access your project, not your whole system

Quick Start

Install via NPM (Recommended)

npm install -g @alanbem/dclaude
dclaude

Install from source

# Clone and install
git clone https://github.com/alanbem/dclaude.git ~/tools/dclaude
sudo ln -s ~/tools/dclaude/dclaude /usr/local/bin/dclaude

# Run (pulls image from Docker Hub automatically)
dclaude

Basic Usage

dclaude passes all arguments directly to Claude CLI - use it exactly as you would use claude:

# Start Claude interactively
dclaude

# Run with a prompt
dclaude "fix the bug in main.js"

# All Claude CLI flags work
dclaude --version
dclaude -p "explain this code"
dclaude --model sonnet
dclaude --resume

# Execute commands in the container
dclaude exec npm install
dclaude exec brew install ripgrep

How It Works

dclaude creates a container that mirrors your host environment:

1. Path Mirroring: Your current directory is mounted at the same path

   • On host: /Users/alice/projects/myapp
   • In container: /Users/alice/projects/myapp
   • All your file paths just work

2. Docker Access: The Docker socket is mounted, so Claude can build images, run containers, and manage compose stacks

3. Persistent Sessions: Containers persist by default - installed tools and configuration survive across sessions

4. Smart Networking: Auto-detects whether host networking is available for localhost access

Persistent vs Ephemeral Containers

Persistent (default) - Container survives between sessions:

dclaude                           # Uses existing container or creates new one
dclaude exec brew install fd      # Install tools - they persist
dclaude exec                      # Open a shell in the container

Ephemeral - Fresh container each time:

DCLAUDE_RM=true dclaude          # Container removed after exit

Use persistent for development (faster startup, tools persist). Use ephemeral for CI/CD or when you want a clean slate.

Features

SSH Authentication

dclaude automatically handles SSH for git operations:

# Auto-detect best method (default)
dclaude

# Force SSH agent forwarding (most secure)
DCLAUDE_GIT_AUTH=agent-forwarding dclaude

# Mount ~/.ssh directory (most compatible)
DCLAUDE_GIT_AUTH=key-mount dclaude

Make sure your SSH key is loaded: ssh-add -l

Homebrew Support

Install tools that persist across sessions:

dclaude exec brew install ripgrep fd bat jq
dclaude exec brew install node@20 [email protected]

GitHub CLI

Authenticate once, use everywhere:

dclaude gh                        # Interactive GitHub login
dclaude exec gh pr list           # Use gh commands

SSH Server for IDEs

Connect JetBrains Gateway, VS Code Remote, or any SSH client:

dclaude ssh                       # Start SSH server, shows port
# Connect: ssh claude@localhost -p <port>
# Password: claude

Chrome DevTools Integration

Control Chrome via MCP for browser automation:

dclaude chrome                    # Launch Chrome with DevTools
dclaude                           # Claude can now interact with the browser

Config Mounting

Mount your host configs for seamless tool integration:

DCLAUDE_MOUNT_CONFIGS=true dclaude

This mounts (read-only): .docker/, .gitconfig, .config/gh/, .npmrc

System Context

dclaude automatically tells Claude about its container environment so it can give better suggestions:

• Network mode - Whether localhost works or needs host.docker.internal
• Docker access - Whether Docker commands are available
• SSH auth method - How git authentication is configured
• Path mirroring - That file paths match the host

This helps Claude understand its environment without you explaining it. Disable if needed:

DCLAUDE_SYSTEM_CONTEXT=false dclaude

Environment Variables

Variable	Default	Description
DCLAUDE_RM	false	Remove container on exit (ephemeral mode)
DCLAUDE_TAG	latest	Docker image tag
DCLAUDE_NETWORK	auto	Network mode: auto, host, bridge
DCLAUDE_GIT_AUTH	auto	SSH auth: auto, agent-forwarding, key-mount, none
DCLAUDE_MOUNT_CONFIGS	false	Mount host config files
DCLAUDE_DEBUG	false	Enable debug output
DCLAUDE_QUIET	false	Suppress info messages
DCLAUDE_NO_UPDATE	false	Skip image update check
DCLAUDE_SYSTEM_CONTEXT	true	Inform Claude about container environment

Networking

dclaude auto-detects the best networking mode:

Host mode (when available):

• Direct localhost access to host services
• Works on: Linux, macOS with OrbStack/Docker Desktop beta, Windows with Docker Desktop beta

Bridge mode (fallback):

• Use host.docker.internal instead of localhost
• Standard Docker networking

Force a specific mode:

DCLAUDE_NETWORK=host dclaude
DCLAUDE_NETWORK=bridge dclaude

Platform Support

Platform	Status	Notes
Linux	Full support	Host networking available
macOS	Full support	Host networking with OrbStack or Docker Desktop beta
Windows	Full support	WSL2/Docker Desktop, host networking with beta features

What's Included

The container includes:

• Ubuntu 24.04 LTS base
• Claude Code CLI (latest)
• Node.js 20+, Python 3 with pip
• Homebrew/Linuxbrew for package management
• Docker CLI and Docker Compose
• Git, GitHub CLI (gh), common dev tools
• tmux for session management
• SSH server for IDE integration

Troubleshooting

Docker not running?

# Make sure Docker Desktop is running, or on Linux:
sudo systemctl start docker

Permission denied on Docker socket?

# Linux: Add yourself to the docker group
sudo usermod -aG docker $USER
# Then logout and login

Can't access localhost services?

# Check what network mode is being used
DCLAUDE_DEBUG=true dclaude

# Try forcing host mode
DCLAUDE_NETWORK=host dclaude

# Or use host.docker.internal in bridge mode

SSH keys not working?

# Make sure your key is loaded
ssh-add -l

# If empty, load your key
ssh-add ~/.ssh/id_ed25519

Installed tools disappearing?

# Make sure you're using persistent mode (default)
# If you set DCLAUDE_RM=true, tools won't persist
dclaude exec brew install <tool>  # This persists

Project Structure

.
├── dclaude                 # Launcher script (runs on host)
├── docker/
│   ├── Dockerfile          # Container image definition
│   ├── README.md           # Docker Hub documentation
│   ├── usr/local/bin/
│   │   └── docker-entrypoint.sh
│   └── home/claude/
│       └── .tmux.conf
├── .github/workflows/      # CI/CD (lint, scan, publish)
├── completions/            # Shell completions (bash, zsh)
├── Makefile                # Development commands
└── package.json            # NPM package config

Development

Want to modify dclaude? Build and test locally:

# Build local image
make build                    # Creates alanbem/dclaude:local

# Test
make test

# Use your local image
DCLAUDE_TAG=local dclaude

Contributing

Contributions welcome! Submit a Pull Request.

License

MIT - see LICENSE

Links

• Docker Hub
• npm
• Issues
• Discussions