xinyin025/LangBot
1
0
Fork 0
mirror of https://github.com/langbot-app/LangBot.git synced 2026-10-29 20:05:25 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #115 from langbot-app/feat/host-box-backend-docs

Browse Source 
docs(box): document explicit host backend
This commit is contained in:
huanghuoguoguo
2026-09-02 22:27:27 +08:00
committed by GitHub
parent f4674a48ac
commit a17fe6dfa9
9 changed files with 225 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files
en/usage/sandbox/config.mdx
+50 -10
View File
@@ -1,9 +1,9 @@
---
title: "Sandbox Configuration"
description: "Configure the LangBot sandbox (Box Runtime). Set up isolated code execution backends: Docker, nsjail or E2B."
description: "Configure LangBot Box Runtime with Docker, nsjail, E2B, or the explicitly enabled non-isolated Host backend."
---
Sandbox settings are owned by the LangBot main process; Box Runtime performs the actual execution. For most deployments, you only need to choose a backend, set the workspace directory, and pick a security profile.
Box settings are owned by the LangBot main process; Box Runtime performs the actual execution. For most deployments, you only need to choose a backend, set the workspace directory, and pick a security profile. Docker, nsjail, and E2B provide sandbox environments; the Host backend runs commands directly on the Box Runtime host.
<Note>
All `box.*` settings on this page live in `data/config.yaml`. See [System Environment Settings](../../deploy/settings) for the file's location and how it's loaded.
@@ -36,7 +36,7 @@ Skills are loaded only from the Box-managed skill store. When Box Runtime or the
## Backend Selection
The sandbox can run on **local containers** or **in the cloud**. `box.backend` picks which:
Box can run in **local containers**, in a **cloud sandbox**, or as a **process on the Box Runtime host**. `box.backend` picks which:
| `backend` | Where it runs | Behavior |
|-----------|---------------|----------|
@@ -44,8 +44,13 @@ The sandbox can run on **local containers** or **in the cloud**. `box.backend` p
| `docker` | Local containers | Force Docker; requires the Docker daemon |
| `nsjail` | Local containers | Force Nsjail (Linux only); no custom image support |
| `e2b` | Cloud | Use [E2B](https://e2b.dev) cloud sandbox; requires API key |
| `host` | Box Runtime host | Start local processes with the Box Runtime user's permissions; requires POSIX and `sh` |
`local` is shorthand for "auto-pick", not a fourth backend sitting next to `docker`/`nsjail`. The local backends (`local`/`docker`/`nsjail`) **share** the `box.local.*` config section; the cloud backend uses `box.e2b.*`.
`local` is shorthand for "auto-pick", not a fourth backend sitting next to `docker`/`nsjail`. It only tries Docker and Nsjail and **never auto-selects `host`**. Local backends use workspace settings from `box.local.*`; the cloud backend uses `box.e2b.*`.
<Warning>
`host` is **not a sandbox**. Commands have the Box Runtime user's host permissions, with no filesystem, process, network, namespace, cgroup, rootfs, or image isolation. Read-only mounts and hard disk quotas are not guaranteed. Use it only for single-user local development with trusted input; never use it for public services, shared hosts, or untrusted code.
</Warning>
<Note>
`backend` is a hard selection. Setting `docker` and finding Docker unavailable does **not** fall back to Nsjail or E2B — only `local` auto-fans-out.
@@ -55,7 +60,7 @@ The sandbox can run on **local containers** or **in the cloud**. `box.backend` p
## Security Profiles
`box.local.profile` controls network, mounts, and resource limits for local backends:
`box.local.profile` controls network, mounts, and resource limits for the Docker / Nsjail local sandbox backends:
| Profile | Network | Mounts | Resources | When to use |
|---------|---------|--------|-----------|-------------|
@@ -66,25 +71,60 @@ The sandbox can run on **local containers** or **in the cloud**. `box.backend` p
Prefer least privilege: skip the network unless you need it (`default` / `offline_readonly`); only add necessary directories to `allowed_mount_roots`.
## Local Backend Configuration (box.local.*)
<Note>
The Host backend does not enforce these isolation policies. A configured profile, CPU / memory / PID limit, read-only rootfs, or disabled network does not create a sandbox boundary around host processes.
</Note>
The local backends (`local` / `docker` / `nsjail`) share these settings:
## Local Workspace Configuration (box.local.*)
Docker, Nsjail, and Host share workspace path settings. Isolation and resource settings only take effect when the selected sandbox backend can enforce them:
| Setting | Default | Notes |
|---------|---------|-------|
| `local.profile` | `default` | See "Security Profiles" above |
| `local.profile` | `default` | Docker / Nsjail security profile; Host provides no matching isolation |
| `local.image` | empty | Docker-only custom image; empty = use profile default |
| `local.host_root` | `./data/box` | Host workspace base, mapped to `/workspace` inside the sandbox |
| `local.default_workspace` | empty | Default workspace name; empty = `<host_root>/default` |
| `local.skills_root` | `skills` | Skill package directory; relative paths resolve under `host_root` |
| `local.allowed_mount_roots` | `[host_root]` | Allowlist of host directories the Agent can mount |
| `local.workspace_quota_mb` | `null` | Workspace disk quota (MB); `null` = use profile default |
| `default_memory_mb` | `1536` | Memory limit for each MCP stdio process (MB); overridable via `BOX__DEFAULT_MEMORY_MB` |
| `local.workspace_quota_mb` | `null` | Workspace disk quota (MB); `null` = use profile default; Host provides no hard quota guarantee |
| `default_memory_mb` | `1536` | Memory limit for each MCP stdio process (MB); Host cannot enforce it through cgroups |
## Host Backend (Trusted Local Development)
Host is the lowest-dependency local option and does not require Docker or Nsjail. It must be selected explicitly:
```yaml
box:
enabled: true
backend: 'host'
local:
host_root: './data/box'
skills_root: 'skills'
```
The WebUI, Agent tools, and calling conventions stay the same: session scopes, `exec/read/write/edit/glob/grep`, Skills, and stdio MCP all use the existing Box APIs. Only the execution layer changes:
- `/workspace`, `workdir`, and Skill mount paths are translated to real paths on the Box Runtime host.
- Child processes inherit only a minimal path, locale, and terminal environment plus variables explicitly supplied by the request. LangBot / Box control secrets are not inherited automatically. This reduces accidental leakage but does not provide filesystem isolation.
- `exec` and managed processes start in separate process groups. Timeouts, cancellation, process stop, session deletion, and Runtime shutdown terminate the corresponding process trees.
- Idle cleanup, managed-process keepalive, and `persistent` rules match the other backends.
- Status responses include `unsafe_direct_execution: true` so operators can detect the lack of sandbox isolation.
<Note>
Host means the environment **where Box Runtime runs**. With LangBot's local stdio-managed Box Runtime, that is the current machine. If Box Runtime itself runs in a container, commands run directly in that container; Host does not automatically break through to the physical host.
</Note>
The Host MVP supports POSIX systems with `sh` (Linux / macOS). Use WSL on Windows; a native Windows process backend is not yet supported.
When Host is used through an external WebSocket Box Runtime, set the same strong random `LANGBOT_BOX_CONTROL_TOKEN` on both LangBot and Box Runtime. The locally managed stdio Runtime needs no extra token configuration. Cloud environments with managed-sandbox admission still validate isolation capabilities and the required backend; Host does not bypass those checks.
## Box Sandbox Memory Configuration
`box.default_memory_mb` sets the nsjail cgroup memory cap for every stdio-mode MCP server process.
The Host backend has no cgroup memory isolation, so this value cannot limit MCP processes running on Host.
| Setting | Notes | Default |
|---|---|---|
| `box.default_memory_mb` | MCP process memory cap (MB) | 1536 |
en/usage/sandbox/readme.mdx
+18 -11
View File
@@ -1,11 +1,11 @@
---
title: "Sandbox"
description: "LangBot sandbox (Box Runtime) gives the built-in Agent an isolated environment to run commands and edit files safely."
description: "LangBot Box Runtime gives the built-in Agent command and file tools with a choice of sandboxed or trusted-host backends."
---
The sandbox gives the built-in Agent an isolated execution environment: run commands, read and write files, and host long-lived processes. Everyday Agent use cases (data processing, file operations, running user code, hosting stdio MCP) all rely on it.
Box Runtime gives the built-in Agent one execution interface for running commands, reading and writing files, and hosting long-lived processes. Everyday Agent use cases (data processing, file operations, running user code, hosting stdio MCP) all rely on it. Docker, nsjail, and E2B provide sandbox isolation; the explicitly selected Host backend is for trusted local development and provides no isolation.
Once the sandbox is enabled, the built-in Agent automatically gains six tools — no need to wire each one into the pipeline.
Once Box is enabled, the built-in Agent automatically gains six tools — no need to wire each one into the pipeline.
## Built-in Tools
@@ -18,7 +18,7 @@ Once the sandbox is enabled, the built-in Agent automatically gains six tools
| `glob` | Find files by glob pattern |
| `grep` | Search file contents by regex |
`exec` runs inside the sandbox container; the other five operate directly on the host directory mapped to `/workspace`.
`exec` runs in the selected Box backend; the other five operate directly on the workspace directory mapped to `/workspace`. With Host selected, commands also run directly on the Box Runtime host.
<Note>
These tools target the built-in Agent. When using external runners such as Dify, n8n, Langflow, or Coze, use that platform's own tool mechanism.
@@ -37,7 +37,7 @@ The pipeline's AI configuration lets you choose how the sandbox is shared across
| Per message | `{query_id}` | Fully stateless |
<Warning>
Commands within the same scope share filesystem state. Choose "per message" for full isolation.
Commands within the same scope share filesystem state. Choose "per message" for a separate workspace. Scope controls session reuse; it is not a security boundary. Host has no host-level isolation even when different scopes are used.
</Warning>
## Lifecycle
@@ -48,23 +48,30 @@ Commands within the same scope share filesystem state. Choose "per message" for
| Box-managed processes running (e.g. stdio MCP) | Kept alive until those processes exit |
| `persistent: true` configured | Never cleaned up automatically |
These lifecycle rules also apply to Host. Cleanup terminates the session's managed process trees and removes its temporary session directory. A durable workspace mapped under `box.local.host_root` is not deleted as temporary state. Runtime shutdown and explicit session deletion also perform cleanup.
## Quick Start
1. **Prepare the backend**: install Docker locally, or pick Nsjail / E2B
2. **Edit `config.yaml`**:
Trusted local development on Linux / macOS can select Host without installing Docker:
1. **Edit `config.yaml`**:
```yaml
box:
enabled: true
backend: 'local'
backend: 'host'
local:
host_root: './data/box'
```
3. **Start LangBot**: the sandbox is enabled automatically
4. **In the pipeline**, select the built-in Agent plus a model that supports function calling
2. **Start LangBot**: Box Runtime is enabled automatically
3. **In the pipeline**, select the built-in Agent plus a model that supports function calling
The Agent will then automatically receive the six tools. See [Sandbox Configuration](./config) for details.
## Disabling the Sandbox
<Warning>
Host executes commands directly with the LangBot / Box Runtime user's permissions and must only process trusted input. To execute untrusted code, set `backend` to `local` (auto-pick Docker / Nsjail), `docker`, `nsjail`, or `e2b`.
</Warning>
## Disabling Box
Set `box.enabled: false`. Everything that depends on the sandbox (built-in tools, Skill create/edit/activate, stdio MCP) is disabled together; MCP servers in http/sse mode are unaffected.
en/usage/sandbox/runtime-relationships.mdx
+8 -2
View File
@@ -7,7 +7,7 @@ LangBot ships four extension mechanisms in parallel — **plugins, MCP, Skills,
## One-line Summary
- **Sandbox**: an execution environment that lets the Agent run commands and read/write files
- **Box execution environment**: lets the Agent run commands and read/write files; isolation depends on the selected backend
- **Skills**: on-demand instruction packages that hand the Agent a specialized workflow when needed
- **MCP Server**: connects to external tool services
- **Plugin**: a long-running extension process that can ship its own config page, event listeners, and knowledge components
@@ -16,7 +16,7 @@ LangBot ships four extension mechanisms in parallel — **plugins, MCP, Skills,
| Capability | Provided by | How the Agent sees it | When to use |
|------------|-------------|-----------------------|-------------|
| Sandbox | Box Runtime | The six tools `exec/read/write/edit/glob/grep` are attached directly | Agent needs to run code or read/write files |
| Box execution environment | Box Runtime | The six tools `exec/read/write/edit/glob/grep` are attached directly | Agent needs to run code or read/write files |
| Skills | Box Runtime skill store | After the Agent calls `activate`, instructions are injected via Tool Result | Hand the Agent a workflow, template, or script, triggered on demand |
| MCP Server | LangBot MCP Loader (stdio mode is hosted by Box) | Tools land directly in the Agent's tool list | Connect an existing MCP service |
| Plugin | Plugin Runtime | Capabilities are exposed through the plugin system | Long-lived capability with a config page, event listeners, or knowledge components |
@@ -30,6 +30,10 @@ Skills, MCP Servers, and plugins are all **pipeline extensions**. After installi
Skill binding decides **which skills the Agent can see** (it controls the `<available_skills>` list). The actual skill content is only injected after the Agent calls `activate`.
## Backends and Isolation Boundaries
The Box API, Agent tools, session scopes, lifecycle, Skills, and stdio MCP hosting work the same across backends, but their security properties differ. Docker, nsjail, and E2B provide their respective sandbox boundaries. Host uses processes on the Box Runtime host directly and is only for trusted local development. Selecting Host does not change the WebUI and does not give separate sessions host-level isolation.
## Troubleshooting Map
| Symptom | Check first |
@@ -40,6 +44,8 @@ Skill binding decides **which skills the Agent can see** (it controls the `<avai
| Sandbox fails to start in Docker deployment | Whether `langbot_box` mounts `docker.sock`, and whether Box root paths match |
| File read/write fails | `box.local.host_root`, `box.local.allowed_mount_roots` |
| Backend selection has no effect | Confirm `BOX__BACKEND` is set on the `langbot` service, not on `langbot_box` |
| Host backend is unavailable | Confirm the system is POSIX and `sh` is on `PATH`; use WSL on Windows |
| External Host Box connection is rejected | Set the same `LANGBOT_BOX_CONTROL_TOKEN` on LangBot and Box Runtime |
<Note>
Sandbox built-in tools and Skills currently target the built-in Agent. External runners (Dify, n8n, Langflow, Coze, etc.) should use their own tools and execution model.
ja/usage/sandbox/config.mdx
+47 -9
View File
@@ -1,9 +1,9 @@
---
title: "サンドボックス設定"
description: "LangBot サンドボックス（Box Runtime）を設定。隔離されたコード実行バックエンド（Docker・nsjail・E2B）を構成。"
description: "LangBot Box Runtime を設定し、Docker・nsjail・E2B、または明示的に有効化する非隔離 Host バックエンドを選択。"
---
サンドボックス設定は LangBot メインプロセスが管理し、Box Runtime が実際の実行を担当します。通常のデプロイでは、バックエンド、ワークスペースディレクトリ、セキュリティプロファイルだけを決めれば十分です。
Box の設定は LangBot メインプロセスが管理し、Box Runtime が実際の実行を担当します。通常のデプロイでは、バックエンド、ワークスペースディレクトリ、セキュリティプロファイルだけを決めれば十分です。Docker、nsjail、E2B はサンドボックス環境を提供し、Host バックエンドは Box Runtime のホスト上でコマンドを直接実行します。
<Note>
このページの `box.*` 設定はすべて `data/config.yaml` に記述します。ファイルの場所と読み込みの仕組みは[システム環境設定](../../deploy/settings)を参照してください。
@@ -36,7 +36,7 @@ Skill は Box Runtime が管理する skill store からのみ読み込まれま
## バックエンドの選択
サンドボックスは**ローカルコンテナ**または**クラウド**で動作させられます。`box.backend` でどちらを使うかを指定します：
Box は**ローカルコンテナ**、**クラウドサンドボックス**、または **Box Runtime ホスト上のプロセス**として動作させられます。`box.backend` で使用する方式を指定します：
| `backend` | 実行場所 | 動作 |
|-----------|---------|------|
@@ -44,8 +44,13 @@ Skill は Box Runtime が管理する skill store からのみ読み込まれま
| `docker` | ローカルコンテナ | Docker を強制使用。Docker daemon が必要 |
| `nsjail` | ローカルコンテナ | Nsjail を強制使用（Linux のみ）。カスタムイメージ非対応 |
| `e2b` | クラウド | [E2B](https://e2b.dev) クラウドサンドボックスを使用。API キーが必要 |
| `host` | Box Runtime ホスト | Box Runtime ユーザーの権限でローカルプロセスを直接起動。POSIX と `sh` が必要 |
`local` は「自動選択」のショートハンドであり、`docker` / `nsjail` と並列の 4 つ目のバックエンドではありません。ローカル系バックエンド（`local` / `docker` / `nsjail`）は `box.local.*` 設定セクションを**共有**し、クラウドバックエンドは `box.e2b.*` を使います。
`local` は「自動選択」のショートハンドであり、`docker` / `nsjail` と並列の 4 つ目のバックエンドではありません。試行対象は Docker と Nsjail だけで、**`host` が自動選択されることはありません**。ローカル系バックエンドは `box.local.*` のワークスペース設定を使い、クラウドバックエンドは `box.e2b.*` を使います。
<Warning>
`host` は**サンドボックスではありません**。コマンドは Box Runtime ユーザーのホスト権限を持ち、ファイルシステム、プロセス、ネットワーク、namespace、cgroup、rootfs、イメージの隔離はありません。読み取り専用マウントやハードディスククォータも保証されません。単一ユーザーかつ信頼できる入力を扱うローカル開発にのみ使用し、公開サービス、共有ホスト、信頼できないコードには使用しないでください。
</Warning>
<Note>
`backend` は強制値です。`docker` を指定して Docker が使えない場合、Nsjail や E2B に**自動でフォールバックしません**。自動 fan-out するのは `local` だけです。
@@ -55,7 +60,7 @@ Skill は Box Runtime が管理する skill store からのみ読み込まれま
## セキュリティプロファイル
`box.local.profile` はローカル系バックエンドのネットワーク、マウント、リソース制限を制御します：
`box.local.profile` は Docker / Nsjail ローカルサンドボックスバックエンドのネットワーク、マウント、リソース制限を制御します：
| Profile | ネットワーク | マウント | リソース | 推奨シーン |
|---------|---------|---------|---------|----------|
@@ -66,19 +71,52 @@ Skill は Box Runtime が管理する skill store からのみ読み込まれま
最小権限を優先：ネットワークが不要なら `default` または `offline_readonly`；`allowed_mount_roots` には必要なディレクトリのみを追加。
## ローカル系バックエンド設定（box.local.*）
<Note>
Host バックエンドはこれらの隔離ポリシーを適用しません。profile、CPU / メモリ / PID 制限、読み取り専用 rootfs、ネットワーク無効化を設定しても、ホストプロセスにサンドボックス境界は作られません。
</Note>
ローカル系バックエンド（`local` / `docker` / `nsjail`）は以下を共有します：
## ローカルワークスペース設定（box.local.*）
Docker、Nsjail、Host はワークスペースパス設定を共有します。隔離とリソース設定は、選択したサンドボックスバックエンドが実施できる場合にのみ有効です：
| 設定項目 | 既定値 | 説明 |
|---------|--------|------|
| `local.profile` | `default` | 上記「セキュリティプロファイル」を参照 |
| `local.profile` | `default` | Docker / Nsjail のセキュリティプロファイル。Host には対応する隔離なし |
| `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` = プロファイル既定 |
| `local.workspace_quota_mb` | `null` | ワークスペースのディスククォータ（MB）。`null` = プロファイル既定。Host ではハードクォータを保証しない |
## Host バックエンド（信頼できるローカル開発）
Host は依存関係が最も少ないローカルオプションで、Docker や Nsjail は不要です。必ず明示的に選択します：
```yaml
box:
enabled: true
backend: 'host'
local:
host_root: './data/box'
skills_root: 'skills'
```
WebUI、Agent ツール、呼び出し方法は変わりません。セッションスコープ、`exec/read/write/edit/glob/grep`、Skills、stdio MCP は既存の Box API をそのまま使います。違いは実行層だけです：
- `/workspace`、`workdir`、Skill のマウントパスは Box Runtime ホスト上の実パスに変換されます。
- 子プロセスは最小限のパス、ロケール、端末環境と、リクエストで明示的に渡された変数だけを継承します。LangBot / Box の制御シークレットは自動継承されません。これは意図しない漏えいを減らしますが、ファイルシステム隔離を提供するものではありません。
- `exec` と管理対象プロセスは個別のプロセスグループで起動します。タイムアウト、キャンセル、プロセス停止、セッション削除、Runtime 終了時には対応するプロセスツリーを終了します。
- アイドルクリーンアップ、管理対象プロセスによる維持、`persistent` のルールは他のバックエンドと同じです。
- ステータスレスポンスには `unsafe_direct_execution: true` が含まれ、サンドボックス隔離がないことを運用側で識別できます。
<Note>
Host は **Box Runtime が動作する環境**を指します。LangBot がローカル stdio Box Runtime を管理する場合は現在のマシンです。Box Runtime 自体がコンテナ内で動作している場合、コマンドはそのコンテナ内で直接実行され、物理ホストへ自動的に抜けることはありません。
</Note>
Host MVP は `sh` を備えた POSIX システム（Linux / macOS）をサポートします。Windows では WSL を使用してください。Windows ネイティブのプロセスバックエンドはまだサポートされていません。
外部 WebSocket Box Runtime で Host を使う場合、LangBot と Box Runtime の両方に同じ強力なランダム値の `LANGBOT_BOX_CONTROL_TOKEN` を設定してください。ローカル管理の stdio Runtime では追加のトークン設定は不要です。管理サンドボックス admission を有効にした Cloud 環境では、隔離能力と必須バックエンドの検証が継続され、Host がこれらを迂回することはありません。
## Docker バックエンド設定（box.docker.*）
ja/usage/sandbox/readme.mdx
+18 -11
View File
@@ -1,11 +1,11 @@
---
title: "サンドボックス (Sandbox)"
description: "LangBot サンドボックス（Box Runtime）は内蔵 Agent に隔離環境を提供し、安全にコマンド実行やファイル編集を可能に。"
description: "LangBot Box Runtime は組み込み Agent にコマンド・ファイルツールを提供し、サンドボックスまたは信頼済み Host バックエンドを選択可能。"
---
サンドボックスは組み込み Agent に隔離された実行環境を提供します。コマンドの実行、ファイルの読み書き、長期常駐プロセスの実行が可能です。日常的な Agent 用途（データ処理、ファイル操作、ユーザーコードの実行、stdio MCP のホスティング）はすべてこれに依存します。
Box Runtime は組み込み Agent に、コマンド実行、ファイルの読み書き、長期常駐プロセスの実行を行う統一インターフェースを提供します。日常的な Agent 用途（データ処理、ファイル操作、ユーザーコードの実行、stdio MCP のホスティング）はすべてこれに依存します。Docker、nsjail、E2B はサンドボックス隔離を提供しますが、明示的に選択する Host バックエンドは信頼できるローカル開発向けで、隔離は提供しません。
サンドボックスを有効化すると、組み込み Agent は自動的に 6 つのツールを取得します。パイプラインで個別に有効化する必要はありません。
Box を有効化すると、組み込み Agent は自動的に 6 つのツールを取得します。パイプラインで個別に有効化する必要はありません。
## 組み込みツール
@@ -18,7 +18,7 @@ description: "LangBot サンドボックス（Box Runtime）は内蔵 Agent に
| `glob` | glob パターンでファイルを検索 |
| `grep` | 正規表現でファイル内容を検索 |
`exec` はサンドボックスコンテナ内で実行されます。残り 5 つはホスト側の `/workspace` にマッピングされたディレクトリを直接読み書きします。
`exec` は選択した Box バックエンドで実行されます。残り 5 つは `/workspace` にマッピングされたワークスペースディレクトリを直接読み書きします。Host を選択した場合、コマンドも Box Runtime ホスト上で直接実行されます。
<Note>
これらのツールは組み込み Agent 向けです。Dify、n8n、Langflow、Coze などの外部 Runner を使用する場合は、各プラットフォーム独自のツール機構を利用してください。
@@ -37,7 +37,7 @@ description: "LangBot サンドボックス（Box Runtime）は内蔵 Agent に
| メッセージごと | `{query_id}` | 完全にステートレス |
<Warning>
同一スコープ内のコマンドはファイルシステム状態を共有します。完全な隔離が必要な場合は「メッセージごと」を選択してください。
同一スコープ内のコマンドはファイルシステム状態を共有します。独立したワークスペースが必要な場合は「メッセージごと」を選択してください。スコープはセッション再利用の規則であり、セキュリティ境界ではありません。Host では異なるスコープを使ってもホストレベルの隔離はありません。
</Warning>
## ライフサイクル
@@ -48,23 +48,30 @@ description: "LangBot サンドボックス（Box Runtime）は内蔵 Agent に
| Box がホストするプロセス（stdio MCP など）が稼働中 | クリーンアップしない。プロセス終了後に解放 |
| `persistent: true` 設定時 | 自動クリーンアップなし |
これらのライフサイクル規則は Host にも適用されます。クリーンアップ時にはセッションの管理対象プロセスツリーを終了し、一時セッションディレクトリを削除します。`box.local.host_root` 配下にマッピングされた永続ワークスペースは一時状態として削除されません。Runtime 終了時や明示的なセッション削除時にもクリーンアップが行われます。
## クイックスタート
1. **バックエンドの準備**: ローカルに Docker をインストール、または Nsjail / E2B を選択
2. **`config.yaml` に記述**:
Linux / macOS 上の信頼できるローカル開発では、Docker をインストールせず Host を選択できます：
1. **`config.yaml` に記述**:
```yaml
box:
enabled: true
backend: 'local'
backend: 'host'
local:
host_root: './data/box'
```
3. **LangBot を起動**: サンドボックスは自動的に有効化
4. **パイプラインで** 組み込み Agent と関数呼び出し対応モデルを選択
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 は影響を受けません。
ja/usage/sandbox/runtime-relationships.mdx
+8 -2
View File
@@ -7,7 +7,7 @@ LangBot には **プラグイン、MCP、Skills、サンドボックス** とい
## 一行で区別する
- **サンドボックス**: 実行環境。Agent がコマンド実行やファイル読み書きを行う場所
- **Box 実行環境**: Agent がコマンド実行やファイル読み書きを行う場所。隔離の有無は選択したバックエンドによる
- **Skills**: オンデマンドで起動する指示パック。Agent に一時的に専門的なワークフローを追加する
- **MCP サーバー**: 外部のツールサービスに接続する
- **プラグイン**: 長期常駐する拡張プロセス。設定ページ、イベント監視、ナレッジベースを持てる
@@ -16,7 +16,7 @@ LangBot には **プラグイン、MCP、Skills、サンドボックス** とい
| 機能 | 提供元 | Agent への入り方 | いつ使うか |
|------|--------|----------------|---------|
| サンドボックス | Box Runtime | `exec/read/write/edit/glob/grep` の 6 点セットを直接付与 | Agent がコード実行やファイル読み書きを行うとき |
| Box 実行環境 | Box Runtime | `exec/read/write/edit/glob/grep` の 6 点セットを直接付与 | Agent がコード実行やファイル読み書きを行うとき |
| Skills | Box Runtime skill store | Agent が `activate` を呼び出した後、指示が Tool Result として注入される | Agent にワークフロー／テンプレート／スクリプトを追加し、必要時にのみ発火させたいとき |
| MCP サーバー | LangBot MCP Loader（stdio モードは Box がホスト） | ツールが利用可能ツール一覧に直接入る | 既存の MCP サービスに接続したいとき |
| プラグイン | Plugin Runtime | プラグインシステムから能力が公開される | 長期的な機能、設定ページ／イベント監視／ナレッジコンポーネントが必要なとき |
@@ -30,6 +30,10 @@ Skills、MCP サーバー、プラグインはすべて **パイプライン拡
Skills のバインドは Agent が **どの Skill を見えるか** を決定します（`<available_skills>` 一覧に影響）。具体的な Skill 内容は Agent が `activate` を呼び出した後にのみ注入されます。
## バックエンドと隔離境界
Box API、Agent ツール、セッションスコープ、ライフサイクル、Skills、stdio MCP ホスティングの使い方は各バックエンドで同じですが、セキュリティ特性は異なります。Docker、nsjail、E2B はそれぞれのサンドボックス境界を提供します。Host は Box Runtime ホスト上のプロセスを直接使用し、信頼できるローカル開発専用です。Host を選択しても WebUI は変わらず、別々のセッションにホストレベルの隔離が追加されることもありません。
## トラブルシューティングの入口
| 症状 | まず確認すること |
@@ -40,6 +44,8 @@ Skills のバインドは Agent が **どの Skill を見えるか** を決定
| Docker デプロイでサンドボックスが起動しない | `langbot_box` が `docker.sock` をマウントしているか、Box ルートディレクトリのパスが一致しているか |
| ファイル読み書きに失敗 | `box.local.host_root`、`box.local.allowed_mount_roots` |
| バックエンド選択が効かない | `BOX__BACKEND` が `langbot_box` ではなく `langbot` サービスに設定されているか確認 |
| Host バックエンドが利用できない | システムが POSIX で、`PATH` に `sh` があることを確認。Windows では WSL を使用 |
| 外部 Host Box への接続が拒否される | LangBot と Box Runtime に同じ `LANGBOT_BOX_CONTROL_TOKEN` を設定 |
<Note>
サンドボックスの組み込みツールと Skills は、現在は組み込み Agent 向けです。外部 Runner（Dify、n8n、Langflow、Coze など）では、各プラットフォーム独自のツールと実行機構を使用してください。
zh/usage/sandbox/config.mdx
+50 -10
View File
@@ -1,9 +1,9 @@
---
title: "沙箱配置"
description: "配置 LangBot 沙箱（Box Runtime），设置隔离的代码执行后端：Docker、nsjail 或 E2B。"
description: "配置 LangBot Box Runtime，选择 Docker、nsjail、E2B，或显式启用不具备隔离能力的 Host 后端。"
---
沙箱由 LangBot 主进程配置，Box Runtime 负责实际执行。常规部署只需要选择后端、设置工作目录和安全预设。
Box 由 LangBot 主进程配置，Box Runtime 负责实际执行。常规部署只需要选择后端、设置工作目录和安全预设。Docker、nsjail 和 E2B 提供沙箱环境；Host 后端则直接在 Box Runtime 所在机器上执行命令。
<Note>
本页所有 `box.*` 配置都写在 `data/config.yaml` 中。配置文件的位置和加载机制详见[系统环境设置](../../deploy/settings)。
@@ -36,7 +36,7 @@ Skills 只从 Box Runtime 管理的 skill store 加载。Box Runtime 或后端
## 后端选择
沙箱可以跑在**本机容器**或**云端**。`box.backend` 选择走哪一种：
Box 可以跑在**本机容器**、**云端沙箱**，也可以直接使用 **Box Runtime 主机进程**。`box.backend` 选择走哪一种：
| `backend` | 跑在哪 | 行为 |
|-----------|--------|------|
@@ -44,8 +44,13 @@ Skills 只从 Box Runtime 管理的 skill store 加载。Box Runtime 或后端
| `docker` | 本机容器 | 强制使用 Docker，需要 Docker daemon |
| `nsjail` | 本机容器 | 强制使用 Nsjail（仅 Linux），不支持自定义镜像 |
| `e2b` | 云端 | 使用 [E2B](https://e2b.dev) 云沙箱，需要 API Key |
| `host` | Box Runtime 主机 | 直接以 Box Runtime 用户权限启动本机进程；仅支持 POSIX 系统且需要 `sh` |
`local` 是「自动选择」的简写，不是和 `docker`/`nsjail` 平级的第四种后端。本机容器后端（`local`/`docker`/`nsjail`）**共用** `box.local.*` 配置段；云端后端用 `box.e2b.*` 配置段。
`local` 是「自动选择」的简写，不是和 `docker`/`nsjail` 平级的第四种后端。它只会尝试 Docker 和 Nsjail，**永远不会自动选择 `host`**。本机后端使用 `box.local.*` 中的工作区配置；云端后端使用 `box.e2b.*`。
<Warning>
`host` **不是沙箱**。命令拥有 Box Runtime 用户的主机权限，没有文件系统、进程、网络、namespace、cgroup、rootfs 或镜像隔离，也不保证只读挂载和硬磁盘配额。它只适合单用户、可信输入的本地开发环境；不要用于公开服务、共享主机或执行不受信任的代码。
</Warning>
<Note>
`backend` 是强制值。设为 `docker` 时如果 Docker 不可用，**不会**自动回退到 Nsjail 或 E2B——只有 `local` 会自动 fan-out。
@@ -55,7 +60,7 @@ Skills 只从 Box Runtime 管理的 skill store 加载。Box Runtime 或后端
## 安全预设
`box.local.profile` 控制本机后端的网络、挂载、资源限制：
`box.local.profile` 控制 Docker / Nsjail 本机沙箱后端的网络、挂载和资源限制：
| Profile | 网络 | 挂载 | 资源 | 建议场景 |
|---------|------|------|------|----------|
@@ -66,25 +71,60 @@ Skills 只从 Box Runtime 管理的 skill store 加载。Box Runtime 或后端
优先使用最小权限：不需要网络就用 `default` 或 `offline_readonly`；只把必要目录加入 `allowed_mount_roots`。
## 本机后端配置（box.local.*）
<Note>
Host 后端不执行这些隔离策略。即使配置了 profile、CPU / 内存 / PID 限制、只读 rootfs 或网络关闭，主机进程也不受这些沙箱边界保护。
</Note>
本机后端（`local` / `docker` / `nsjail`）共用以下配置：
## 本机工作区配置（box.local.*）
Docker、Nsjail 和 Host 共用工作区路径配置；隔离与资源配置仅在对应沙箱后端能够实施时生效：
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `local.profile` | `default` | 见上文「安全预设」 |
| `local.profile` | `default` | Docker / Nsjail 安全预设；Host 不提供对应隔离 |
| `local.image` | 空 | Docker 后端的自定义镜像；空 = 用 profile 默认 |
| `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` = 用 profile 默认 |
| `default_memory_mb` | `1536` | MCP stdio 进程内存上限（MB）；可通过 `BOX__DEFAULT_MEMORY_MB` 覆盖 |
| `local.workspace_quota_mb` | `null` | 工作区磁盘配额（MB），`null` = 用 profile 默认；Host 不提供硬配额保证 |
| `default_memory_mb` | `1536` | MCP stdio 进程内存上限（MB）；Host 无法用 cgroup 强制执行 |
## Host 后端（可信本地开发）
Host 是依赖最少的本地选项，不需要安装 Docker 或 Nsjail。它必须显式选择：
```yaml
box:
enabled: true
backend: 'host'
local:
host_root: './data/box'
skills_root: 'skills'
```
WebUI、Agent 工具和调用方式不变：仍然使用相同的会话作用域、`exec/read/write/edit/glob/grep`、Skills 和 stdio MCP。区别只在执行层：
- `/workspace`、`workdir` 和 Skill 挂载路径会转换为 Box Runtime 主机上的实际路径。
- 子进程只继承最小的 PATH、语言和终端环境，再叠加请求中显式传入的变量；LangBot / Box 控制密钥不会自动进入子进程环境。这能减少意外泄露，但不构成文件系统隔离。
- `exec` 和托管进程在独立进程组中启动；超时、取消、停止、删除会话和 Runtime 关闭都会终止对应进程树。
- 空闲回收、托管进程保活和 `persistent` 规则与其他后端一致。
- 状态接口会返回 `unsafe_direct_execution: true`，便于运维侧识别当前没有沙箱隔离。
<Note>
Host 指的是 **Box Runtime 所在的环境**。LangBot 直接启动本地 stdio Box Runtime 时，它是当前机器；如果 Box Runtime 本身运行在容器里，命令会直接运行在那个容器中，而不是自动穿透到物理宿主机。
</Note>
Host MVP 支持带 `sh` 的 POSIX 系统（Linux / macOS）。Windows 请先使用 WSL；原生 Windows 进程后端尚未支持。
外部 WebSocket Box Runtime 使用 Host 时，必须在 LangBot 与 Box Runtime 两侧设置相同的强随机 `LANGBOT_BOX_CONTROL_TOKEN`。本地自动管理的 stdio Box Runtime 不需要额外配置该令牌。启用了托管沙箱 admission 的 Cloud 环境仍会按隔离能力和指定后端进行校验，Host 不会绕过这些检查。
## Box 沙箱内存配置
`box.default_memory_mb` 控制每个 stdio 模式 MCP 服务进程的 nsjail cgroup 内存上限。
Host 后端不提供 cgroup 内存隔离，因此该值不能限制 Host 上的 MCP 进程。
| 配置项 | 说明 | 默认值 |
|---|---|---|
| `box.default_memory_mb` | MCP 进程内存上限（MB）| 1536 |
zh/usage/sandbox/readme.mdx
+18 -11
View File
@@ -1,11 +1,11 @@
---
title: "沙箱 (Sandbox)"
description: "LangBot 沙箱（Box Runtime）为内置 Agent 提供隔离环境，安全地执行命令与读写文件。"
description: "LangBot Box Runtime 为内置 Agent 提供命令执行与文件工具，并可选择沙箱或可信本机后端。"
---
沙箱给内置 Agent 一个隔离的执行环境：跑命令、读写文件、运行长驻进程。日常 Agent 应用（数据处理、文件操作、运行用户代码、托管 stdio MCP）都依赖它。
Box Runtime 给内置 Agent 一个统一的执行环境：跑命令、读写文件、运行长驻进程。日常 Agent 应用（数据处理、文件操作、运行用户代码、托管 stdio MCP）都依赖它。Docker、nsjail 和 E2B 后端提供沙箱隔离；显式选择的 Host 后端用于可信本地开发，不提供隔离。
启用沙箱后，内置 Agent 会自动获得六个工具，无需在流水线里逐项开启。
启用 Box 后，内置 Agent 会自动获得六个工具，无需在流水线里逐项开启。
## 内置工具
@@ -18,7 +18,7 @@ description: "LangBot 沙箱（Box Runtime）为内置 Agent 提供隔离环境
| `glob` | 按 glob 模式查找文件 |
| `grep` | 按正则搜索文件内容 |
`exec` 在沙箱容器内运行；其余五个直接读写主机映射到 `/workspace` 的目录。
`exec` 在所选 Box 后端中运行；其余五个直接读写映射到 `/workspace` 的工作区目录。选择 Host 时，命令也直接运行在 Box Runtime 主机上。
<Note>
这些工具面向内置 Agent。使用 Dify、n8n、Langflow、Coze 等外部 Runner 时，请使用对应平台自己的工具机制。
@@ -37,7 +37,7 @@ description: "LangBot 沙箱（Box Runtime）为内置 Agent 提供隔离环境
| 每条消息 | `{query_id}` | 完全无状态 |
<Warning>
同一作用域内的命令共享文件系统状态。需要完全隔离请选"每条消息"。
同一作用域内的命令共享文件系统状态。需要独立工作区请选择"每条消息"。作用域是会话复用规则，不是安全边界；Host 后端即使使用不同作用域，也没有主机级隔离。
</Warning>
## 生命周期
@@ -48,23 +48,30 @@ description: "LangBot 沙箱（Box Runtime）为内置 Agent 提供隔离环境
| 有 Box 托管进程（如 stdio MCP）在跑 | 不清理，进程结束后才释放 |
| 配置 `persistent: true` | 永不自动清理 |
这些生命周期行为也适用于 Host。回收时会终止该会话的托管进程树并移除临时会话目录；映射到 `box.local.host_root` 的持久工作区不会被当作临时目录删除。Runtime 关闭或显式删除会话时也会执行清理。
## 快速开始
1. **准备后端**：本机装好 Docker，或选择 Nsjail / E2B
2. **写入 `config.yaml`**：
可信的 Linux / macOS 本地开发可以直接选择 Host，不需要安装 Docker：
1. **写入 `config.yaml`**：
```yaml
box:
enabled: true
backend: 'local'
backend: 'host'
local:
host_root: './data/box'
```
3. **启动 LangBot**：沙箱自动启用
4. **在流水线里**选择内置 Agent + 支持函数调用的模型
2. **启动 LangBot**：Box Runtime 自动启用
3. **在流水线里**选择内置 Agent + 支持函数调用的模型
之后 Agent 会自动获得六个工具。详细配置见[沙箱配置](./config)。
## 关闭沙箱
<Warning>
Host 会以 LangBot / Box Runtime 用户的权限直接执行命令，只能处理可信输入。需要执行不受信任的代码时，请将 `backend` 改为 `local`（自动选择 Docker / Nsjail）、`docker`、`nsjail` 或 `e2b`。
</Warning>
## 关闭 Box
设置 `box.enabled: false`。所有依赖沙箱的能力（内置工具、Skill 创建/编辑/激活、stdio MCP）会一并停用；http/sse 模式的 MCP 不受影响。
zh/usage/sandbox/runtime-relationships.mdx
+8 -2
View File
@@ -7,7 +7,7 @@ LangBot 里同时存在**插件、MCP、Skills、沙箱**四种扩展机制，
## 一句话区分
- **沙箱**：执行环境，让 Agent 跑命令、读写文件
- **Box 执行环境**：让 Agent 跑命令、读写文件；是否隔离取决于所选后端
- **Skills**：按需激活的指令包，给 Agent 临时增加一段专业工作流
- **MCP Server**：接入外部工具服务
- **插件**：长期运行的扩展进程，可带配置页、事件监听、知识库
@@ -16,7 +16,7 @@ LangBot 里同时存在**插件、MCP、Skills、沙箱**四种扩展机制，
| 能力 | 提供方 | 给 Agent 的形式 | 何时使用 |
|------|--------|----------------|---------|
| 沙箱 | Box Runtime | 直接挂上 `exec/read/write/edit/glob/grep` 六件套 | Agent 要执行代码、读写文件 |
| Box 执行环境 | Box Runtime | 直接挂上 `exec/read/write/edit/glob/grep` 六件套 | Agent 要执行代码、读写文件 |
| Skills | Box Runtime skill store | Agent 调 `activate` 后，指令通过 Tool Result 注入 | 想给 Agent 加一段流程/模板/脚本，按需触发 |
| MCP Server | LangBot MCP Loader（stdio 模式由 Box 托管） | 工具直接进入可用工具列表 | 接入已有的 MCP 服务 |
| 插件 | Plugin Runtime | 由插件系统暴露能力 | 长期能力、需要配置页/事件监听/知识库组件 |
@@ -30,6 +30,10 @@ Skills、MCP Server、插件都属于**流水线扩展**。在 WebUI 安装/创
Skills 的绑定决定 Agent **能看到哪些技能**（影响 `<available_skills>` 列表）。具体技能内容只有 Agent 调用 `activate` 后才会注入。
## 后端与隔离边界
Box API、Agent 工具、会话作用域、生命周期、Skills 和 stdio MCP 托管在各后端上的使用方式一致，但安全属性不同：Docker、nsjail 和 E2B 提供各自的沙箱边界；Host 直接使用 Box Runtime 主机进程，只用于可信本地开发。选择 Host 不会改变 WebUI，也不会让不同会话获得主机级隔离。
## 排障入口
| 现象 | 优先检查 |
@@ -40,6 +44,8 @@ Skills 的绑定决定 Agent **能看到哪些技能**（影响 `<available_skil
| Docker 部署沙箱启不来 | `langbot_box` 是否挂载 `docker.sock`、Box 根目录路径是否一致 |
| 文件读写失败 | `box.local.host_root`、`box.local.allowed_mount_roots` |
| 后端选择不生效 | 确认 `BOX__BACKEND` 设在 `langbot` 服务上，不是 `langbot_box` |
| Host 后端不可用 | 确认系统为 POSIX 且 `PATH` 中存在 `sh`；Windows 使用 WSL |
| 外部 Host Box 连接被拒绝 | LangBot 与 Box Runtime 两侧设置相同的 `LANGBOT_BOX_CONTROL_TOKEN` |
<Note>
沙箱内置工具和 Skills 当前面向内置 Agent。外部 Runner（Dify、n8n、Langflow、Coze 等）应使用各自平台的工具和执行机制。