> ## 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.

# サンドボックス設定

> LangBot サンドボックス（Box Runtime）を設定。隔離されたコード実行バックエンド（Docker・nsjail・E2B）を構成。

サンドボックス設定は LangBot メインプロセスが管理し、Box Runtime が実際の実行を担当します。通常のデプロイでは、バックエンド、ワークスペースディレクトリ、セキュリティプロファイルだけを決めれば十分です。

<Note>
  このページの `box.*` 設定はすべて `data/config.yaml` に記述します。ファイルの場所と読み込みの仕組みは[システム環境設定](../../deploy/settings)を参照してください。
</Note>

## 推奨設定

```yaml theme={null}
box:
  enabled: true
  backend: 'local'        # Docker / Nsjail から利用可能なものを自動選択
  local:
    profile: 'default'
    host_root: './data/box'
    skills_root: 'skills'
  docker:
    cpu_limit_enabled: true
```

* `enabled`：サンドボックスのマスタースイッチ。`false` にすると、サンドボックス組み込みツール、Skill の追加 / 編集、stdio MCP のホスティングなど Box 依存の機能はすべて無効になります。
* `backend`：下記「バックエンドの選択」を参照。
* `local.profile`：セキュリティプロファイル。ネットワーク、マウント、リソース制限を制御。
* `local.host_root`：ホスト側のサンドボックス作業ディレクトリ。サンドボックス内では `/workspace` にマウントされます。
* `local.skills_root`：Skill パッケージのディレクトリ。相対パスは `host_root` 配下に解決され、デフォルトは `host_root/skills`。
* `docker.cpu_limit_enabled`：Docker サンドボックスコンテナに CPU 制限を付けるかどうか。`false` にすると `docker run --cpus` を省略し、メモリと PID 制限は維持します。

<Note>
  Skill は Box Runtime が管理する skill store からのみ読み込まれます。Box Runtime またはバックエンドが利用できない場合、Skill 一覧は空になり、追加 / 編集 / `register_skill` も使えません。`data/skills/` へのフォールバックは行いません。
</Note>

## バックエンドの選択

サンドボックスは**ローカルコンテナ**または**クラウド**で動作させられます。`box.backend` でどちらを使うかを指定します：

| `backend`   | 実行場所     | 動作                                              |
| ----------- | -------- | ----------------------------------------------- |
| `local`（既定） | ローカルコンテナ | Docker / Nsjail から利用可能なものを自動選択（Docker 優先）       |
| `docker`    | ローカルコンテナ | Docker を強制使用。Docker daemon が必要                  |
| `nsjail`    | ローカルコンテナ | Nsjail を強制使用（Linux のみ）。カスタムイメージ非対応              |
| `e2b`       | クラウド     | [E2B](https://e2b.dev) クラウドサンドボックスを使用。API キーが必要 |

`local` は「自動選択」のショートハンドであり、`docker` / `nsjail` と並列の 4 つ目のバックエンドではありません。ローカル系バックエンド（`local` / `docker` / `nsjail`）は `box.local.*` 設定セクションを**共有**し、クラウドバックエンドは `box.e2b.*` を使います。

<Note>
  `backend` は強制値です。`docker` を指定して Docker が使えない場合、Nsjail や E2B に**自動でフォールバックしません**。自動 fan-out するのは `local` だけです。

  環境変数 `BOX__BACKEND` で `box.backend` を上書きできます（`config.yaml` より優先）。
</Note>

## セキュリティプロファイル

`box.local.profile` はローカル系バックエンドのネットワーク、マウント、リソース制限を制御します：

| Profile            | ネットワーク   | マウント   | リソース | 推奨シーン               |
| ------------------ | -------- | ------ | ---- | ------------------- |
| `default`          | オフ       | 読み書き   | 既定制限 | 既定の選択               |
| `offline_readonly` | オフ       | 読み取り専用 | より厳格 | 信頼できないファイルの読み込み     |
| `network_basic`    | 基本ネットワーク | 読み書き   | 既定制限 | API アクセス、依存関係インストール |
| `network_extended` | フルネットワーク | 読み書き   | 緩和   | 開発、デバッグ、複雑なタスク      |

最小権限を優先：ネットワークが不要なら `default` または `offline_readonly`；`allowed_mount_roots` には必要なディレクトリのみを追加。

## ローカル系バックエンド設定（box.local.\*）

ローカル系バックエンド（`local` / `docker` / `nsjail`）は以下を共有します：

| 設定項目                        | 既定値           | 説明                                          |
| --------------------------- | ------------- | ------------------------------------------- |
| `local.profile`             | `default`     | 上記「セキュリティプロファイル」を参照                         |
| `local.image`               | 空             | Docker バックエンドのカスタムイメージ。空 = プロファイル既定を使用      |
| `local.host_root`           | `./data/box`  | ホスト作業ディレクトリのベース。サンドボックス内の `/workspace` にマップ |
| `local.default_workspace`   | 空             | 既定ワークスペース名。空 = `<host_root>/default`        |
| `local.skills_root`         | `skills`      | Skill パッケージディレクトリ。相対パスは `host_root` 配下に解決   |
| `local.allowed_mount_roots` | `[host_root]` | Agent がマウント要求できるホストディレクトリの許可リスト             |
| `local.workspace_quota_mb`  | `null`        | ワークスペースのディスク配額（MB）。`null` = プロファイル既定        |

## Docker バックエンド設定（box.docker.\*）

| 設定項目                       | 既定値    | 説明                                                                                                     |
| -------------------------- | ------ | ------------------------------------------------------------------------------------------------------ |
| `docker.cpu_limit_enabled` | `true` | Docker バックエンドのみ有効。`false` の場合、サンドボックスコンテナは `--cpus` なしで起動しますが、`--memory` と `--pids-limit` は引き続き適用されます。 |

## クラウドバックエンド設定（box.e2b.\*）

`backend: 'e2b'` を指定したうえで設定します：

| 設定項目           | 既定値 | 説明                                           |
| -------------- | --- | -------------------------------------------- |
| `e2b.api_key`  | 空   | E2B API キー。環境変数 `E2B_API_KEY` でも設定可          |
| `e2b.api_url`  | 空   | セルフホスト E2B のエンドポイント。環境変数 `E2B_API_URL` でも設定可 |
| `e2b.template` | 空   | 既定の E2B テンプレート ID                            |

E2B はホスト側に Docker や Nsjail を必要とせず、毎回の実行をリモートサンドボックスで行います。

## Docker Compose デプロイ

Docker Compose では、サンドボックス設定は `langbot` サービス側に記述します。LangBot は起動時に INIT RPC で設定を `langbot_box` に転送します。

```yaml theme={null}
services:
  langbot_box:
    image: rockchin/langbot:latest
    container_name: langbot_box
    profiles: ["box", "all"]
    volumes:
      - ${LANGBOT_BOX_ROOT:-${PWD}/data/box}:${LANGBOT_BOX_ROOT:-${PWD}/data/box}
      - /var/run/docker.sock:/var/run/docker.sock
    command: ["uv", "run", "--no-sync", "-m", "langbot_plugin.cli.__init__", "box"]

  langbot:
    image: rockchin/langbot:latest
    volumes:
      - ./data:/app/data
    environment:
      - BOX__LOCAL__HOST_ROOT=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
      - BOX__LOCAL__SKILLS_ROOT=skills
      - BOX__LOCAL__ALLOWED_MOUNT_ROOTS=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
      - BOX__DOCKER__CPU_LIMIT_ENABLED=${LANGBOT_BOX_DOCKER_CPU_LIMIT_ENABLED:-true}
```

<Warning>
  `langbot_box` は Docker daemon にアクセスします。`docker.sock` のマウントは信頼できる環境でのみ行い、Box のルートパスをホストと `langbot_box` コンテナ内で一致させてください。
</Warning>

外部の Box Runtime（リモートホストなど）に接続する場合は `box.runtime.endpoint` で URL を指定します：

```yaml theme={null}
box:
  runtime:
    endpoint: 'ws://192.168.1.10:5410'
```

## 環境変数

| 環境変数                              | 対応する設定                                 |
| --------------------------------- | -------------------------------------- |
| `BOX__ENABLED`                    | `box.enabled`                          |
| `BOX__BACKEND`                    | `box.backend`                          |
| `BOX__LOCAL__PROFILE`             | `box.local.profile`                    |
| `BOX__LOCAL__IMAGE`               | `box.local.image`                      |
| `BOX__LOCAL__HOST_ROOT`           | `box.local.host_root`                  |
| `BOX__LOCAL__DEFAULT_WORKSPACE`   | `box.local.default_workspace`          |
| `BOX__LOCAL__SKILLS_ROOT`         | `box.local.skills_root`                |
| `BOX__LOCAL__ALLOWED_MOUNT_ROOTS` | `box.local.allowed_mount_roots`、カンマ区切り |
| `BOX__LOCAL__WORKSPACE_QUOTA_MB`  | `box.local.workspace_quota_mb`         |
| `BOX__DOCKER__CPU_LIMIT_ENABLED`  | `box.docker.cpu_limit_enabled`         |
| `BOX__E2B__API_KEY`               | `box.e2b.api_key`                      |
| `BOX__E2B__API_URL`               | `box.e2b.api_url`                      |
| `BOX__E2B__TEMPLATE`              | `box.e2b.template`                     |

<Note>
  `langbot_box` サービス側には `BOX__*` や `LANGBOT_BOX_*` を設定しないでください。Box Runtime はこれらを直接読みません——設定は LangBot から INIT RPC 経由で渡されます。
</Note>