176 lines
6.7 KiB
Markdown
176 lines
6.7 KiB
Markdown
# docker-claude
|
|
|
|
Runs [Claude Code](https://claude.ai/code) inside an isolated Docker environment with a proxy sidecar for controlled egress. Claude cannot access the host filesystem or network directly.
|
|
|
|
## Quick Start
|
|
|
|
**1. Install a Docker runtime**
|
|
|
|
Pick the free, open-source option for your platform:
|
|
|
|
| Platform | Recommended | Alternative |
|
|
|---|---|---|
|
|
| macOS | [Rancher Desktop](https://rancherdesktop.io/) (GUI) | [Colima](https://github.com/abiosoft/colima) (CLI): `brew install colima docker docker-compose && colima start` |
|
|
| Linux | Docker Engine: `curl -fsSL https://get.docker.com \| sh` | [Rancher Desktop](https://rancherdesktop.io/) |
|
|
| Windows | [Rancher Desktop](https://rancherdesktop.io/) (GUI) | WSL2 + Docker Engine (see below) |
|
|
|
|
> **Note:** Docker Desktop is not listed — it requires a commercial licence for business use.
|
|
|
|
**2. Download this repo**
|
|
|
|
Clone or download and unzip this repository somewhere on your machine.
|
|
|
|
**3. Run setup**
|
|
|
|
- **macOS / Linux:** Open a terminal, navigate to the folder, and run:
|
|
```bash
|
|
./setup.sh
|
|
```
|
|
- **Windows:** Double-click `launch.bat` — it will run setup automatically on first launch.
|
|
|
|
Setup will ask how you want to authenticate (API key, subscription token, or browser login) and save your settings.
|
|
|
|
**4. Start Claude**
|
|
|
|
- **macOS / Linux:** Double-click `launch.sh`, or run it from a terminal:
|
|
```bash
|
|
./launch.sh
|
|
```
|
|
A folder picker will appear — select the project you want Claude to work on.
|
|
|
|
- **Windows:** Double-click `launch.bat`.
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌──────────────────────────────────────────────────────────┐
|
|
│ Host machine │
|
|
│ │
|
|
│ claude.sh (control script) │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌──────────────────────────────────────────────────┐ │
|
|
│ │ Docker: claude-secure │ │
|
|
│ │ │ │
|
|
│ │ ┌─────────────┐ claude-internal │ │
|
|
│ │ │ claude │ (internal: true) │ │
|
|
│ │ │ (UID 1000) │──────────────► ┌──────────┐ │ │
|
|
│ │ └─────────────┘ │ proxy │ │ │
|
|
│ │ │ (UID 13) │ │ │
|
|
│ │ └────┬─────┘ │ │
|
|
│ │ proxy-external │ │
|
|
│ └──────────────────────────────────────────────────┘ │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ internet (allowlisted) │
|
|
└──────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
- **`claude`** — Claude Code CLI (`node:24-alpine`), runs as the built-in `node` user (UID 1000), on `claude-internal` only
|
|
- **`proxy`** — Squid forward proxy (`alpine:3.21`), bridges `claude-internal` ↔ internet with egress allowlist
|
|
- **`claude-internal`** — `internal: true`; no default gateway, containers cannot reach the internet directly
|
|
- **`proxy-external`** — Standard bridge; proxy sidecar only
|
|
|
|
## Prerequisites
|
|
|
|
A Docker runtime with Compose support. Choose a free, open-source option:
|
|
|
|
- **macOS:** [Rancher Desktop](https://rancherdesktop.io/) or [Colima](https://github.com/abiosoft/colima)
|
|
- **Linux:** [Docker Engine CE](https://docs.docker.com/engine/install/) (`curl -fsSL https://get.docker.com | sh`)
|
|
- **Windows:** [Rancher Desktop](https://rancherdesktop.io/) or WSL2 + Docker Engine
|
|
|
|
> Docker Desktop is not recommended — it requires a commercial licence for business use.
|
|
|
|
## Authentication
|
|
|
|
Three options — `./setup.sh` will guide you through picking one:
|
|
|
|
### Option 1 — API key
|
|
```bash
|
|
ANTHROPIC_API_KEY=sk-ant-...
|
|
```
|
|
Get a key at [console.anthropic.com](https://console.anthropic.com/settings/keys).
|
|
|
|
### Option 2 — OAuth token (subscription, headless-friendly)
|
|
|
|
Run this **on your host** (not inside the container) to generate a 1-year token:
|
|
```bash
|
|
claude setup-token
|
|
```
|
|
Then paste the token into setup, or set it manually in `.env`:
|
|
```bash
|
|
CLAUDE_CODE_OAUTH_TOKEN=...
|
|
```
|
|
|
|
### Option 3 — Browser OAuth (interactive)
|
|
|
|
Leave both keys unset. On first run, Claude Code will print a login URL.
|
|
Port 54545 must be reachable from your browser for the OAuth callback.
|
|
|
|
## Usage
|
|
|
|
### Normal use
|
|
|
|
```bash
|
|
./launch.sh # folder picker → starts Claude in the selected directory
|
|
```
|
|
|
|
### CLI / power users
|
|
|
|
```bash
|
|
cd ~/myproject
|
|
./claude.sh start
|
|
|
|
./claude.sh stop # Stop and remove all containers
|
|
./claude.sh update # Pull latest images from the registry
|
|
./claude.sh logs # Tail proxy logs
|
|
./claude.sh status # Show container status
|
|
./claude.sh shell # Debug bash shell in the Claude container
|
|
```
|
|
|
|
### Windows: WSL2 + Docker Engine (alternative to Rancher Desktop)
|
|
|
|
1. Install [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install): `wsl --install` in PowerShell
|
|
2. Open the Ubuntu terminal and run:
|
|
```bash
|
|
curl -fsSL https://get.docker.com | sh
|
|
sudo usermod -aG docker $USER
|
|
```
|
|
3. Log out and back in, then run `launch.bat` as usual.
|
|
|
|
### Building locally
|
|
|
|
```bash
|
|
./build.sh # build with layer cache
|
|
./build.sh --no-cache # force full rebuild
|
|
```
|
|
|
|
## Egress allowlist
|
|
|
|
Edit `proxy/squid.conf` and add domains to the `allowed_sites` ACL:
|
|
|
|
```
|
|
acl allowed_sites dstdomain api.anthropic.com
|
|
acl allowed_sites dstdomain statsig.anthropic.com
|
|
# acl allowed_sites dstdomain api.github.com
|
|
# acl allowed_sites dstdomain registry.npmjs.org
|
|
```
|
|
|
|
Rebuild after changes:
|
|
|
|
```bash
|
|
./claude.sh stop && ./claude.sh start
|
|
```
|
|
|
|
## Security controls
|
|
|
|
| Control | claude | proxy |
|
|
|---|---|---|
|
|
| Non-root user | UID 1000 (`node`, built into base image) | `squid` user |
|
|
| `no-new-privileges` | yes | yes |
|
|
| All capabilities dropped | yes | yes |
|
|
| Direct internet access | no (`internal` network only) | allowlisted only |
|
|
| Host filesystem | CWD mounted as `/workspace` | none |
|
|
| Docker socket | not mounted | not mounted |
|