HN 표시: Claude Code 컨테이너 – Claude 코드를 위한 Zero-Config Docker 격리

Single command. Isolated environment. No setup required. Run ccc in your project directory — no Dockerfile, docker-compose, port mapping, or volume config needed. - Per-project isolated containers (path-hash based naming) - Auto-forwarding of host env vars, locale ( LANG /LC_* ), and timezone (TZ ) - SSH keys and agent auto-mounted - Auto-cleanup on session exit (stops container when last session ends) - mise-based tool version management (auto-detect and create mise.toml ) - Built-in Chromium (headless testing support) --network host for direct port access- macOS/Windows: transparent localhost proxy (iptables + fallback to host.docker.internal ) - Auto-pull Docker image from Docker Hub on first run (no manual docker build needed) - Version-aware image management (auto-updates on npm update ) npm install -g claude-code-container On first ccc run, the Docker image (~2GB) is automatically pulled from Docker Hub. No manual build required. For development setup, see CONTRIBUTING.md. # Run Claude in current project (container auto-created) ccc # Continue previous session ccc --continue ccc --resume # Open a shell in the container ccc shell # Run arbitrary commands ccc npm install ccc npm test ~/.ccc/ ├── claude/ # Claude credentials (mounted to /claude) └── locks/ # Session lock files (per session) Docker Volume: └── ccc-mise-cache # mise cache (named volume, optimized for macOS/Windows) - Start: Container created/started + session lock file created - Running: Multiple sessions can run for the same project simultaneously - Exit: Lock file deleted; container auto-stops if no other sessions remain - Crash recovery: Stale lock files cleaned up on next run Container names are fixed per project path hash, so claude --continue and --resume work correctly. ccc uses Docker image labels to manage versions: | Scenario | Behavior | |---|---| | npm install (first run) | Auto-pulls matching version from Docker Hub | | npm update | Detects version mismatch, auto-pulls new image | Local docker build -t ccc . | Uses local image, never auto-replaced | | Offline with stale image | Warns but continues with existing image | | Offline with no image | Error with instructions to build locally | Override the registry with CCC_REGISTRY env var: export CCC_REGISTRY=myregistry/claude-code-container ccc # Run Claude ccc shell # Open bash shell ccc # Run arbitrary command ccc --env KEY=VALUE # Set additional env var ccc stop # Stop current project's container ccc rm # Remove current project's container ccc status # Show CLI version, image info, and containers ccc doctor # Health check and diagnostics ccc clean # Clean stopped containers and images Host environment variables are automatically forwarded to the container. export JIRA_API_KEY=xxx ccc # JIRA_API_KEY is available inside the container Excluded (to prevent system conflicts): PATH ,HOME ,USER ,SHELL ,PWD - macOS-specific vars ( TERM_PROGRAM ,ITERM_* ,LC_TERMINAL , etc.) Auto-forwarded: LANG , LC_ALL , LC_CTYPE (host locale), TZ (auto-detected) ccc --env API_KEY=xxx --env DEBUG=true See the Tool Management (mise) section for details on separating container and desktop environments. SSH configuration from the host is automatically used when Git SSH access is needed (private repo cloning, plugin installation, etc.). | Item | macOS (Docker Desktop) | Linux | |---|---|---| SSH keys (~/.ssh ) | Read-only mount | Read-only mount | | SSH Agent | Docker Desktop built-in socket | $SSH_AUTH_SOCK auto-detected | # 1. Check if SSH keys are registered with the agent on host ssh-add -l # Add key if missing ssh-add ~/.ssh/id_ed25519 # or id_rsa # 2. Recreate container (to apply new mounts) ccc rm ccc ccc shell ssh-add -l # List agent keys ssh -T [email protected] # Test GitHub connection ssh -T [email protected] # Test GitLab connection ccc @ creates an isolated workspace per branch. It auto-creates git worktree entries for git repos in the current directory and runs Claude in the workspace. ~/projects/ ├── my-project/ # Original (git repos + other files) │ ├── backend/ # git repo │ ├── frontend/ # git repo │ └── shared/ # regular directory └── my-project--feature/ # Workspace (auto-created) ├── backend/ # git worktree (feature branch) ├── frontend/ # git worktree (feature branch) └── shared -> ../my-project/shared # symlink Git repos are linked via git worktree ; other items are symlinked. # Create workspace + run Claude ccc @feature # Reuse existing workspace ccc @feature --continue # List workspaces + container status ccc @ # Remove workspace (container + worktrees) ccc @feature rm # Force remove dirty worktrees ccc @feature rm -f - Local branch exists: Creates worktree from that branch - Remote only: Creates local branch from origin/ - Doesn't exist: Creates new branch from HEAD Branch / is converted to - in directory names (e.g., feature/login → my-project--feature-login/ ). Each workspace has its own container, so they can run simultaneously. # Terminal 1 cd ~/projects/my-project && ccc @fe