> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langbot.app/llms.txt
> Use this file to discover all available pages before exploring further.

# サンドボックス (Sandbox)

> LangBot サンドボックス（Box Runtime）は内蔵 Agent に隔離環境を提供し、安全にコマンド実行やファイル編集を可能に。

サンドボックスは組み込み Agent に隔離された実行環境を提供します。コマンドの実行、ファイルの読み書き、長期常駐プロセスの実行が可能です。日常的な Agent 用途（データ処理、ファイル操作、ユーザーコードの実行、stdio MCP のホスティング）はすべてこれに依存します。

サンドボックスを有効化すると、組み込み Agent は自動的に 6 つのツールを取得します。パイプラインで個別に有効化する必要はありません。

## 組み込みツール

| ツール     | 用途                      |
| ------- | ----------------------- |
| `exec`  | サンドボックス内で Shell コマンドを実行 |
| `read`  | ワークスペースのファイルを読み取る       |
| `write` | ファイルを作成または上書き           |
| `edit`  | 文字列置換でファイルを編集           |
| `glob`  | glob パターンでファイルを検索       |
| `grep`  | 正規表現でファイル内容を検索          |

`exec` はサンドボックスコンテナ内で実行されます。残り 5 つはホスト側の `/workspace` にマッピングされたディレクトリを直接読み書きします。

<Note>
  これらのツールは組み込み Agent 向けです。Dify、n8n、Langflow、Coze などの外部 Runner を使用する場合は、各プラットフォーム独自のツール機構を利用してください。
</Note>

## サンドボックススコープ

パイプラインの AI 設定で、メッセージ間でサンドボックスをどのように共有するかを選べます。デフォルトの「チャットごと」で多くのシナリオに対応できます。

| スコープ          | テンプレート                                            | 共有範囲                  |
| ------------- | ------------------------------------------------- | --------------------- |
| グローバル         | `{global}`                                        | 全ユーザーが 1 つのサンドボックスを共有 |
| チャットごと（デフォルト） | `{launcher_type}_{launcher_id}`                   | 同じグループ／個人チャットで共有      |
| ユーザーごと        | `{launcher_type}_{launcher_id}_{sender_id}`       | グループ内の各メンバーが独立        |
| 会話ごと          | `{launcher_type}_{launcher_id}_{conversation_id}` | 会話単位で隔離               |
| メッセージごと       | `{query_id}`                                      | 完全にステートレス             |

<Warning>
  同一スコープ内のコマンドはファイルシステム状態を共有します。完全な隔離が必要な場合は「メッセージごと」を選択してください。
</Warning>

## ライフサイクル

| 状況                               | 動作                    |
| -------------------------------- | --------------------- |
| 5 分以上アイドル                        | 自動クリーンアップ             |
| Box がホストするプロセス（stdio MCP など）が稼働中 | クリーンアップしない。プロセス終了後に解放 |
| `persistent: true` 設定時           | 自動クリーンアップなし           |

## クイックスタート

1. **バックエンドの準備**: ローカルに Docker をインストール、または Nsjail / E2B を選択
2. **`config.yaml` に記述**:
   ```yaml theme={null}
   box:
     enabled: true
     backend: 'local'
     local:
       host_root: './data/box'
   ```
3. **LangBot を起動**: サンドボックスは自動的に有効化
4. **パイプラインで** 組み込み Agent と関数呼び出し対応モデルを選択

その後、Agent は自動的に 6 つのツールを取得します。詳細な設定は [サンドボックス設定](./config) を参照してください。

## サンドボックスを無効化する

`box.enabled: false` を設定します。サンドボックスに依存するすべての機能（組み込みツール、Skill の作成／編集／起動、stdio MCP）が同時に無効になります。http/sse モードの MCP は影響を受けません。

## 次のステップ

* [サンドボックス設定](./config) — バックエンド、セキュリティプリセット、マウント、環境変数
* [ランタイムと拡張機能の関係](./runtime-relationships) — サンドボックス、Skills、MCP、プラグインの役割分担