Skip to content

etoryoki/claude-code-sandbox

BranchesTags

Repository files navigation

Claude Code Sandbox (Windows + Docker Desktop)

Windows + PowerShell から sandbox claude 一発で、使い捨ての Docker コンテナ内に Claude Code を起動するための構成一式です。

次の 5 つを満たします。

  1. 使い捨てコンテナ — Claude Code を --rm の Docker コンテナ内で実行
  2. PII マスキング — API リクエストを privacy-guard-proxy 経由にして、メール・電話番号などをマスク
  3. egress allowlist — iptables + ipset で、許可ドメイン以外への外向き通信を遮断
  4. 機密ファイルの Read 拒否 — .env / 各種鍵 / ~/.ssh などを managed-settings.json でブロック
  5. バージョン固定 — ベースイメージ・Node・Claude Code をビルド時に固定

動作確認環境: Windows 11 + Docker Desktop (WSL2 backend) + PowerShell 5.1 / 7。

前提

  • Windows 10/11
  • Docker Desktop インストール済み・起動中（docker --version / docker ps が通ること）
  • PowerShell 5.1 または 7+

セットアップ

git clone https://github.com/etoryoki/claude-code-sandbox.git
cd claude-code-sandbox

# 1. インストール（~/.sandbox へ配置 + プロファイルに sandbox 関数を追加）
.\install\install.ps1

# 2. privacy-guard プロキシを起動
docker compose -f "$HOME\.sandbox\docker-compose.yml" up -d

# 3. プロファイル再読み込み（または新しいターミナルを開く）
. $PROFILE

install.ps1 は次を行います。

  • Dockerfile / docker-compose.yml / entrypoint.sh / init-firewall.sh / managed-settings.json を ~/.sandbox へコピー
  • privacy-guard-config.sample.json → ~/.sandbox\privacy-guard-config.json を生成（未存在時のみ）
  • $PROFILE にマーカー付きで sandbox 関数を追記（再実行で更新）

手動で行う場合は、上記ファイルを ~/.sandbox に置き、install/sandbox.ps1 の内容を $PROFILE に貼り付けてください。

使い方

cd C:\path\to\your\project
sandbox claude          # カレントディレクトリを /workspaces/project にマウントして起動

初回はイメージを自動ビルドします。Claude Code には /login でログインしてください （認証情報・設定はプロファイル別の Docker volume claude-code-config-<profile> に永続化されます）。

オプション

指定 効果
sandbox claude 既定（マスキング ON・ファイアウォール ON）
sandbox claude -NoMask プロキシを経由しない（マスキング無効）
sandbox claude -NoFirewall egress 制限なしで起動（切り分け用）
sandbox claude -Profile work 認証・設定を別 volume に分離
sandbox bash コンテナ内でシェルを起動

プロキシは restart: unless-stopped なので Docker Desktop 起動時に自動復帰します。 止めてしまった場合は docker compose -f "$HOME\.sandbox\docker-compose.yml" up -d で再開できます。

仕組み

PowerShell  ──sandbox claude──▶  claude-sandbox コンテナ
                                   │  ANTHROPIC_BASE_URL=http://host.docker.internal:9880
                                   ▼
                       host.docker.internal:9880 (ホスト)
                                   │
                          socat 転送サイドカー (0.0.0.0:9890)
                                   ▼
                     privacy-guard-proxy (127.0.0.1:9880) ──▶ api.anthropic.com
                       └ PII を検出・マスクしてから上流へ
  • ファイアウォール: entrypoint.sh が ENABLE_FIREWALL=1 のとき init-firewall.sh を実行。 init-firewall.sh の ALLOWED_DOMAINS のみ許可し、それ以外は即 REJECT（タイムアウト待ちを避ける）。
  • socat サイドカー: privacy-guard-proxy は 9880 をコンテナ内ループバックでしか待ち受けないため、 同一ネットワーク名前空間の socat が 0.0.0.0 で受けて中継する（docker-compose.yml 参照）。
  • 管理設定: managed-settings.json をコンテナの /etc/claude-code/managed-settings.json（0444）に配置。

カスタマイズ

許可ドメインを増やす（リモート MCP・追加 API など）

init-firewall.sh の ALLOWED_DOMAINS にドメインを追加して再ビルド。

ALLOWED_DOMAINS=(
    "api.anthropic.com"
    "registry.npmjs.org"
    "mcp.example.com"   # ← 追加
    ...
)
docker build -t claude-sandbox $HOME\.sandbox

Claude Code のバージョンを厳密に固定

Dockerfile の ARG CLAUDE_CODE_VERSION=latest を固定値にする（例: =2.1.150）。 意図的に更新したいときは docker build --no-cache -t claude-sandbox $HOME\.sandbox。

MCP サーバ

  • stdio 型（npx/node 等）はそのまま動作: claude mcp add <名前> -s user -- npx -y <パッケージ>（-s user で volume に永続化）
  • リモート型（HTTP/SSE）は接続先ドメインを上記 allowlist に追加。
  • Python 製サーバを使う場合は Dockerfile に python を追加。

API キーを渡す

~/.sandbox\mcp.env を作成すると --env-file で自動的にコンテナへ渡されます（.gitignore 済み）。

セキュリティ上の注意

  • docker-compose.yml ではプロキシの 9880 を 0.0.0.0 で公開しています（コンテナから到達させるため）。 既定では api_keys が空なので、同一 LAN から無認証で利用され得ます。気になる場合は privacy-guard-config.json の api_keys に鍵を設定してください。管理 UI の 9881 は 127.0.0.1 限定です。
  • privacy-guard-config.json と mcp.env、logs/ は .gitignore 済み。秘密情報をコミットしないよう注意。

トラブルシュート（実際に踏んだ落とし穴）

症状 原因 / 対処
.sh で bad interpreter 改行が CRLF。LF で保存する（このリポジトリは LF 済み）。
bubblewrap is required ... で起動失敗 イメージに bubblewrap が必要（導入済み）。
Bash が全コマンド bwrap: Can't mkdir /mnt/c ... で失敗 Docker Desktop は WSL2 カーネルで動くため Claude Code が WSL と誤検知し、存在しない Windows パスを bind しようとする。CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=0（Dockerfile で既定）で回避。
ECONNRESET / Empty reply（プロキシ到達不可） プロキシ 9880 がコンテナ内ループバック限定。socat サイドカー（compose 同梱）で解決済み。
Unable to connect ... ECONNREFUSED api.anthropic.com 起動時の到達性チェックが直アクセスするため、api.anthropic.com を allowlist に追加済み（マスキングは BASE_URL 経由で維持）。
ログイン直後に Not logged in に戻る ~/.claude volume が root 所有で書き込めない。Dockerfile で vscode 所有に作成済み。既存の壊れた volume は docker volume rm claude-code-config-default で作り直す。
毎回オンボーディング（テーマ選択）が出る ~/.claude.json が volume 外。entrypoint.sh が volume 内へ symlink して永続化。

ファイル構成

Dockerfile                      ベースイメージ + Node + Claude Code + 隔離ツール
docker-compose.yml              privacy-guard-proxy + socat 転送サイドカー
entrypoint.sh                   ファイアウォール初期化 + .claude.json 永続化
init-firewall.sh                iptables/ipset による egress allowlist
managed-settings.json           機密ファイル Read 拒否などの権限ポリシー
privacy-guard-config.sample.json プロキシ設定のサンプル（実体は gitignore）
install/sandbox.ps1             PowerShell の sandbox 関数
install/install.ps1             セットアップスクリプト

About

One-command sandbox claude Docker sandbox for Claude Code on Windows: PII masking, egress allowlist, secret-file deny, pinned versions.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages