コンテナ運用 & 永続化設計ガイド
Claude Code / Codex をコンテナで使う理由・ボリューム設計・運用ベストプラクティス
内容の最終更新: 2026-11-02(公式ドキュメント・CHANGELOG と照合)
~/.claude は Named Volume でプロジェクト完全分離。ローカルの汚染問題がそもそも発生しない
~/.claude/jobs のバックグラウンドジョブ状態は自動では掃除されない。claude stop <id> で止めて claude rm <id> で一覧から消す
- ~/.claude がプロジェクトごとに完全分離
- iptables でネットワークを allowlist 制限
- ホストの npm / Node.js 環境を汚染しない
- チームで同一環境を再現できる
- devcontainerId でボリュームが自動分離
- ホスト OS クラッシュリスクをコンテナに閉じ込め
- ~/.claude がプロジェクト横断で汚染される
- グローバル CLAUDE.md に何でも書いてしまう
- ネットワーク制限がない(デフォルト無制限)
- Node.js バージョン衝突の可能性
- 組み込みのサンドボックスは既定でオフ(
/sandboxかsandbox.enabled: trueで有効にする。macOS では Seatbelt を使う) - 環境差異でチームと挙動が変わることがある
Layer 1Claude Code 組み込みの sandbox。コンテナ内では bubblewrap を入れ子にできないため、必要な場合は enableWeakerNestedSandbox で弱めて動かす
Layer 2iptables の allowlist(init-firewall.sh)
- 許可: api.anthropic.com・npmjs.org・GitHub など
- 拒否: それ以外のすべての外向き通信
- 検証: example.com に繋がらないことを確認
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 で毎回初期化・検証
- IPv6 未対応 —
ip6tablesルールなし。このコンテナは IPv6 なし(loのみ)なので現状問題なし - DNS TOCTOU — 起動時 IP を ipset に登録するが、CDN の IP ローテーション後は新規接続が DROP される可能性
- WebFetch ツール — WebFetch は Bash のサンドボックスの
allowedDomainsの対象外で、WebFetch(domain:...)の権限ルールで制御する。Claude Code のプロセスから直接通信するので、コンテナの iptables は WebFetch にも適用される
settings.json 経由のサンドボックス脱出(Configuration Injection)。なお SOCKS5 の null-byte によるネットワーク許可リストの回避は別の問題で、二次情報では v2.1.90 で修正されたとされる(公式のアドバイザリ・CVE はなし)。
sandbox.bwrapPath / sandbox.socatPath でカスタムバイナリパスを指定可能に。非標準インストール環境に対応。
find コマンドが macOS の vnode テーブルを枯渇させホストをクラッシュさせるバグを修正。
$TMPDIR がサンドボックス外のコマンドにも /tmp/claude-{uid} で上書きされる不具合を修正(bazel / EDR 保護環境で影響)。
.claude/settings.json が絶対パスのシンボリックリンクの場合に Linux sandbox が起動失敗するバグを修正。
/sandbox コマンドが Linux の依存(bubblewrap / socat / seccomp)を表示してしまう問題。報告と同日にクローズされている。
# 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 のたびに消える。
- settings.json(権限・hooks・sandbox設定)
- skills/ (インストール済みスキル)
- agents/ (カスタムサブエージェント)
- projects/<project>/*.jsonl (会話の記録、--resume 用。
cleanupPeriodDays(既定30日)を過ぎると自動削除) - projects/<project>/memory/ (Auto Memory)
- zsh コマンド履歴
- /workspace/CLAUDE.md(プロジェクト設定)
- /workspace/CLAUDE.local.md(個人設定)
- /workspace/.claude/settings.json
- /workspace/.claude/skills/
- /workspace/.claude/agents/
- ソースコード全体
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>)での操作が必要な場合がある
/sandbox や @anthropic-ai/sandbox-runtime(Docker 不要のプロセス隔離、サンドボックスガイド参照)に移行しても変わらない。
運用で使い終わったジョブをこまめに閉じるしかない。
現場がローカル運用を続ける場合、以下の方法で ~/.claude 汚染を最小化できる。
# .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の一覧が分かれる
- 済devcontainer.json でボリューム分離設定済み
- 済init-firewall.sh で iptables allowlist 構成済み
- 済postStart で毎回ファイアウォール初期化
- TODO
CLAUDE_CODE_VERSION=latest→ 特定バージョンに固定し、containerEnvにDISABLE_AUTOUPDATER=1を設定(再現性確保) - TODO
node: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 にプロジェクト固有ルール
| 観点 | コンテナ(現在) | ローカル(現場) | ローカル + 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・実運用での動作確認を参照