---
title: "サンドボックス (Sandbox)"
description: "LangBot Box Runtime は組み込み Agent にコマンド・ファイルツールを提供し、サンドボックスまたは信頼済み Host バックエンドを選択可能。"
---

Box Runtime は組み込み Agent に、コマンド実行、ファイルの読み書き、長期常駐プロセスの実行を行う統一インターフェースを提供します。日常的な Agent 用途（データ処理、ファイル操作、ユーザーコードの実行、stdio MCP のホスティング）はすべてこれに依存します。Docker、nsjail、E2B はサンドボックス隔離を提供しますが、明示的に選択する Host バックエンドは信頼できるローカル開発向けで、隔離は提供しません。

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

## 組み込みツール

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

`exec` は選択した Box バックエンドで実行されます。残り 5 つは `/workspace` にマッピングされたワークスペースディレクトリを直接読み書きします。Host を選択した場合、コマンドも Box Runtime ホスト上で直接実行されます。

<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>
同一スコープ内のコマンドはファイルシステム状態を共有します。独立したワークスペースが必要な場合は「メッセージごと」を選択してください。スコープはセッション再利用の規則であり、セキュリティ境界ではありません。Host では異なるスコープを使ってもホストレベルの隔離はありません。
</Warning>

## ライフサイクル

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

これらのライフサイクル規則は Host にも適用されます。クリーンアップ時にはセッションの管理対象プロセスツリーを終了し、一時セッションディレクトリを削除します。`box.local.host_root` 配下にマッピングされた永続ワークスペースは一時状態として削除されません。Runtime 終了時や明示的なセッション削除時にもクリーンアップが行われます。

## クイックスタート

Linux / macOS 上の信頼できるローカル開発では、Docker をインストールせず Host を選択できます：

1. **`config.yaml` に記述**:
   ```yaml
   box:
     enabled: true
     backend: 'host'
     local:
       host_root: './data/box'
   ```
2. **LangBot を起動**: Box Runtime は自動的に有効化
3. **パイプラインで** 組み込み Agent と関数呼び出し対応モデルを選択

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

<Warning>
Host は LangBot / Box Runtime ユーザーの権限でコマンドを直接実行するため、信頼できる入力だけを扱ってください。信頼できないコードを実行する場合は、`backend` を `local`（Docker / Nsjail の自動選択）、`docker`、`nsjail`、または `e2b` に設定してください。
</Warning>

## Box を無効化する

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

## 次のステップ

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