docs: simplify Docker setup to a safe directory and one command (#127)

Co-authored-by: dadachann <[email protected]>
2026-10-29 20:05:25 +08:00 · 2026-09-08 01:41:46 +08:00
parent 19fc5e6399
commit 9fe0eddf34
3 changed files with 9 additions and 204 deletions
@@ -14,22 +14,13 @@ description: "Deploy LangBot with Docker and Docker Compose. Run an open-source
  - Please ensure Git, Docker, and Docker Compose are installed
 </Info>

-Clone the project:
+We recommend installing LangBot at `/opt/LangBot`. Avoid restricted directories such as `/root` and `/etc`, where security rules can block sandbox features. With an account that can write to `/opt`, run:

 ```bash
-git clone https://github.com/langbot-app/LangBot
-cd LangBot/docker
+git clone https://github.com/langbot-app/LangBot /opt/LangBot && cd /opt/LangBot/docker && docker compose --profile all up -d
 ```

-<Warning>
-  If the project is under `/root`, configure `LANGBOT_BOX_ROOT` as described in “Sandbox data directory” below before starting. Otherwise, security rules will reject the default sandbox path.
-</Warning>
-
-Start the containers with the recommended `all` profile, which enables Box Runtime-dependent features by default, including the sandbox, stdio MCP hosting, and Skill add/edit:
-
-```bash
-docker compose --profile all up
-```
+This enables the sandbox, stdio MCP, and Skill editing by default. No separate data directory configuration is needed.

 ## Runtime tokens for Internet-accessible deployments

@@ -57,62 +48,6 @@ Linux `pylibseekdb` wheel, so the host macOS version does not limit embedded
 mode inside the container. Keep the default `vdb.use: chroma` when SeekDB is
 not needed.

-## Sandbox data directory
-
-With the `all` or `box` profile, sandbox data defaults to `${PWD}/data/box`. Running Compose from `/root/LangBot/docker` puts this path under `/root`, so sandbox creation fails with `host_path ... is blocked for security`. Features that depend on the sandbox, such as stdio MCP, will not work.
-
-**Use a dedicated absolute path, such as `/opt/langbot-box` or `/data/langbot-box`.** The LangBot project can stay under `/root`; only the sandbox data directory needs to be elsewhere. Add or update this entry in `LangBot/docker/.env`, keeping any existing settings:
-
-```dotenv
-LANGBOT_BOX_ROOT=/opt/langbot-box
-```
-
-Avoid protected directories such as `/root`, `/etc`, `/proc`, `/sys`, `/dev`, `/boot`, and `/run`, their subdirectories, and symlinks pointing into them.
-
-If you already have sandbox data, stop the related services, back up and migrate the data first; changing the path does not move existing data. When ready, run from `LangBot/docker`:
-
-```bash
-docker compose --profile all up -d --force-recreate langbot langbot_box
-```
-
-Recreate both `langbot` and `langbot_box`: `restart` alone does not update environment variables or mounts. Compose environment variables override `config.yaml`, so editing that file alone will not help.
-
-`langbot_box` creates sandbox containers through the host Docker socket, so the Box root path must be identical on the host and inside the container:
-
-```yaml
-services:
-  langbot:
-    environment:
-      - BOX__LOCAL__HOST_ROOT=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
-      - BOX__LOCAL__DEFAULT_WORKSPACE=default
-      - BOX__LOCAL__SKILLS_ROOT=skills
-      - BOX__LOCAL__ALLOWED_MOUNT_ROOTS=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
-
-  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
-```
-
-<Note>
-  **The Box control plane's transport depends on the deployment method.** In Docker deployments it runs as the standalone `langbot_box` **container**, and `langbot` connects to it over WebSocket (`ws://langbot_box:5410`). In manual / `uvx` deployments, `langbot` instead spawns a stdio subprocess as the Box control plane. `langbot_box` creates sandbox sibling containers on the host Docker through the mounted `docker.sock`; the LangBot image already bundles the `docker` client, so no extra installation is required.
-</Note>
-
-If you see `No sandbox backend (Docker/nsjail/E2B) is ready`, first make sure the current user can access Docker:
-
-```bash
-sudo usermod -aG docker $USER
-newgrp docker
-docker info
-```
-
-If `docker info` works, restart LangBot.
-
-<Warning>
-`langbot_box` does not read `LANGBOT_BOX_*` or `BOX__*` variables directly. LangBot reads `BOX__LOCAL__*` and forwards the effective Box config to Box Runtime through INIT RPC. Set `LANGBOT_BOX_ROOT` as described above rather than changing only the environment of `langbot_box`.
-</Warning>
-
 The container maps port `5300` for WebUI access. You can visit `http://127.0.0.1:5300` to view the WebUI.\
 It also maps ports `2280-2285` reserved for message platform adapters.

@@ -13,22 +13,13 @@ description: "Docker と Docker Compose で LangBot をデプロイ。Discord・
 - Git、Docker、Docker Composeがインストールされていることを確認してください
 </Info>

-プロジェクトをクローンします:
+インストール先は `/opt/LangBot` を推奨します。`/root` や `/etc` などの制限されたディレクトリでは、安全規則によりサンドボックス機能が使えなくなるため避けてください。`/opt` に書き込めるアカウントで、次を実行します：

 ```bash
-git clone https://github.com/langbot-app/LangBot
-cd LangBot/docker
+git clone https://github.com/langbot-app/LangBot /opt/LangBot && cd /opt/LangBot/docker && docker compose --profile all up -d
 ```

-<Warning>
-  プロジェクトを `/root` 配下に置く場合は、起動前に下の「サンドボックスのデータディレクトリ」に従って `LANGBOT_BOX_ROOT` を設定してください。デフォルトのパスは安全規則により拒否されます。
-</Warning>
-
-推奨の `all` profile でコンテナを起動します。これにより、サンドボックス、stdio MCP ホスティング、Skill の追加/編集など Box Runtime に依存する機能がデフォルトで有効になります:
-
-```bash
-docker compose --profile all up
-```
+サンドボックス、stdio MCP、Skill の編集がデフォルトで有効になります。データディレクトリを別途設定する必要はありません。

 ## インターネット公開時の Runtime Token

@@ -52,62 +43,6 @@ docker compose up

 公式 Docker イメージにはオプションの SeekDB 依存関係がすでに含まれており、追加のビルド引数は不要です。コンテナは対応する Linux アーキテクチャの `pylibseekdb` wheel を使用するため、ホストの macOS バージョンはコンテナ内の組み込みモードを制限しません。SeekDB を使用しない場合は、デフォルトの `vdb.use: chroma` のまま使用できます。

-## サンドボックスのデータディレクトリ
-
-`all` または `box` profile を有効にすると、サンドボックスのデータはデフォルトで `${PWD}/data/box` に保存されます。`/root/LangBot/docker` で Compose を実行すると保存先も `/root` 配下になるため、サンドボックス作成時に `host_path ... is blocked for security` が発生し、stdio MCP などの機能が使えなくなります。
-
-**`/opt/langbot-box` や `/data/langbot-box` など、専用の絶対パスを推奨します。** LangBot 本体は `/root` 配下のままで構いません。サンドボックスのデータだけを別の場所に置きます。`LangBot/docker/.env` の既存設定を残し、次の行を追加または変更してください：
-
-```dotenv
-LANGBOT_BOX_ROOT=/opt/langbot-box
-```
-
-`/root`、`/etc`、`/proc`、`/sys`、`/dev`、`/boot`、`/run` などの保護されたディレクトリとその配下、およびそれらを指すシンボリックリンクは使用しないでください。
-
-既存のサンドボックスデータがある場合は、先に関連サービスを停止し、バックアップとデータ移行を済ませてください。パスを変更してもデータは自動で移動しません。準備ができたら、`LangBot/docker` で次を実行します：
-
-```bash
-docker compose --profile all up -d --force-recreate langbot langbot_box
-```
-
-`langbot` と `langbot_box` の両方を再作成する必要があります。`restart` だけでは環境変数やマウントは更新されません。また、Compose の環境変数が `config.yaml` より優先されるため、設定ファイルだけを編集しても反映されません。
-
-`langbot_box` はホスト Docker socket 経由でサンドボックスコンテナを作成するため、Box root のホスト側パスとコンテナ内パスは同一である必要があります：
-
-```yaml
-services:
-  langbot:
-    environment:
-      - BOX__LOCAL__HOST_ROOT=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
-      - BOX__LOCAL__DEFAULT_WORKSPACE=default
-      - BOX__LOCAL__SKILLS_ROOT=skills
-      - BOX__LOCAL__ALLOWED_MOUNT_ROOTS=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
-
-  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
-```
-
-<Note>
-  **Box コントロールプレーンの起動方式はデプロイ方法によって異なります。** Docker デプロイでは独立した `langbot_box` **コンテナ**として動作し、`langbot` は WebSocket（`ws://langbot_box:5410`）で接続します。手動起動 / `uvx` デプロイでは、`langbot` が Box コントロールプレーンとして stdio サブプロセスを直接起動します。`langbot_box` はマウントされた `docker.sock` を介してホスト Docker 上にサンドボックスの兄弟コンテナを作成します。LangBot イメージには `docker` クライアントが同梱されているため、追加のインストールは不要です。
-</Note>
-
-`No sandbox backend (Docker/nsjail/E2B) is ready` と表示される場合は、まず現在のユーザーが Docker にアクセスできるか確認してください:
-
-```bash
-sudo usermod -aG docker $USER
-newgrp docker
-docker info
-```
-
-`docker info` が正常に出力される場合は、LangBot を再起動してください。
-
-<Warning>
-`langbot_box` は `LANGBOT_BOX_*` や `BOX__*` 環境変数を直接読み取りません。LangBot が `BOX__LOCAL__*` を読み取り、INIT RPC 経由で Box Runtime に渡します。`langbot_box` の環境変数だけを変更せず、上記の手順で `LANGBOT_BOX_ROOT` を設定してください。
-</Warning>
-
 コンテナはWebUIアクセス用にポート`5300`をマッピングします。`http://127.0.0.1:5300`にアクセスしてWebUIを表示できます。
 また、メッセージプラットフォームアダプター用に予約されたポート`2280-2285`もマッピングします。

@@ -14,22 +14,13 @@ description: "使用 Docker 和 Docker Compose 部署 LangBot，几分钟内运
  - 推荐使用[阿里云，服务器价格低至 38 元一年，更可以享受8折优惠](https://www.aliyun.com/minisite/goods?userCode=ys4ad8gs)
 </Info>

-Git 克隆本项目：
+建议将 LangBot 安装到 `/opt/LangBot`，避免 `/root`、`/etc` 等受限制目录，以免沙箱功能被安全规则拦截。使用有 `/opt` 写入权限的账号，执行以下命令即可启动：

 ```bash
-git clone https://github.com/langbot-app/LangBot
-cd LangBot/docker
+git clone https://github.com/langbot-app/LangBot /opt/LangBot && cd /opt/LangBot/docker && docker compose --profile all up -d
 ```

-<Warning>
-  如果项目放在 `/root` 下，请先按下方「沙箱数据目录」设置 `LANGBOT_BOX_ROOT`，否则默认沙箱路径会被安全规则拒绝。
-</Warning>
-
-启动容器（推荐启用 `all` profile，以默认启用沙箱、stdio MCP 托管、Skill 添加/编辑等依赖 Box Runtime 的功能）：
-
-```bash
-docker compose --profile all up
-```
+默认启用沙箱、stdio MCP 和 Skill 编辑等功能，无需单独配置数据目录。

 ## 公网部署的 Runtime Token

@@ -53,62 +44,6 @@ docker compose up

 官方 Docker 镜像已经包含可选的 SeekDB 依赖，无需额外构建参数。容器会使用对应 Linux 架构的 `pylibseekdb` wheel，因此宿主机的 macOS 版本不会限制容器内的 embedded 模式；不使用 SeekDB 时保持默认 `vdb.use: chroma` 即可。

-## 沙箱数据目录
-
-启用 `all` 或 `box` profile 时，沙箱数据默认放在 `${PWD}/data/box`。若在 `/root/LangBot/docker` 下运行 Compose，默认路径也会落在 `/root` 下，创建沙箱时会报 `host_path ... is blocked for security`，导致 stdio MCP 等依赖沙箱的功能不可用。
-
-**建议使用独立的绝对路径，例如 `/opt/langbot-box` 或 `/data/langbot-box`。** LangBot 项目本身可以留在 `/root`，只需把沙箱数据目录放到外面。在 `LangBot/docker/.env` 中添加或修改（保留已有配置）：
-
-```dotenv
-LANGBOT_BOX_ROOT=/opt/langbot-box
-```
-
-不要使用 `/root`、`/etc`、`/proc`、`/sys`、`/dev`、`/boot`、`/run` 等受保护目录及其子目录，也不要通过符号链接指向这些目录。
-
-已有沙箱数据时，请先停止相关服务、备份并迁移数据；更改路径不会自动搬迁旧数据。准备好后，在 `LangBot/docker` 目录执行：
-
-```bash
-docker compose --profile all up -d --force-recreate langbot langbot_box
-```
-
-需要同时重建 `langbot` 和 `langbot_box`，仅 `restart` 不会更新环境变量或挂载。Compose 环境变量会覆盖 `config.yaml`，因此只改配置文件无效。
-
-`langbot_box` 通过主机 Docker socket 创建沙箱容器，因此 Box 根目录的宿主机路径和容器内路径必须一致：
-
-```yaml
-services:
-  langbot:
-    environment:
-      - BOX__LOCAL__HOST_ROOT=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
-      - BOX__LOCAL__DEFAULT_WORKSPACE=default
-      - BOX__LOCAL__SKILLS_ROOT=skills
-      - BOX__LOCAL__ALLOWED_MOUNT_ROOTS=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
-
-  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
-```
-
-<Note>
-  **Box 控制面的启动方式因部署方式而异。** 容器部署下，Box 控制面以独立的 `langbot_box` **容器**运行，`langbot` 通过 WebSocket（`ws://langbot_box:5410`）连接它；而手动启动 / `uvx` 部署则由 `langbot` 直接拉起一个 stdio 子进程作为 Box 控制面。`langbot_box` 借助挂载的宿主 `docker.sock` 在宿主 Docker 上创建沙箱兄弟容器，LangBot 镜像已内置 `docker` 客户端，无需额外安装。
-</Note>
-
-如果提示 `No sandbox backend (Docker/nsjail/E2B) is ready`，请先确认当前用户可访问 Docker：
-
-```bash
-sudo usermod -aG docker $USER
-newgrp docker
-docker info
-```
-
-若 `docker info` 正常输出，请重启 LangBot。
-
-<Warning>
-`langbot_box` 不直接读取 `LANGBOT_BOX_*` 或 `BOX__*` 环境变量；Box 配置由 `langbot` 读取 `BOX__LOCAL__*` 后通过 INIT RPC 传给 Box Runtime。请按上文设置 `LANGBOT_BOX_ROOT`，不要只修改 `langbot_box` 的环境变量。
-</Warning>
-
 <Info>
  - 如果你的主机位于中国大陆，可以考虑把 `docker-compose.yaml` 文件中的镜像名称改为`docker.langbot.app/langbot-public/rockchin/langbot:latest`以使用我们提供的镜像源。
  - 推荐[设置 Docker 容器代理](https://docker.github.net.cn/network/proxy/)，以便保证 LangBot 在运行期间的网络访问通畅。