initial

2026-04-14 20:11:24 +02:00 · 2026-04-14 20:11:24 +02:00 · c01102b641
commit c01102b641
10 changed files with 554 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,120 @@
+# docker-claude
+
+Runs [Claude Code](https://claude.ai/code) inside an isolated Docker environment with a proxy sidecar for controlled egress. Claude cannot reach the host filesystem or network directly.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│  Host machine                                       │
+│                                                     │
+│  claude.sh (control script)                         │
+│       │                                             │
+│       ▼                                             │
+│  ┌─────────────────────────────────────────────┐   │
+│  │  Docker: claude-secure                      │   │
+│  │                                             │   │
+│  │  ┌─────────────┐    claude-internal         │   │
+│  │  │  claude     │◄─────(internal only)───►  │   │
+│  │  │  (UID 1000) │           │               │   │
+│  │  └─────────────┘    ┌──────┴──────┐        │   │
+│  │                     │   proxy     │         │   │
+│  │                     │  (UID 13)   │         │   │
+│  │                     └──────┬──────┘         │   │
+│  │                     proxy-external           │   │
+│  └─────────────────────────────────────────────┘   │
+│                              │                      │
+│                              ▼                      │
+│                   internet (allowlisted)             │
+└─────────────────────────────────────────────────────┘
+```
+
+- **`claude` container** — Claude Code, runs as UID 1000, on `claude-internal` only (no internet route)
+- **`proxy` container** — Squid forward proxy, runs as UID 13, bridges `claude-internal` ↔ internet, enforces egress allowlist
+- **`claude-internal`** — Docker bridge with `internal: true`; Docker adds no default gateway, so containers on this network cannot reach the internet directly
+- **`proxy-external`** — Standard bridge; the proxy sidecar uses this for controlled outbound access
+
+## Prerequisites
+
+- Docker Engine 24+
+- Docker Compose v2 plugin (`docker compose version`)
+
+## Setup
+
+```bash
+# 1. Clone / copy this repo
+git clone <repo> docker-claude && cd docker-claude
+
+# 2. Configure your API key
+cp .env.example .env
+$EDITOR .env   # set ANTHROPIC_API_KEY
+
+# 3. Make the control script executable
+chmod +x claude.sh
+```
+
+## Usage
+
+```bash
+# Build images, start proxy, launch Claude Code interactively
+./claude.sh start
+
+# Same as start but skips image rebuild (faster on subsequent runs)
+./claude.sh run
+
+# Stop and remove all containers (proxy + any running sessions)
+./claude.sh stop
+
+# Rebuild images without cache (e.g. after Claude Code updates)
+./claude.sh update
+
+# Tail proxy access logs
+./claude.sh logs
+
+# Show container status
+./claude.sh status
+
+# Open a debug bash shell inside the Claude container
+./claude.sh shell
+```
+
+### Working with host files
+
+By default, Claude's workspace is a named Docker volume (`claude-secure-workspace`) — fully isolated from the host.
+
+To mount a specific host directory:
+
+```bash
+WORKSPACE_DIR=$HOME/myproject ./claude.sh run
+```
+
+The directory is mounted at `/workspace` inside the container.
+
+## Egress allowlist
+
+Edit `proxy/squid.conf` and add domains to the `allowed_sites` ACL:
+
+```squid
+acl allowed_sites dstdomain api.anthropic.com
+acl allowed_sites dstdomain statsig.anthropic.com
+# acl allowed_sites dstdomain api.github.com   # uncomment if needed
+# acl allowed_sites dstdomain registry.npmjs.org
+```
+
+Rebuild the proxy after changes:
+
+```bash
+docker compose -p claude-secure build proxy
+./claude.sh stop && ./claude.sh start
+```
+
+## Security controls
+
+| Control | Claude container | Proxy container |
+|---|---|---|
+| Non-root user | UID 1000 (`claude`) | UID 13 (`proxy`) |
+| `no-new-privileges` | yes | yes |
+| All capabilities dropped | yes | yes |
+| Direct internet access | no (`internal` network only) | allowlisted only |
+| Host filesystem | no mounts by default | none |
+| Docker socket | not mounted | not mounted |