Claude Code の sandboxing が来た — WSL2 での導入手順と既存 hooks/permissions との境界

Claude Code に native sandboxing が追加された。Bash ツールの実行を OS レベルで filesystem と network 双方から隔離する仕組みで、Edit/Read/Write などのファイル系ツールには影響しない。本稿は 2026-05-10 時点の公式ドキュメントを起点に、WSL2 環境での導入手順、既存の hooks/permissions との位置関係、運用上の注意点を整理する。

検証日: 2026-05-10（sandboxing docs の改稿に伴い 2026-06-09 に全 citation を再検証・更新）。Claude Code v2.x、WSL2 Ubuntu 24.04 / Linux 6.6 を想定。

何が来たか

公式 docs は Bash sandbox を「The Bash sandbox lets Claude run most shell commands without stopping to ask permission」と説明する。動機は明確で、コマンドごとに承認を求める従来モデルが「approval fatigue（承認疲労）」を招き、結果として注意散漫や生産性低下を生む点にある。それを「事前に boundaries を引いて、その内側では自由に動かす」という設計に置き換える。

実装は OS 機能に依拠し、「sandboxed Bash tool provides filesystem and network isolation」——filesystem と network の両方を隔離する。具体的なバックエンドはプラットフォームごとに異なる。

• macOS: 追加インストール不要。「sandboxing uses the built-in Seatbelt framework」
• Linux / WSL2: 2 パッケージに依存する。bubblewrap（「the unprivileged sandboxing tool that enforces filesystem isolation」）と socat（「the relay used to route network traffic through the sandbox proxy」）
• WSL1: 非対応。「WSL1 is not supported because bubblewrap requires kernel features only available in WSL2」

ネイティブ Windows は 非対応になった。docs は「Native Windows is not supported. On Windows, run Claude Code inside a WSL2 distribution」と明記する。Windows ユーザーは WSL2 ディストリビューション内で Claude Code を動かすのが公式の前提。

filesystem 側のデフォルトは非対称で、書き込みは「commands inside the sandbox can write only to the working directory」（cwd 限定）、読み取りは「read access to the entire computer, except certain denied directories」（原則全 OK、denyRead で塞ぐ）という構造。docs は「この既定では ~/.aws/credentials や ~/.ssh も読めてしまうので、必要なら denyRead に追加せよ」と注意している。

network 側はプロキシ経由で domain allowlist による制御。重要な制約として「The built-in proxy does not terminate or perform TLS inspection on outbound traffic」がある。allowlist は client が伝えるホスト名で判定するため、domain fronting による抜けが発生しうる。脅威モデルが厳しい場合は custom proxy で TLS 終端する設計が推奨されている。

設計思想として「Effective sandboxing requires both filesystem and network isolation」が示されている。filesystem だけ、network だけでは攻撃面が残るため両方を組み合わせる。SSH 鍵の流出阻止には network isolation が、システム改竄阻止には filesystem isolation が必要になる。

WSL2 での導入手順

1. 必要パッケージのインストール

Ubuntu/Debian 系：

sudo apt-get install bubblewrap socat

Fedora 系は sudo dnf install bubblewrap socat。socat も必須なので忘れない。WSL1 で実行すると Sandboxing requires WSL2 というエラーになる。

2. 有効化

「Start a Claude Code session and run the /sandbox command」。セッション内で /sandbox と打つとモード選択パネルが開く。依存パッケージが足りなければ panel に不足が表示される。

/sandbox

モードは 2 種類：

• Auto-allow mode: 「Bash commands will attempt to run inside the sandbox and are automatically allowed without requiring permission」。sandbox 内で実行可能なコマンドは承認プロンプトなしで走る。sandbox の外に出るコマンド（network や非許可パスへのアクセス）だけが従来の permission フローに落ちる
• Regular permissions mode: 「All Bash commands go through the regular permission flow, even when sandboxed」。sandbox 自体は効くが、すべてのコマンドが従来どおり承認を求められる

filesystem と network の制限自体はどちらの mode でも同じで、違うのは「sandbox 内のコマンドを自動承認するかどうか」だけ。auto-allow は permission mode（accept edits 等）とは独立しており、accept edits OFF でも sandbox 範囲内の bash は走る点に注意。

3. 失敗時の挙動

依存欠落や非対応プラットフォームで sandbox が起動できない場合、デフォルトでは「warning を出して非 sandbox で実行」する fallback が動く。これを許さない managed deployment では sandbox.failIfUnavailable を true に設定すると hard fail に切り替わる。

WSL2 特有の落とし穴

WSL2 で sandbox を入れた直後に効いてくるのが Windows binary との関係。docs は明確に「On WSL2, sandboxed commands cannot launch Windows binaries such as cmd.exe, powershell.exe, or anything under /mnt/c/」と書いている。WSL は Windows 側へのハンドオフを Unix socket 経由で行うが、sandbox はこの socket をブロックする。

回避策は excludedCommands で sandbox 外実行を明示する。「If a command needs to invoke a Windows binary, add it to excludedCommands so it runs outside the sandbox」。たとえば /mnt/c/ 配下のスクリプトや clip.exe を呼びたい場合は、それらを除外指定する。

加えて以下のツールは仕様上 sandbox と相性が悪い、という言及がある（公式 docs より）：

• watchman は sandbox 内で動かない。jest を使うなら jest --no-watchman
• docker は sandbox 不互換。docker * を excludedCommands に入れて sandbox 外で走らせる

既存 hooks / permissions との境界

公式 docs の「How sandboxing relates to permissions」節が明快。

「Permission rules control which tools Claude Code can use and are evaluated before any tool runs. They apply to all tools: Bash, Read, Edit, WebFetch, MCP, and others.」

「Sandboxing provides OS-level enforcement that restricts what Bash commands can access at the filesystem and network level. It applies only to Bash commands and their child processes.」

つまり 2 層構造になっている。

• permissions: すべてのツール（Bash・Read・Edit・WebFetch・MCP）に対して、ツール実行前に評価される論理層
• sandbox: Bash とその子プロセスに対してのみ、OS レベルで実行中に強制される物理層

両者は補完関係で、片方を撤去すると穴が開く。たとえば permissions だけだと sandbox を抜けて子プロセスから攻撃できるし、sandbox だけだと Read/Edit ツールが対象外になる。

設定値は以下のように使い分ける（docs 引用）：

• sandbox.filesystem.allowWrite: subprocess に cwd 外の書き込みを許可する path リスト
• sandbox.filesystem.denyWrite / denyRead: 特定 path をブロック
• sandbox.filesystem.allowRead: denyRead で塞いだ範囲の中で再開放
• 既存の Read(...) / Edit(...) permission rule: 特定ファイルへのアクセス制御
• sandbox.allowedDomains / deniedDomains: Bash の network 到達先制御

設定は scope 間でマージされる。「Paths from both sandbox.filesystem settings and permission rules are merged together into the final sandbox configuration」。managed → user → project → local の各層に書いた配列は加算で合流する。

FileChanged などの hooks との関係は、sandbox は Bash ツールの実行ラッパーなので、hook イベントの発火・hook script 実行自体には影響しない。hook script 内で bash を呼ぶ場合、その bash 実行が sandbox 対象になる、という関係。

移行コスト見積もり

WSL2 を主環境にしている開発者にとっての導入コストは中程度。具体的に必要な作業：

1. bubblewrap socat のインストール（5 分）
2. /sandbox で mode 選択（即時）
3. Windows binary を呼ぶスクリプトを excludedCommands に登録（プロジェクトごとに 5-15 分）
4. watchman / docker を使っているなら fallback ルールを excludedCommands で書く
5. 既存の permissions 設定が sandbox.filesystem 設定と衝突していないか確認

導入後の挙動変化として最も大きいのは、Auto-allow mode を有効にすると accept edits 設定と独立に bash が自動承認される点。これを把握せずに有効化すると、想定外の自動実行が起きうる。最初は Regular permissions mode で挙動を確かめてから auto-allow に切り替えるのが安全。

既知の制約（What sandboxing does not cover）

公式 docs が末尾で明示している通り、sandbox は Bash subprocess の隔離に限定される。

• Built-in file tools（Read / Edit / Write）は permission system 直結で、sandbox を経由しない
• Computer use（Claude が画面操作する機能）は sandbox の外、デスクトップ上で動作。アプリごとの permission prompt が境界
• TLS 検査なし: 上述の通り domain fronting に弱い
• Linux nested sandbox の弱体化: Docker 内で動かすため enableWeakerNestedSandbox が用意されているが、「This option considerably weakens security and should only be used when additional isolation is otherwise enforced」と明記
• Performance overhead: 「Minimal, but some filesystem operations may be slightly slower」

ネイティブ Windows は非対応で、Windows では WSL2 内での実行が前提（docs は「On Windows, run Claude Code inside a WSL2 distribution」と指示）。WSL1 も非対応のまま。

ランタイムは OSS

おまけとして、sandbox の primitives は単体 npm パッケージとして公開されている。「available as the standalone @anthropic-ai/sandbox-runtime package」。Claude Code 以外のエージェントや処理を sandbox で包みたい場合の選択肢になる。

npx @anthropic-ai/sandbox-runtime <command-to-sandbox>

まとめ

permissions プロンプトの疲労を OS レベルで解消する 2 層目のセキュリティが入った。WSL2 ユーザーにとっては bubblewrap socat 入れて /sandbox を打つだけで導入できるが、/mnt/c/ や Windows binary を踏むワークフローを持つなら excludedCommands の整備が必須。Auto-allow mode は便利だが accept edits とは独立に bash を自動実行するので、最初は Regular permissions mode で挙動を確かめる順序が安全。

References

[1] Claude Code Sandboxing — https://code.claude.com/docs/en/sandboxing

---

この docs 追従を自動化するツールを作っています

本稿のような公式 docs の追従を手作業で続けるのは骨が折れます。docs-first では、公式ドキュメントの更新を検知して ~/.claude 環境への改善提案を逐語検証つきで配信するツール env-coach を準備中です（導入パッケージ＋アップデート購読の二本立て）。

関心のある方は登録をどうぞ → https://note.com/docsfirst/n/n8159d74b3ed7