サンドボックス完全ガイド -- 基礎からClaude Codeの実践設定まで

サンドボックスとは何か、なぜ必要か、どう使うかを初心者向けに徹底解説。localhostから外部APIのテストモード、Claude Codeの3層サンドボックス構造と設定方法まで、段階的に理解できます。

田中俊輔2026年3月26日16分で読める

Claude / Claude Code 開発・エンジニアリング業務全般

はじめに -- サンドボックスって何？

「サンドボックス」という言葉を聞いたことはありますか？

開発の記事やClaude Codeのドキュメントで見かけるものの、「自分には関係ない」「よく分からないから後回し」と思っている方も多いのではないでしょうか。

実は、サンドボックスの考え方は非常にシンプルです。一言でいえば、「失敗しても大丈夫な、安全な実験場」 のことです。

子どもが砂場（sandbox）で自由に遊ぶように、何を作っても壊しても、砂場の外の世界には影響がない。これがサンドボックスの本質です。

iこの記事のゴール

この記事を読み終えると、以下のことが分かるようになります。

サンドボックスとは何か、なぜ必要なのか
自分の開発レベルに合ったサンドボックスの使い方
Claude Codeにおけるサンドボックスの仕組みと設定方法
「今すぐやるべきこと」と「将来必要になること」の判断基準

実は、あなたはすでにサンドボックスを使っている

いきなり結論ですが、Vibe Codingで開発を始めたあなたは、すでにサンドボックスの恩恵を受けています。

普段の開発フローを振り返ってみてください。

開発 → 確認 → デプロイの流れ

ステップ1: localhost で開発する

bash

npm run dev

自分のPCで開発サーバーを立ち上げる。この時点で、本番サイトには一切影響がありません。つまり、localhost 自体が「隔離された実験場＝サンドボックス」の役割を果たしています。

ステップ2: ブラウザで動作確認する

ブラウザで http://localhost:3000 を開いて、見た目や機能をチェックします。これはサンドボックスの中でテストしている状態です。ユーザーには見えず、安全に確認作業ができます。

ステップ3: 問題なければデプロイする

確認が終わったものだけを、Vercel等で本番環境に反映します。これが「サンドボックスから本番への移行」です。

!ポイント

個人開発や小規模開発では、localhost 自体がサンドボックスの役割を果たしています。だから「サンドボックスを別途用意する」必要があまりありません。サンドボックスという言葉に馴染みがなくて当然です。

3つのレベル -- 規模によってサンドボックスの形が変わる

サンドボックスの形は、開発の規模によって変わります。今の自分がどこにいるのかを把握しておくと、将来チーム開発や外部API連携に進んだときにスムーズです。

Lv.1: 個人開発・小規模

localhost（サンドボックス）  →  本番（Vercel等）

localhost がサンドボックス
今のあなたの運用です。これで十分安全です

Lv.2: チーム開発・中規模

localhost（個人の実験場）  →  dev環境  →  staging環境  →  本番

dev / staging サーバーがサンドボックスの役割を担います
複数人が同時に開発するので、個人の localhost だけでは足りなくなります。共有のテスト環境（dev/staging）が「サンドボックス」になります

Lv.3: 大規模・エンタープライズ

localhost  →  dev環境  →  sandbox環境（外部API連携テスト）  →  staging環境  →  本番

API提供側が用意するテスト環境がサンドボックスです
決済APIや行政APIなど外部システムとの連携テスト用に、API提供側が「サンドボックス環境」を用意しています。ここで偽のデータを使って安全にテストします

i「sandbox」と「テスト環境」の違いは？

技術的に明確な線引きはありません。ただ、一般的に「sandbox」は外部のAPI提供者が用意したテスト環境を指すことが多く、「dev環境」「staging環境」は自分たちで構築するテスト環境を指します。どちらも「本番に影響を与えない安全な環境」という意味では同じです。

実務での使い方 -- 具体的な場面

「サンドボックスが本当に役立つのはどんなとき？」を、具体的な例で見てみましょう。

決済APIのテスト（Stripe / PayPal）

テストで本当にお金を引き落としたら大変です。Stripeはこの問題を解決するために「テストモード」というサンドボックスを提供しています。

偽のカード番号で決済フローを安全にテストできます。

bash

# .env.local
# テスト用キー（お金は動かない）
STRIPE_SECRET_KEY=sk_test_xxxx

# 本番用キー（実際に決済される）
# STRIPE_SECRET_KEY=sk_live_xxxx

開発中は sk_test_ で始まるテスト用キーを使います。本番にデプロイするときだけ sk_live_ のキーに切り替えます。この切り替えの仕組みが、サンドボックスの基本的な設計パターンです。

メッセージングAPIの開発（LINE / X）

開発中に、フォロワー全員にテストメッセージを送ってしまったら事故になります。

開発用のBotアカウントやテスト環境を使えば、本番のユーザーには一切影響しません。

bash

# .env.local
# 開発用トークン（テスト用Botに送信される）
LINE_CHANNEL_TOKEN=test_xxx

# 本番用トークン（実際のユーザーに送信される）
# LINE_CHANNEL_TOKEN=prod_xxx

ブラウザのサンドボックス

実は、あなたが毎日使っているブラウザにもサンドボックスが組み込まれています。

サンドボックスがなければ、悪意あるWebサイトがPC内のファイルを盗み出す可能性があります。ブラウザはWebページを「サンドボックス」の中で実行することで、WebサイトのJavaScriptがPC内のファイルにアクセスできないようにしています。

html

<!-- HTML の iframe にもサンドボックス属性がある -->
<iframe sandbox="allow-scripts">
  <!-- この中のコードは制限された環境で実行される -->
</iframe>

iサンドボックスの共通パターン

決済API、メッセージングAPI、ブラウザ。分野は違いますが、サンドボックスの考え方は共通しています。「本番のデータやユーザーに影響を与えずに、安全にテスト・実行する仕組み」です。

「サンドボックスを設定しておく」が重要になる場面

ネット記事で「サンドボックスの設定が重要」と書かれているのを見かけたとき、それは主に以下の3つの場面を指しています。

パターン1: 外部APIのテストモード設定

項目	内容
いつ？	Stripe、PayPal、LINE API などを使うとき
何をする？	API側が用意しているテスト用キーを `.env.local` に設定して、開発中は自動的にテストモードで動くようにする
なぜ重要？	設定し忘れると、開発中に本番のAPIを叩いてしまう

パターン2: CI/CDのテスト環境構築

項目	内容
いつ？	GitHub Actions、Vercel Preview などを使うとき
何をする？	プルリクエストごとに自動でプレビュー環境（＝サンドボックス）を作る設定
なぜ重要？	チーム開発で「各自のlocalhostでOKでした」は信用できない

パターン3: セキュリティのサンドボックス化

項目	内容
いつ？	ユーザーがコードを入力するアプリ、iframe を使うとき
何をする？	ユーザーの入力したコードが本体のシステムに影響しないよう、隔離して実行する設定
なぜ重要？	悪意あるコードでシステムを乗っ取られる危険がある

!今のあなたに必要なこと

今の運用（localhost で開発 → Vercel にデプロイ）で問題ありません。外部APIを使い始めたタイミングで「テストモードの設定」を意識すればOKです。

Claude Code編 -- AIエージェント時代のサンドボックス

ここからが、Vibe Codingをしているあなたに最も関係のある内容です。Claude Codeを使った開発では、サンドボックスの考え方がこれまでとは少し違う意味で重要になります。

なぜClaude Codeにサンドボックスが必要？

人間が開発するときとAIが開発するときには、決定的な違いがあります。

	人間が開発	AIが開発
ファイル削除	`rm` を打つ前に考える	悪意あるコードに騙される可能性がある
機密ファイル	怪しいファイルは開かない	SSH鍵や .env を読める状態にある
意図しない操作	意図しない操作はしない	意図せずファイルを削除する可能性がある

人間は「何をするか自分で判断」できますが、Claude Code は「AIが自律的にコマンドを実行」します。だからこそ、AIにも行動範囲の制限＝サンドボックスが必要なのです。

!誤解しないでください

Claude Code が危険だという話ではありません。Claude Code はデフォルトでも安全に設計されています。ここで説明するのは、「さらに安心して使うための追加設定」です。車にシートベルトがあるのと同じように、安全装置を重ねることでリスクを限りなくゼロに近づけます。

Claude Codeの3層サンドボックス構造

Claude Code には、安全性を確保するための3つの層が用意されています。内側から順に見ていきましょう。

第1層: Permission（許可制）-- 玄関の鍵

Claude Code はコマンドを実行する前に「これを実行してもいいですか？」とあなたに確認を求めます。

これがデフォルトで有効になっている最初の防御層です。何かを実行するたびに、あなたの承認が必要です。

家に例えるなら「玄関の鍵」です。来訪者（Claude Code の操作）がドアを開ける前に、必ずあなたが鍵を開ける必要があります。

第2層: Allow / Deny ルール -- 入っていい部屋リスト

settings.json というファイルに、「常にOK」「絶対NG」なコマンドを事前に定義できます。

npm run test → 常にOK（毎回聞かれるのは面倒）
rm -rf → 絶対NG（どんな理由でも実行させない）

家に例えるなら「入っていい部屋リスト」です。「リビングは自由にどうぞ、金庫の部屋は絶対ダメ」とルールを決めておくことで、毎回許可を出す手間が省けます。

第3層: Sandbox（OS隔離）-- 家全体を防犯ガラスで囲む

/sandbox コマンドで有効化できる最も強力な防御層です。OSレベルでファイルアクセスやネットワーク通信を隔離します。

macOS では Seatbelt（Apple のサンドボックス技術）を使用
Linux では Bubblewrap（コンテナ型の隔離技術）を使用

家に例えるなら「家全体を防犯ガラスで囲む」ようなものです。たとえ家の中で何が起きても、外の世界には絶対に影響が出ません。

i3つの層が重なる意味

この3層は独立ではなく、重なり合って機能します。たとえAIが悪意あるプロンプトに騙されたとしても、第1層で止まる。第1層を突破しても第2層で止まる。第2層も突破しても第3層で止まる。このように多重防御することで、「たとえAIが騙されても被害が出ない」状態を作ります。

具体的な設定方法

実際にClaude Codeのサンドボックスを設定してみましょう。ステップごとに進めます。

STEP 1: サンドボックスを有効化する

Claude Code を起動した後、以下のコマンドを入力します。

bash

/sandbox

メニューが表示されるので、「Auto-allow」モードを選択します。サンドボックス内で安全と判断されたコマンドは自動承認されるようになり、許可プロンプトが約84%減少します。

つまり、安全性を高めながら操作の手間も大幅に減るということです。

STEP 2: settings.json でルールを定義する

より細かくコントロールしたい場合は、settings.json にルールを書きます。

ファイルの場所は ~/.claude/settings.json（グローバル設定）です。

json

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff:*)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo:*)",
      "Read(**/.env)",
      "Bash(git push --force *)"
    ]
  }
}

このルールの意味を整理します。

ルール	動作	説明
`allow` に書いたもの	自動承認	いちいち確認されない。よく使う安全なコマンドを登録する
`deny` に書いたもの	絶対禁止	どんな理由があっても実行されない。危険なコマンドを登録する
どちらにも書いていないもの	都度確認	従来どおり「実行してもいいですか？」と聞かれる

!deny は allow より常に優先されます

もし同じコマンドが allow と deny の両方に書かれていた場合、deny が勝ちます。安全側に倒す設計です。

STEP 3: プロジェクト別にも設定する（応用）

プロジェクトのルートに .claude/settings.json を置くと、そのプロジェクト専用のルールを定義できます。Gitで管理すれば、チームメンバーと共有することも可能です。

my-project/
├── .claude/
│   └── settings.json    ← プロジェクト専用ルール
├── src/
└── package.json

プロジェクト設定について、2つの重要なポイントがあります。

プロジェクトの deny ルールは、グローバル設定に追加されます。 プロジェクト固有の禁止事項を追加できます
プロジェクトの allow ルールは、グローバル設定の範囲を超えられません。 グローバルで禁止しているものを、プロジェクト設定で許可することはできません

!初心者へのおすすめ

まずはグローバル設定（~/.claude/settings.json）だけで十分です。プロジェクト別の設定は、複数のプロジェクトを扱うようになってから検討してください。

あなたの場合、いつ設定すべき？

「結局、自分は今すぐ設定すべき？」という疑問に、場面ごとに答えます。

シナリオ	判断	やるべきこと
普段の開発（個人プロジェクト）	今のままでOK	デフォルトのPermission制（都度確認）で十分安全です。気になれば `/sandbox` を有効化するとさらに安心です
クライアントの本番環境を触るとき	設定を推奨	`deny` ルールで `rm -rf`、`git push --force`、`.env` 読み取りを禁止します。万が一の事故を防ぐ保険です
自動化（CI/CD、長時間タスク）	必ず設定	`--dangerously-skip-permissions` を使うなら、必ずDockerコンテナ内で実行します。コンテナ自体がサンドボックスの役割を果たします
API連携でAPIキーを扱うとき	設定を推奨	`.env` ファイルを `deny` ルールで保護します。APIキーをClaude Codeが読み出すリスクを排除します

まとめ

この記事のポイントを振り返ります。

サンドボックスとは「失敗しても大丈夫な、安全な実験場」です。

個人開発では、localhost 自体がサンドボックスの役割を果たしています。 今の運用で安全に開発できています
外部APIを使うときは、テストモード（サンドボックス）の設定が重要です。 開発用キーと本番用キーを分けて管理します
Claude Codeには、3層のサンドボックス構造が用意されています。 Permission（許可制）、Allow/Denyルール、OS隔離の3段階で守られています
AIに任せる範囲が広がるほど、サンドボックスの重要性は増していきます。 今は必要最小限でも、成長に合わせて設定を強化していきましょう

!今すぐできるアクション

Claude Code で /sandbox と入力してみてください。それだけで、安全性が一段階上がります。慣れてきたら settings.json で自分なりのルールを追加していきましょう。

次のステップ

サンドボックスの基礎が理解できたら、次はClaude Codeの設定をさらに深く学んでいきましょう。

.claude/ フォルダ完全解剖ガイド -- CLAUDE.md やカスタムコマンドなど、Claude Codeの設定全体を体系的に理解できます
Claude Code ネイティブ版セットアップガイド -- Claude Codeのインストールがまだの方はこちらから