{"id":37735073,"url":"https://github.com/alanbem/dclaude","last_synced_at":"2026-04-01T19:39:38.692Z","repository":{"id":332667825,"uuid":"1060132206","full_name":"alanbem/dclaude","owner":"alanbem","description":"Run Claude Code CLI in Docker - no local installation needed. Full MCP support, persistent sessions, and seamless host integration.","archived":false,"fork":false,"pushed_at":"2026-03-20T09:54:08.000Z","size":442,"stargazers_count":9,"open_issues_count":15,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-21T01:53:26.637Z","etag":null,"topics":["anthropic","claude","claude-code","cli","containerization","devtools","docker","mcp"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alanbem.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-19T12:37:19.000Z","updated_at":"2026-03-20T09:53:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/alanbem/dclaude","commit_stats":null,"previous_names":["alanbem/dclaude"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/alanbem/dclaude","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alanbem%2Fdclaude","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alanbem%2Fdclaude/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alanbem%2Fdclaude/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alanbem%2Fdclaude/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alanbem","download_url":"https://codeload.github.com/alanbem/dclaude/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alanbem%2Fdclaude/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291171,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anthropic","claude","claude-code","cli","containerization","devtools","docker","mcp"],"created_at":"2026-01-16T13:59:17.083Z","updated_at":"2026-04-01T19:39:38.683Z","avatar_url":"https://github.com/alanbem.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dclaude — Dockerized Claude Code\n\n[![CI/CD](https://github.com/alanbem/dclaude/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/alanbem/dclaude/actions/workflows/ci-cd.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Docker Pulls](https://img.shields.io/docker/pulls/alanbem/dclaude)](https://hub.docker.com/r/alanbem/dclaude)\n[![npm](https://img.shields.io/npm/v/@alanbem/dclaude)](https://www.npmjs.com/package/@alanbem/dclaude)\n\nRun Claude Code CLI in Docker — no local installation needed. Full MCP support, persistent sessions, and seamless host integration.\n\n## Why dclaude?\n\n**Claude Code CLI is powerful, but installing it locally means:**\n- MCP servers needing specific Python/Node setups\n- Different behavior across machines\n- Claude has access to your entire filesystem\n\n**dclaude solves this by running Claude in a container that feels native:**\n- **Safer `--dangerously-skip-permissions`** - container isolation means Claude can only access your project, not your whole system\n- Your files appear at the same paths (no `/app` or `/workspace` confusion)\n- Docker commands work (socket is mounted)\n- SSH keys and git config just work\n- Homebrew included - easy migration from local macOS setup\n- Works on Linux, macOS, and Windows\n\n## Quick Start\n\n\u003e **Prerequisite:** A Docker-compatible runtime such as [Docker Desktop](https://docs.docker.com/get-docker/), [OrbStack](https://orbstack.dev/), or [Colima](https://github.com/abiosoft/colima) must be installed and running.\n\n### Install via NPM (Recommended)\n\n```bash\nnpm install -g @alanbem/dclaude\ndclaude\n```\n\n### Install from source\n\n```bash\n# Clone and install\ngit clone https://github.com/alanbem/dclaude.git ~/tools/dclaude\nsudo ln -s ~/tools/dclaude/dclaude /usr/local/bin/dclaude\n\n# Run (pulls image from Docker Hub automatically)\ndclaude\n```\n\n\u003e **First run:** The Docker image (~1GB) is pulled automatically on first launch. You'll be prompted to authenticate with your Anthropic account.\n\n## Basic Usage\n\n**dclaude passes all arguments directly to Claude CLI** - use it exactly as you would use `claude`:\n\n```bash\n# Start Claude interactively\ndclaude\n\n# Run with a prompt\ndclaude \"fix the bug in main.js\"\n\n# All Claude CLI flags work\ndclaude --version\ndclaude -p \"explain this code\"\ndclaude --model sonnet\ndclaude --resume\n\n# Execute commands in the container\ndclaude exec npm install\ndclaude exec brew install ripgrep\n```\n\n## How It Works\n\ndclaude creates a container that mirrors your host environment:\n\n1. **Path Mirroring**: Your current directory is mounted at the *same path*\n   ```\n   Host:      /Users/alice/projects/myapp ──mount──\u003e Container: /Users/alice/projects/myapp\n   ```\n   No `/app` or `/workspace` confusion — all your file paths just work\n\n2. **Docker Access**: The Docker socket is mounted, so Claude can build images, run containers, and manage compose stacks\n\n3. **Persistent Sessions**: Containers persist by default - installed tools and configuration survive across sessions\n\n4. **Smart Networking**: Auto-detects whether host networking is available for localhost access\n\n## Persistent vs Ephemeral Containers\n\n**Persistent (default)** - Container survives between sessions:\n```bash\ndclaude                           # Uses existing container or creates new one\ndclaude exec brew install fd      # Install tools - they persist\ndclaude exec                      # Open a shell in the container\n```\n\n**Ephemeral** - Fresh container each time:\n```bash\nDCLAUDE_RM=true dclaude          # Container removed after exit\n```\n\nUse persistent for development (faster startup, tools persist). Use ephemeral for CI/CD or when you want a clean slate.\n\n## Features\n\n### SSH Authentication\n\ndclaude automatically handles SSH for git operations:\n\n```bash\n# Auto-detect best method (default)\ndclaude\n\n# Force SSH agent forwarding (most secure)\nDCLAUDE_GIT_AUTH=agent-forwarding dclaude\n\n# Mount ~/.ssh directory (most compatible)\nDCLAUDE_GIT_AUTH=key-mount dclaude\n```\n\ndclaude warns you if no keys are loaded and suggests `dclaude ssh keys` to load them automatically (see also [SSH Key and Server Management](#ssh-key-and-server-management)).\n\n### Homebrew Support\n\nInstall tools that persist across sessions:\n\n```bash\ndclaude exec brew install ripgrep fd bat jq\ndclaude exec brew install node@20 python@3.12\n```\n\n### GitHub CLI\n\nAuthenticate once, use everywhere:\n\n```bash\ndclaude gh                        # Interactive GitHub login\ndclaude exec gh pr list           # Use gh commands\n```\n\n### Git Configuration\n\nSSH agent forwarding provides authentication for git, but git also needs your identity (name/email) for commits. Use `dclaude git` to configure this:\n\n```bash\ndclaude git                       # Configure git name/email in container\n```\n\nThis reads your host's `~/.gitconfig` and offers to copy the identity into the container's persistent volume.\n\n### SSH Key and Server Management\n\nLoad SSH keys and start SSH server for JetBrains Gateway, VS Code Remote, or any SSH client (see also [SSH Authentication](#ssh-authentication)):\n\n```bash\ndclaude ssh                       # Load keys + start SSH server\ndclaude ssh keys                  # Load SSH keys into agent\ndclaude ssh server                # Start SSH server, shows port\ndclaude ssh server --stop         # Stop SSH server\n# Connect: ssh claude@localhost -p \u003cport\u003e\n# Password: claude\n```\n\n### Chrome DevTools Integration\n\nControl Chrome via MCP for browser automation. Chrome runs on the host with remote debugging; Claude connects from the container:\n\n```bash\ndclaude chrome                    # Launch Chrome with DevTools + create .mcp.json\ndclaude chrome --port=9223        # Use custom debugging port\ndclaude chrome --setup-only       # Create .mcp.json without launching Chrome\ndclaude                           # Claude can now interact with the browser\n```\n\nChrome profiles are stored per-project in `.dclaude.d/chrome/profiles/`. Customize with `DCLAUDE_CHROME_PROFILE`, `DCLAUDE_CHROME_PORT`, `DCLAUDE_CHROME_BIN`, and `DCLAUDE_CHROME_FLAGS`.\n\n### AWS CLI Integration\n\nAWS CLI v2 is pre-installed in the container. Configure how AWS credentials are provided:\n\n```bash\n# Auto (default): mounts ~/.aws from host if it exists, otherwise no config\ndclaude\n\n# Mount host's ~/.aws directory (read-write, shared with host)\nDCLAUDE_AWS_CLI=mount dclaude\n\n# Use isolated Docker volume (persists across container recreations)\nDCLAUDE_AWS_CLI=volume dclaude\n\n# No AWS config mounting\nDCLAUDE_AWS_CLI=none dclaude\n```\n\n**Volume mode** provides isolated AWS config per namespace:\n\n```bash\ndclaude aws configure                  # Copy ~/.aws/config (profiles, regions) into container\ndclaude aws login                      # Run 'aws login' in container\ndclaude aws login --profile staging    # Login with specific profile\n```\n\n### iTerm2 Shell Integration\n\nIf you use iTerm2 on macOS, dclaude automatically enables [iTerm2 Shell Integration](https://iterm2.com/documentation-shell-integration.html):\n\n- **Click URLs in output** - Opens in your Mac's browser\n- **imgcat** - Display images inline in terminal\n- **it2copy** - Copy to Mac clipboard from inside container\n- **Marks** - Navigate between command prompts\n\nThis only activates when running in iTerm2. To disable:\n\n```bash\nDCLAUDE_ITERM2=false dclaude\n```\n\n### System Context\n\ndclaude automatically tells Claude about its container environment so it can give better suggestions:\n\n- **Network mode** - Whether `localhost` works or needs `host.docker.internal`\n- **Docker access** - Whether Docker commands are available\n- **SSH auth method** - How git authentication is configured\n- **AWS CLI** - Whether and how AWS credentials are configured\n- **Path mirroring** - That file paths match the host\n\nThis helps Claude understand its environment without you explaining it. Disable if needed:\n\n```bash\nDCLAUDE_SYSTEM_CONTEXT=false dclaude\n```\n\n## Container Management\n\n```bash\n# Session management\ndclaude new                       # Start a new Claude session\ndclaude attach \u003csession\u003e          # Reattach to a named tmux session\nDCLAUDE_TMUX_SESSION=reviewer dclaude  # Start a named session\n\n# Container lifecycle\ndclaude stop                      # Stop container for current directory\ndclaude rm                        # Remove container (add -f to force)\n\n# Maintenance\ndclaude pull                      # Pull latest Docker image\ndclaude update                    # Update Claude CLI inside container\ndclaude shell                     # Open a bash shell (alias for exec)\n```\n\n## Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `DCLAUDE_RM` | `false` | Remove container on exit (ephemeral mode) |\n| `DCLAUDE_TAG` | `latest` | Docker image tag |\n| `DCLAUDE_NAMESPACE` | (none) | Namespace for isolated credentials/config |\n| `DCLAUDE_NETWORK` | `auto` | Network mode: `auto`, `host`, `bridge` |\n| `DCLAUDE_GIT_AUTH` | `auto` | SSH auth: `auto`, `agent-forwarding`, `key-mount`, `none` |\n| `DCLAUDE_MOUNT_ROOT` | (working dir) | Mount parent directory for sibling access |\n| `DCLAUDE_DEBUG` | `false` | Enable debug output |\n| `DCLAUDE_QUIET` | `false` | Suppress info messages |\n| `DCLAUDE_NO_UPDATE` | `false` | Skip image update check |\n| `DCLAUDE_SYSTEM_CONTEXT` | `true` | Inform Claude about container environment |\n| `DCLAUDE_AWS_CLI` | `auto` | AWS config: `auto`, `mount`, `volume`, `none` |\n| `DCLAUDE_TMUX_SESSION` | `claude-TIMESTAMP` | Custom tmux session name for concurrent sessions |\n| `DCLAUDE_ITERM2` | `true` | Enable iTerm2 shell integration (only affects iTerm2) |\n| `DCLAUDE_CA_CERT` | (none) | Path to CA certificate for corporate SSL inspection |\n\n## Configuration File\n\nCreate a `.dclaude` file at your project root to configure dclaude for that directory tree:\n\n```bash\n# ~/projects/mycompany/.dclaude\nNAMESPACE=mycompany\nNETWORK=host\nDEBUG=true\nCA_CERT=certs/corporate-ca.pem\n```\n\ndclaude walks up the directory tree to find `.dclaude` files. Any dclaude session started from that directory or any subdirectory will use these settings.\n\n**Supported variables:**\n\n| Variable | Description |\n|----------|-------------|\n| `NAMESPACE` | Isolate credentials/config (see Namespace Isolation) |\n| `NETWORK` | Network mode (`host`, `bridge`) |\n| `GIT_AUTH` | Git auth mode |\n| `MOUNT_ROOT` | Mount directory (relative to config file, or absolute path) |\n| `DEBUG` | Enable debug output (`true`, `false`) |\n| `CHROME_PORT` | Chrome DevTools port |\n| `AWS_CLI` | AWS config mode (`mount`, `volume`, `none`) |\n| `CA_CERT` | Path to CA certificate for corporate SSL inspection (relative to config file, or absolute) |\n\nConfig file variables are the unprefixed equivalents of `DCLAUDE_*` environment variables (e.g., `NAMESPACE` in `.dclaude` = `DCLAUDE_NAMESPACE` env var).\n\n**Precedence:** Environment variables override `.dclaude` file settings.\n\n## Namespace Isolation\n\nUse namespaces to maintain completely separate environments with different credentials and settings.\n\n**Use case:** You have both a personal Anthropic subscription and a company subscription. You want to keep them completely separate.\n\n**Option 1: Using `.dclaude` file (recommended)**\n```bash\n# Create config at company project root\necho \"NAMESPACE=mycompany\" \u003e ~/projects/mycompany/.dclaude\n\n# Now any dclaude in that tree uses company credentials\ncd ~/projects/mycompany/api/src\ndclaude  # Uses mycompany namespace automatically\n```\n\n**Option 2: Using environment variable**\n```bash\nDCLAUDE_NAMESPACE=mycompany dclaude\n```\n\n**Option 3: Shell alias**\n```bash\n# Add to ~/.bashrc or ~/.zshrc\nalias dclaude-work='DCLAUDE_NAMESPACE=mycompany dclaude'\n```\n\nEach namespace gets its own:\n- Claude credentials and API key\n- Claude settings and preferences\n- Git configuration\n- Container instance\n\n## Mount Root (Parent Directory Access)\n\nBy default, dclaude only mounts the current working directory. Use `MOUNT_ROOT` to mount a parent directory, enabling access to sibling directories.\n\n**Use case:** You're working in a subdirectory but need access to related projects:\n\n```text\n/Users/alan/projects/mycompany/\n├── shared-libs/          # Common libraries\n├── api-service/          # API backend\n├── web-app/              # Frontend\n└── infrastructure/\n    └── terraform/        # ← You're here, but need access to siblings\n```\n\n**Option 1: Using `.dclaude` file (recommended)**\n```bash\n# Create config at the directory you want as mount root\necho \"MOUNT_ROOT=.\" \u003e ~/projects/mycompany/.dclaude\n\n# Relative paths are resolved from config file's directory\necho \"MOUNT_ROOT=..\" \u003e ~/projects/mycompany/subdir/.dclaude  # mounts mycompany/\n```\n\n**Option 2: Using environment variable**\n```bash\n# Relative path (from working directory)\nDCLAUDE_MOUNT_ROOT=../.. dclaude\n\n# Absolute path\nDCLAUDE_MOUNT_ROOT=/Users/alan/projects/mycompany dclaude\n```\n\nNow Claude can see and work with all sibling directories while your working directory remains `terraform/`.\n\n## Networking\n\ndclaude auto-detects the best networking mode:\n\n**Host mode** (when available):\n- Direct `localhost` access to host services\n- Works on: Linux, macOS with OrbStack/Docker Desktop beta, Windows with Docker Desktop beta\n\n**Bridge mode** (fallback):\n- Use `host.docker.internal` instead of `localhost`\n- Standard Docker networking\n\nForce a specific mode:\n```bash\nDCLAUDE_NETWORK=host dclaude\nDCLAUDE_NETWORK=bridge dclaude\n```\n\n## Platform Support\n\n| Platform | Status | Notes |\n|----------|--------|-------|\n| Linux | Full support | Host networking available |\n| macOS | Full support | Host networking with OrbStack or Docker Desktop beta |\n| Windows | Full support | Requires WSL2; host networking with Docker Desktop beta features |\n\n## What's Included\n\nThe container includes:\n- **Ubuntu 24.04 LTS** base\n- **Claude Code CLI** (latest, AMD64 and ARM64/Apple Silicon)\n- **Node.js 20+**, **Python 3** with pip\n- **Homebrew/Linuxbrew** for package management\n- **Docker CLI** and **Docker Compose**\n- **Git**, **GitHub CLI** (`gh`), common dev tools\n- **tmux** for session management\n- **AWS CLI v2** for cloud operations\n- **SSH server** for IDE integration\n\n## Troubleshooting\n\n**Docker not running?**\n```bash\n# Make sure Docker Desktop is running, or on Linux:\nsudo systemctl start docker\n```\n\n**Permission denied on Docker socket?**\n```bash\n# Linux: Add yourself to the docker group\nsudo usermod -aG docker $USER\n# Then logout and login\n```\n\n**Can't access localhost services?**\n```bash\n# Check what network mode is being used\nDCLAUDE_DEBUG=true dclaude\n\n# Try forcing host mode\nDCLAUDE_NETWORK=host dclaude\n\n# Or use host.docker.internal in bridge mode\n```\n\n**SSH keys not working?**\n```bash\n# Make sure your key is loaded\nssh-add -l\n\n# If empty, load your key\nssh-add ~/.ssh/id_ed25519\n```\n\n**Installed tools disappearing?**\n```bash\n# Make sure you're using persistent mode (default)\n# If you set DCLAUDE_RM=true, tools won't persist\ndclaude exec brew install \u003ctool\u003e  # This persists\n```\n\n**Directories appear empty inside container? (OrbStack)**\n\nThis is a [known OrbStack 2.0.x bug](https://github.com/orbstack/orbstack/issues/2103) where VirtioFS caches stale directory entries. Directories that existed before upgrading to OrbStack 2.0 may appear empty inside the container.\n\n```bash\n# Fix: rename the directory to clear the cache\nmv problematic-dir problematic-dir.tmp \u0026\u0026 mv problematic-dir.tmp problematic-dir\n\n# Or restart OrbStack completely (clears all caches)\n```\n\nUpgrading to the latest OrbStack version may also help.\n\n## Shell Completions\n\nTab completion is available for bash and zsh:\n\n```bash\n# Bash — add to ~/.bashrc\nsource \"$(npm root -g)/@alanbem/dclaude/completions/dclaude.bash\"\n\n# Zsh — add to ~/.zshrc\nsource \"$(npm root -g)/@alanbem/dclaude/completions/dclaude.zsh\"\n\n# Source install — use the repo path directly\nsource ~/tools/dclaude/completions/dclaude.bash\n```\n\n## Project Structure\n\n```text\n.\n├── dclaude                 # Launcher script (runs on host)\n├── docker/\n│   ├── Dockerfile          # Container image definition\n│   ├── README.md           # Docker Hub documentation\n│   ├── usr/local/bin/\n│   │   ├── docker-entrypoint.sh\n│   │   ├── claude-launcher.sh\n│   │   └── tmux-wrapper.sh\n│   └── home/claude/\n│       └── .tmux.conf\n├── .github/workflows/      # CI/CD (lint, scan, publish)\n├── completions/            # Shell completions (bash, zsh)\n├── Makefile                # Development commands\n└── package.json            # NPM package config\n```\n\n## Development\n\nWant to modify dclaude? Build and test locally:\n\n```bash\n# Build local image\nmake build                    # Creates alanbem/dclaude:local\n\n# Test\nmake test\n\n# Use your local image\nDCLAUDE_TAG=local dclaude\n```\n\n## Contributing\n\nContributions welcome! Submit a Pull Request.\n\n## License\n\nMIT - see [LICENSE](LICENSE)\n\n## Links\n\n- [Docker Hub](https://hub.docker.com/r/alanbem/dclaude)\n- [npm](https://www.npmjs.com/package/@alanbem/dclaude)\n- [Issues](https://github.com/alanbem/dclaude/issues)\n- [Discussions](https://github.com/alanbem/dclaude/discussions)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falanbem%2Fdclaude","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falanbem%2Fdclaude","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falanbem%2Fdclaude/lists"}