claude-docker: Instructions file for Claude Code

claude-docker

Docker sandbox for running Claude Code in an isolated Linux container that mirrors the host environment.

Quick Start

bin/claude-docker-ctrl start    # build image, start container
bin/claude-docker-ctrl stop     # stop container
bin/claude-docker-ctrl status   # show container status
bin/claude-docker-ctrl shell    # shell into the container (auto-detects from host $SHELL)
bin/claude-docker-ctrl exec     # interactive Claude session in container
bin/claude-docker-ctrl rebuild  # rebuild image from scratch + restart

Project Structure

• Dockerfile — Alpine 3.24 image
• docker-compose.yml — base container config (auth, socket proxy, filter proxy, Go cache)
• scripts/ — shell scripts copied into the container at build time:
  • entrypoint.sh — runtime setup: socket proxy wait, git credentials, GPG import, user drop
  • git-wrapper.sh — blocks git push to protected branches and any git push that includes tags (--tags, --follow-tags, --mirror, refs/tags/* refspecs, <remote> tag <name> shorthand). Replaces /usr/bin/git. Defense-in-depth only: git-real is still readable+executable by the unprivileged user, so a determined caller can invoke /usr/libexec/git-real/git directly. Real branch/tag protection must come from the upstream (server-side hook).
  • docker-wrapper.sh — allowlists safe docker subcommands, including build and buildx, and warns (without blocking) when a build tag would overwrite one of the sibling sandbox images. Replaces /usr/bin/docker; direct calls to the real binary still pass through the filtering proxy.
  • claude-session.sh — process-group wrapper that ensures claude + children (gopls) are killed on disconnect
  • go-install.sh — Dockerfile helper to download Go by version
• docker-filter-proxy/ — Go reverse proxy that blocks privileged containers, host namespacing, dangerous capabilities
• bin/claude-docker — interactive Claude session in container (-it)
• bin/claude-docker-vscode-wrapper — VSCode claudeProcessWrapper script (-i only, no TTY)
• bin/claude-docker-jetbrains-wrapper — JetBrains (GoLand/IntelliJ) Claude command wrapper (auto-detects TTY)
• bin/claude-docker-ctrl — container lifecycle management
• bin/lib/session-cleanup.sh — host-side session lifecycle shared by the bin/ wrappers (and the user's shell function): a detached watchdog HUPs the in-container session when the launching shell dies (double-forks before setsid so interactive-zsh job control can't kill it with the terminal; tracks parent identity as PID + start time to survive PID reuse), reap_stale_sessions sweeps orphaned sessions whose host client is gone, and when the last session ends the transient claude daemon is stopped so armed background tasks can't keep re-invoking Claude unattended
• config/ — user configuration (gitignored copies + examples):
  • docker-compose.local.example.yml — template for project volume mounts
  • claude-notifier.example — template for notification script
  • .env.example — all configurable env vars
  • claude-settings.example.json — example Claude Code hooks
  • CLAUDE.md.example — example CLAUDE.md with notifier usage
• ../aws-ai-proxy/ - optional independently running AWS credential proxy consumed when AWS_AI_PROXY_ENABLED is true (https://github.com/hrubymar10/aws-ai-proxy)
• beeper/ — simple Go HTTP server that plays a beep sound on the host (optional)
• gpg-keys/ — drop GPG private keys here for commit signing (gitignored)