🔗 関連ガイド
このページは「コンテナ・永続化」専門。サンドボックスの仕組み自体は サンドボックスガイド、CLAUDE.md/設定ファイルの書き方は コンテキスト管理ガイド を参照。
⚡ TL;DR
🔒 コンテナ内の ~/.claude は Named Volume でプロジェクト完全分離。ローカルの汚染問題がそもそも発生しない
🛡️ ネットワーク制限は iptables allowlist(コンテナ独自)+ Claude Code 組み込み sandbox の 2 層構造
🐛 2026年前半に多発していた sandbox バグは修正済み。新しい不具合は日次のニュースで確認する
🗑️ ~/.claude/jobs のバックグラウンドジョブ状態は自動では掃除されない。claude stop <id> で止めて claude rm <id> で一覧から消す
01 — なぜコンテナで動かすか
🐳 コンテナ運用のメリット
  • ~/.claude がプロジェクトごとに完全分離
  • iptables でネットワークを allowlist 制限
  • ホストの npm / Node.js 環境を汚染しない
  • チームで同一環境を再現できる
  • devcontainerId でボリュームが自動分離
  • ホスト OS クラッシュリスクをコンテナに閉じ込め
💻 ローカル運用のデメリット
  • ~/.claude がプロジェクト横断で汚染される
  • グローバル CLAUDE.md に何でも書いてしまう
  • ネットワーク制限がない(デフォルト無制限)
  • Node.js バージョン衝突の可能性
  • 組み込みのサンドボックスは既定でオフ(/sandbox か sandbox.enabled: true で有効にする。macOS では Seatbelt を使う)
  • 環境差異でチームと挙動が変わることがある
📌 現場への移行コスト
4 月時点はバグが多く勧めづらかったが、現在はほぼ解消。Docker Desktop さえ入れれば VS Code で devcontainer が one-click で立ち上がる。 初回ビルド(iptables 初期化含む)は 1〜2 分。以降はボリューム再利用で数秒起動。
02 — サンドボックス 2 層構造
🔒 セキュリティ層の全体像

Layer 1: Claude Code Sandbox

  • 非特権コンテナで bubblewrap が /proc をマウントできない(Can't mount proc on /newroot/proc)場合に限り enableWeakerNestedSandbox: true を使う。隔離は弱まるので、外側のコンテナが隔離境界になっているときだけ使う
  • 仕組み・設定・トラブルシュートの詳細は サンドボックスガイド へ

Layer 2: iptables Firewall(コンテナ独自)

  • ネットワーク全域を allowlist 制御
  • 起動時に GitHub IP を動的取得
  • 許可ドメイン: 公式の構成は npm / Anthropic API / GitHub / VS Code Marketplace / sentry.io / statsig.com。このリポジトリでは Kiro と OpenAI を独自に追加
  • postStart で毎回初期化・検証
⚠️ iptables の既知の限界
  • IPv6 未対応 — ip6tables ルールなし。このコンテナは IPv6 なし(loのみ)なので現状問題なし
  • DNS TOCTOU — 起動時 IP を ipset に登録するが、CDN の IP ローテーション後は新規接続が DROP される可能性
  • WebFetch ツール — WebFetch は Bash のサンドボックスの allowedDomains の対象外で、WebFetch(domain:...) の権限ルールで制御する。Claude Code のプロセスから直接通信するので、コンテナの iptables は WebFetch にも適用される
03 — 4月以降のバグ修正タイムライン
✅ 結論
2026年前半に多発していた sandbox バグは修正済み。 現在コンテナ運用を始めるのに大きな障害はない。
CVE-2026-25725(2026-02 公開・v2.1.2 で修正済み)
SEC settings.json 経由のサンドボックス脱出(Configuration Injection)。なお SOCKS5 の null-byte によるネットワーク許可リストの回避は別の問題で、二次情報では v2.1.90 で修正されたとされる(公式のアドバイザリ・CVE はなし)。
v2.1.133(5/7)
NEW sandbox.bwrapPath / sandbox.socatPath でカスタムバイナリパスを指定可能に。非標準インストール環境に対応。
v2.1.149(5/22)
FIX ホームディレクトリへの find コマンドが macOS の vnode テーブルを枯渇させホストをクラッシュさせるバグを修正。
v2.1.163(6/4)
FIX v2.1.154 で入った、$TMPDIR がサンドボックス外のコマンドにも /tmp/claude-{uid} で上書きされる不具合を修正(bazel / EDR 保護環境で影響)。
v2.1.173(6/11)
FIX settings で sandbox を有効にしている Windows 環境の起動時に「sandbox dependencies missing」の偽警告が出るバグを修正。
v2.1.176(6/12)
FIX .claude/settings.json が絶対パスのシンボリックリンクの場合に Linux sandbox が起動失敗するバグを修正。
Issue #32251(2026-03-08 にクローズ済み)
BUG macOS で /sandbox コマンドが Linux の依存(bubblewrap / socat / seccomp)を表示してしまう問題。報告と同日にクローズされている。
04 — コンテキストファイル(CLAUDE.md / AGENTS.md)の管理
📂 詳しくはコンテキスト管理ガイドへ
CLAUDE.md / AGENTS.md のファイル階層・読み込みタイミング・「何をどこに書くか」の判断ツリー・汚染パターンと対処法は コンテキスト管理ガイド に集約した。このページではコンテナ環境が何を自動で解決するか(次セクション)だけを扱う。
05 — コンテナでのコンテキスト永続化設計
🗂 現在の devcontainer マウント構成
# devcontainer.json のマウント設定
"mounts": [
  "source=claude-code-bashhistory-${devcontainerId},target=/commandhistory,type=volume",
  "source=claude-code-config-${devcontainerId},target=/home/node/.claude,type=volume"
],
"containerEnv": {
  "CLAUDE_CONFIG_DIR": "/home/node/.claude"
},
"workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=delegated"

1つ目のマウントで zsh の履歴、2つ目で Claude Code の設定を永続化し、ソースコードは bind mount で渡す。CLAUDE_CONFIG_DIR を設定しないと、~/.claude.json(アカウント情報・MCP・信頼したフォルダ)が rebuild のたびに消える。

Named Volume で永続化されるもの
  • settings.json(権限・hooks・sandbox設定)
  • skills/ (インストール済みスキル)
  • agents/ (カスタムサブエージェント)
  • projects/<project>/*.jsonl (会話の記録、--resume 用。cleanupPeriodDays(既定30日)を過ぎると自動削除)
  • projects/<project>/memory/ (Auto Memory)
  • zsh コマンド履歴
bind mount で永続化されるもの
  • /workspace/CLAUDE.md(プロジェクト設定)
  • /workspace/CLAUDE.local.md(個人設定)
  • /workspace/.claude/settings.json
  • /workspace/.claude/skills/
  • /workspace/.claude/agents/
  • ソースコード全体
💡 devcontainerId によるプロジェクト分離
claude-code-config-${devcontainerId} の ${devcontainerId} はワークスペースごとに異なる ID が割り当てられる。 つまり 別のフォルダを開くと自動的に別ボリュームになり、~/.claude が完全分離される。 ローカル運用で問題になる「グローバル汚染」がアーキテクチャとして解決されている(公式ドキュメントでも推奨構成として明記されている)。
🗑 ボリューム分離が解決しないもの: バックグラウンドジョブの汚染

${devcontainerId} で分離されるのは ~/.claude の中身(設定・スキル・エージェント)であって、 claude agents(バックグラウンドセッション)の実行状態は別問題。同じボリューム内の ~/.claude/jobs/<id>/ にジョブごとの状態が残り続け、使い終わっても自動では消えない。

  • blocked 状態のまま何ヶ月も放置されるジョブができる
  • supervisor daemon は「予期せず終了した」プロセスを再起動する。kill <pid> で止めても再起動されることがあるので、claude stop を使う
  • 状態確認は claude agents --json --all や claude daemon status
  • 停止は claude stop <id>(claude kill も可)、一覧からの削除は claude rm <id>、全体を止めるなら claude daemon stop --any(いずれも公式ドキュメントに記載)。claude stop が再起動と競合して取り消される不具合は v2.1.199 で修正済み
  • 確実に止めるには対話TUI(claude agents または claude --resume <sessionId>)での操作が必要な場合がある
⚠️ Docker をやめても解決しない
この汚染は Claude Code 本体のバックグラウンドエージェント機構(daemon/jobs)の挙動であり、コンテナ運用をやめて /sandbox や @anthropic-ai/sandbox-runtime(Docker 不要のプロセス隔離、サンドボックスガイド参照)に移行しても変わらない。 運用で使い終わったジョブをこまめに閉じるしかない。
06 — ローカル運用でも汚染を防ぐ方法

現場がローカル運用を続ける場合、以下の方法で ~/.claude 汚染を最小化できる。

01 CLAUDE_CONFIG_DIR 環境変数でプロジェクトごとに分離 ▼
# .envrc や .zshrc に書く
export CLAUDE_CONFIG_DIR=/path/to/project/.claude-config

# または direnv を使う場合
# .envrc
export CLAUDE_CONFIG_DIR=$(pwd)/.claude-config

これで ~/.claude を使わず、プロジェクトローカルの設定ディレクトリを使うようになる。.gitignore に .claude-config/ を追加すること。

  • プロジェクトの .claude/settings.json の env では設定できない(シェル・ユーザー設定・管理設定で設定する)
  • ~/.claude.json の内容(アカウント情報・MCP・信頼したフォルダ)もこのディレクトリに移る
  • バックグラウンドセッションの supervisor も別のものになり、claude agents の一覧が分かれる
📂 グローバル CLAUDE.md の最小化・個人設定の分離・@import での分割管理
これらは環境(コンテナ/ローカル)を問わない汚染対策なので コンテキスト管理ガイド にまとめた。 やりがちな汚染パターン・判断ツリー・既存設定の棚卸しチェックまで含めて解説している。
07 — 運用チェックリスト
🐳 コンテナ運用セットアップ
  • 済devcontainer.json でボリューム分離設定済み
  • 済init-firewall.sh で iptables allowlist 構成済み
  • 済postStart で毎回ファイアウォール初期化
  • TODOCLAUDE_CODE_VERSION=latest → 特定バージョンに固定し、containerEnv に DISABLE_AUTOUPDATER=1 を設定(再現性確保)
  • TODOnode:20 → node:24 以上に更新(Node 20 は 2026-04-30 に EOL。-slim を使う場合は git などを apt で追加する)
  • OPTip6tables ルール追加(IPv6 対応が必要な場合)
  • OPTrenovate / dependabot で Claude Code バージョン自動追従
  • TODO使い終わった claude agents バックグラウンドジョブは claude stop <id> で止め、claude rm <id> で一覧から消す(~/.claude/jobs/ を手で消さない)
  • OPT定期的に claude agents --json --all で棚卸し(blocked/done放置の掃除)
📂 コンテキスト管理セットアップ

CLAUDE.md・settings.json・Skills の置き場所チェックリストは コンテキスト管理ガイドの棚卸しチェック を参照。

  • 済~/.claude/CLAUDE.md に全 PJ 共通ルールのみ記載
  • 済/workspace/CLAUDE.md にプロジェクト固有ルール
08 — 現場への展開参考
観点 コンテナ(現在) ローカル(現場) ローカル + CLAUDE_CONFIG_DIR
~/.claude 汚染 なし(devcontainerId で分離) 発生しやすい なし(PJ ごとに分離)
環境の再現性 高い(Dockerfile で固定) 低い(OS 依存) 中(設定のみ分離)
ネットワーク制限 iptables allowlist なし なし
導入コスト 中(Docker Desktop 要) 低(即開始) 低(env var 1行)
起動時間 初回 1〜2 分、以降数秒 即時 即時
推奨場面 長期 PJ・セキュリティ重視 一時作業・素早い検証 現場の暫定対策として

最終更新: 2026-11-02 公式ドキュメント・CHANGELOG と照合 · Claude Code changelog・公式 Docs(devcontainer / claude-directory)・GitHub Issues・実運用での動作確認を参照