From 853d7d4091aac9aa9feae4f51187d89069b79638 Mon Sep 17 00:00:00 2001 From: RockChinQ Date: Tue, 11 Aug 2026 21:35:20 +0800 Subject: [PATCH] docs(runtime): update standalone development guide --- en/deploy/settings.mdx | 5 +-- en/develop/plugin-runtime.mdx | 63 +++++++++++++++++++++++++++++++---- ja/develop/plugin-runtime.mdx | 63 +++++++++++++++++++++++++++++++---- zh/develop/plugin-runtime.mdx | 63 +++++++++++++++++++++++++++++++---- 4 files changed, 174 insertions(+), 20 deletions(-) diff --git a/en/deploy/settings.mdx b/en/deploy/settings.mdx index 4635d06aa..40cf99f98 100644 --- a/en/deploy/settings.mdx +++ b/en/deploy/settings.mdx @@ -340,8 +340,9 @@ box: enabled: true backend: 'local' # 'local' (Docker/nsjail), 'docker', 'nsjail', or 'e2b'. Can be written via BOX__BACKEND. runtime: - # External WebSocket runtimes also require LANGBOT_BOX_CONTROL_TOKEN in - # both LangBot and Box. Keep the shared secret out of this config file. + # LANGBOT_BOX_CONTROL_TOKEN is optional for OSS external WebSocket + # runtimes. To protect an exposed endpoint, set the same strong secret + # in both LangBot and Box. Keep it out of this config file. endpoint: '' # External Box Runtime base URL, e.g. 'ws://127.0.0.1:5410'. Leave empty for local auto-managed runtime. limits: max_sessions: 64 diff --git a/en/develop/plugin-runtime.mdx b/en/develop/plugin-runtime.mdx index 6424a1a05..f1652fd8a 100644 --- a/en/develop/plugin-runtime.mdx +++ b/en/develop/plugin-runtime.mdx @@ -42,11 +42,9 @@ source .venv/bin/activate ## Start Plugin Runtime ```bash -uv run --no-sync lbp rt +python -m langbot_plugin.cli.__init__ rt ``` -Or start it via `python -m langbot_plugin.cli.__init__ rt`. - Plugin Runtime accepts the following parameters: - `--debug-only`: Do not start plugins in the `data/plugins` directory, only allow loading plugins through debug connections. @@ -76,10 +74,63 @@ plugin: runtime_ws_url: ws://localhost:5400/control/ws ``` -And add the startup parameter `--standalone-runtime` when starting the LangBot main program (e.g., `uv run --no-sync main.py --standalone-runtime`). Make sure to include the `--no-sync` parameter in this command, which ensures that the local langbot-plugin-sdk you just synced will not be overwritten by the remote version.\ +In a terminal with LangBot's virtual environment activated, start the main program directly with Python and add `--standalone-runtime` (for example, `python main.py --standalone-runtime`). Calling the current virtual environment's Python directly does not resync dependencies, so it does not overwrite the local langbot-plugin-sdk you just installed with the remote version.\ Restart LangBot, and it will connect to this runtime using WebSocket. -`LANGBOT_PLUGIN_RUNTIME_CONTROL_TOKEN` is optional by default. When it is unset on both LangBot and Runtime, the local OSS control connection is established without a token. To protect an exposed port 5400, configure the same high-entropy value of at least 32 characters on both sides; configuring only one side makes the connection fail. +`LANGBOT_PLUGIN_RUNTIME_CONTROL_TOKEN` is optional by default. When it is unset on both LangBot and Runtime, the local OSS control connection is established without a token. To protect an exposed port 5400, configure the same high-entropy value of at least 32 characters on both sides. Once the Runtime configures a token, it rejects LangBot clients without the same value; configuring only the LangBot side does not enable authentication on the Runtime. + +### Debug a plugin with `lbp run` + +Multi-Workspace versions no longer allow a debug plugin to join the Runtime merely by reaching port `5401`. Every Workspace has a separate expiring debug key: + +1. Make sure LangBot and Plugin Runtime are running and connected as described above. +2. On the LangBot WebUI Plugins page, open “Debug Info” and copy the debug URL and debug key. This requires resource-management permission in the current Workspace. +3. Add the values to the plugin project's `.env`: + +```bash +DEBUG_RUNTIME_WS_URL=ws://localhost:5401/plugin/debug/ws +PLUGIN_DEBUG_KEY= +``` + +4. Start the plugin from its project directory: + +```bash +python -m langbot_plugin.cli.__init__ run +``` + +Instead of storing the key in `.env`, you may run `python -m langbot_plugin.cli.__init__ run --plugin-debug-key ''`. Keys are scoped to one Workspace and expire after two hours. Fetch a new key after it expires, the Runtime restarts, or you switch Workspaces. A client that configures only `DEBUG_RUNTIME_WS_URL` is rejected. + +## Start Box Runtime in standalone mode + +Box Runtime follows the same control-connection rules as Plugin Runtime: a token is optional for OSS standalone development, and the connection works when `LANGBOT_BOX_CONTROL_TOKEN` is unset on both sides: + +```bash +# Terminal 1: langbot-plugin-sdk directory +python -m langbot_plugin.cli.__init__ box +``` + +Point LangBot's `data/config.yaml` at the local Box Runtime: + +```yaml +box: + enabled: true + backend: local + runtime: + endpoint: ws://127.0.0.1:5410 +``` + +```bash +# Terminal 2: LangBot directory +python main.py --standalone-runtime --standalone-box +``` + +To protect an exposed port 5410, set the same high-entropy, non-whitespace value of at least 32 characters before starting each process: + +```bash +export LANGBOT_BOX_CONTROL_TOKEN='' +``` + +Once Box Runtime configures a token, it rejects LangBot clients without the same value. Configuring only the LangBot side does not enable authentication on Box Runtime; an explicitly configured value shorter than 32 characters is still rejected by both sides. Do not commit the real value to configuration or Git. ## langbot-plugin-sdk Architecture @@ -95,4 +146,4 @@ This codebase contains the following: The CLI tool provides Runtime startup, plugin initialization, plugin component management, Marketplace interaction, and other functions. -For detailed program entry points, please see [`langbot_plugin.cli.__init__`](https://github.com/langbot-app/langbot-plugin-sdk/blob/main/src/langbot_plugin/cli/__init__.py). \ No newline at end of file +For detailed program entry points, please see [`langbot_plugin.cli.__init__`](https://github.com/langbot-app/langbot-plugin-sdk/blob/main/src/langbot_plugin/cli/__init__.py). diff --git a/ja/develop/plugin-runtime.mdx b/ja/develop/plugin-runtime.mdx index f873ef60c..012c8d09a 100644 --- a/ja/develop/plugin-runtime.mdx +++ b/ja/develop/plugin-runtime.mdx @@ -42,11 +42,9 @@ source .venv/bin/activate ## プラグインランタイムの起動 ```bash -uv run --no-sync lbp rt +python -m langbot_plugin.cli.__init__ rt ``` -または`python -m langbot_plugin.cli.__init__ rt`で起動してください。 - プラグインランタイムは以下のパラメーターを受け入れます: - `--debug-only`: `data/plugins`ディレクトリのプラグインを起動せず、デバッグ接続を通じたプラグインの読み込みのみを許可します。 @@ -76,10 +74,63 @@ plugin: runtime_ws_url: ws://localhost:5400/control/ws ``` -そして、LangBotメインプログラムの起動時に起動パラメーター`--standalone-runtime`を追加します(例: `uv run --no-sync main.py --standalone-runtime`)。このコマンドでは必ず`--no-sync`パラメーターを付けてください。これにより、同期したローカルのlangbot-plugin-sdkがリモート版で上書きされないことが保証されます。\ +LangBot の仮想環境を有効にしたターミナルで、Python を直接使用してメインプログラムを起動し、`--standalone-runtime` を追加します（例：`python main.py --standalone-runtime`）。現在の仮想環境の Python を直接呼び出す場合、依存関係は再同期されないため、インストールしたローカルの langbot-plugin-sdk がリモート版で上書きされることはありません。\ LangBotを再起動すると、WebSocketを使用してこのランタイムに接続されます。 -`LANGBOT_PLUGIN_RUNTIME_CONTROL_TOKEN` は既定では省略可能です。LangBot と Runtime の両方で未設定の場合、ローカル OSS の制御接続はトークンなしで確立されます。公開された 5400 ポートを保護する場合は、両側に同じ 32 文字以上の高エントロピー値を設定してください。片側だけに設定すると接続は失敗します。 +`LANGBOT_PLUGIN_RUNTIME_CONTROL_TOKEN` は既定では省略可能です。LangBot と Runtime の両方で未設定の場合、ローカル OSS の制御接続はトークンなしで確立されます。公開された 5400 ポートを保護する場合は、両側に同じ 32 文字以上の高エントロピー値を設定してください。Runtime 側に token を設定すると、同じ値を送信しない LangBot は拒否されます。LangBot 側だけに設定しても Runtime 側の認証は有効になりません。 + +### `lbp run` でプラグインをデバッグする + +Multi-Workspace 版では、デバッグプラグインは `5401` ポートへ到達できるだけでは Runtime に接続できません。Workspace ごとに、有効期限付きの個別デバッグキーが必要です： + +1. 上記の手順で LangBot と Plugin Runtime が起動し、接続済みであることを確認します。 +2. LangBot WebUI の「プラグイン」ページで「デバッグ情報」を開き、デバッグ URL とデバッグキーをコピーします。この操作には現在の Workspace のリソース管理権限が必要です。 +3. プラグインプロジェクトの `.env` に設定します： + +```bash +DEBUG_RUNTIME_WS_URL=ws://localhost:5401/plugin/debug/ws +PLUGIN_DEBUG_KEY= +``` + +4. プラグインプロジェクトのディレクトリで起動します： + +```bash +python -m langbot_plugin.cli.__init__ run +``` + +`.env` に保存せず、`python -m langbot_plugin.cli.__init__ run --plugin-debug-key '<デバッグキー>'` を使用することもできます。キーは Workspace ごとに分離され、有効期限は 2 時間です。期限切れ、Runtime の再起動、または Workspace の切り替え後は WebUI から再取得してください。`DEBUG_RUNTIME_WS_URL` だけを設定したクライアントは拒否されます。 + +## Box Runtime を standalone モードで起動する + +Box Runtime の制御接続ルールは Plugin Runtime と同じです。OSS standalone 開発では token は省略可能で、両側で `LANGBOT_BOX_CONTROL_TOKEN` が未設定の場合も接続できます： + +```bash +# ターミナル 1：langbot-plugin-sdk ディレクトリ +python -m langbot_plugin.cli.__init__ box +``` + +LangBot の `data/config.yaml` でローカル Box Runtime を指定します： + +```yaml +box: + enabled: true + backend: local + runtime: + endpoint: ws://127.0.0.1:5410 +``` + +```bash +# ターミナル 2：LangBot ディレクトリ +python main.py --standalone-runtime --standalone-box +``` + +公開された 5410 ポートを保護する場合は、両方のプロセスを起動する前に、同じ 32 文字以上で空白を含まない高エントロピー値を設定してください： + +```bash +export LANGBOT_BOX_CONTROL_TOKEN='<両側で完全に同じ高エントロピーシークレット>' +``` + +Box Runtime 側に token を設定すると、同じ値を送信しない LangBot は拒否されます。LangBot 側だけに設定しても Box Runtime 側の認証は有効になりません。明示的に設定した値が 32 文字未満の場合は、引き続き両側で拒否されます。実際の値を設定ファイルや Git にコミットしないでください。 ## langbot-plugin-sdkアーキテクチャ @@ -95,4 +146,4 @@ LangBotを再起動すると、WebSocketを使用してこのランタイムに CLIツールは、ランタイムの起動、プラグインの初期化、プラグインコンポーネント管理、Marketplaceとのインタラクションなどの機能を提供します。 -詳細なプログラムエントリポイントについては、[`langbot_plugin.cli.__init__`](https://github.com/langbot-app/langbot-plugin-sdk/blob/main/src/langbot_plugin/cli/__init__.py)を参照してください。 \ No newline at end of file +詳細なプログラムエントリポイントについては、[`langbot_plugin.cli.__init__`](https://github.com/langbot-app/langbot-plugin-sdk/blob/main/src/langbot_plugin/cli/__init__.py)を参照してください。 diff --git a/zh/develop/plugin-runtime.mdx b/zh/develop/plugin-runtime.mdx index 267f7c81f..f0e051f64 100644 --- a/zh/develop/plugin-runtime.mdx +++ b/zh/develop/plugin-runtime.mdx @@ -42,11 +42,9 @@ source .venv/bin/activate ## 启动插件运行时 ```bash -uv run --no-sync lbp rt +python -m langbot_plugin.cli.__init__ rt ``` -或通过`python -m langbot_plugin.cli.__init__ rt`启动。 - Plugin Runtime 接受以下参数： - `--debug-only`: 不启动`data/plugins`目录下的插件，仅允许通过调试连接加载插件。 @@ -76,10 +74,63 @@ plugin: runtime_ws_url: ws://localhost:5400/control/ws ``` -并在启动 LangBot 主程序时携带启动参数`--standalone-runtime`（如：`uv run --no-sync main.py --standalone-runtime`）。此命令行中，请务必携带`--no-sync`参数，这将确保您刚刚同步的本地 langbot-plugin-sdk 不会被远程的覆盖。\ +并在已激活 LangBot 虚拟环境的终端中，直接使用 Python 启动主程序并携带参数`--standalone-runtime`（如：`python main.py --standalone-runtime`）。直接调用当前虚拟环境的 Python 不会再次同步依赖，因此不会把刚刚安装的本地 langbot-plugin-sdk 覆盖为远程版本。\ 重启 LangBot，将会使用 WebSocket 连接到此运行时。 -默认情况下无需配置 `LANGBOT_PLUGIN_RUNTIME_CONTROL_TOKEN`：当 LangBot 与 Runtime 两端都未设置时，OSS 的本地控制连接直接建立。若部署环境需要为 5400 控制端口增加共享密钥，则必须在两端配置同一个至少 32 位的高熵值；只配置一端会导致连接失败。 +默认情况下无需配置 `LANGBOT_PLUGIN_RUNTIME_CONTROL_TOKEN`：当 LangBot 与 Runtime 两端都未设置时，OSS 的本地控制连接直接建立。若部署环境需要为 5400 控制端口增加共享密钥，则应在两端配置同一个至少 32 位的高熵值。Runtime 端配置后，未携带相同密钥的 LangBot 会被拒绝；只在 LangBot 端配置并不会启用 Runtime 端的认证。 + +### 使用 `lbp run` 调试插件 + +多 Workspace 版本不再允许调试插件仅凭 `5401` 端口接入 Runtime。每个 Workspace 都有独立且会过期的调试密钥： + +1. 确认 LangBot 与 Plugin Runtime 已按上文启动并连接成功。 +2. 在 LangBot WebUI 的“插件”页面点击“调试信息”，复制调试 URL 和调试密钥。该操作需要当前 Workspace 的资源管理权限。 +3. 在插件项目的 `.env` 中配置： + +```bash +DEBUG_RUNTIME_WS_URL=ws://localhost:5401/plugin/debug/ws +PLUGIN_DEBUG_KEY=<从 WebUI 复制的调试密钥> +``` + +4. 在插件项目目录中启动： + +```bash +python -m langbot_plugin.cli.__init__ run +``` + +也可以不写入 `.env`，改用 `python -m langbot_plugin.cli.__init__ run --plugin-debug-key '<调试密钥>'`。调试密钥按 Workspace 隔离且有效期为两小时；密钥过期、Runtime 重启或切换 Workspace 后，请回到 WebUI 重新获取。只配置 `DEBUG_RUNTIME_WS_URL` 会被 Runtime 拒绝。 + +## 以 standalone 模式启动 Box Runtime + +Box Runtime 与 Plugin Runtime 的控制连接规则一致：OSS standalone 开发环境默认不强制配置 token，两端都未设置 `LANGBOT_BOX_CONTROL_TOKEN` 时可以直接连接： + +```bash +# 终端 1：langbot-plugin-sdk 目录 +python -m langbot_plugin.cli.__init__ box +``` + +LangBot 的 `data/config.yaml` 使用本地 Box 地址： + +```yaml +box: + enabled: true + backend: local + runtime: + endpoint: ws://127.0.0.1:5410 +``` + +```bash +# 终端 2：LangBot 目录 +python main.py --standalone-runtime --standalone-box +``` + +若需要保护暴露的 5410 端口，请在启动两个进程前分别设置完全相同、至少 32 位且不含空白的高熵值： + +```bash +export LANGBOT_BOX_CONTROL_TOKEN='<两端完全相同的高熵密钥>' +``` + +Box Runtime 端一旦配置 token，就会拒绝未携带相同 token 的 LangBot。只在 LangBot 端设置不会启用 Box Runtime 端认证；显式配置但不足 32 位的值仍会被两端拒绝。不要把真实密钥提交到配置文件或 Git。 ## langbot-plugin-sdk 架构 @@ -95,4 +146,4 @@ plugin: CLI 工具提供 Runtime 启动、插件初始化、插件组件管理、Marketplace 交互等功能。 -详细的程序入口请查看[`langbot_plugin.cli.__init__`](https://github.com/langbot-app/langbot-plugin-sdk/blob/main/src/langbot_plugin/cli/__init__.py)。 \ No newline at end of file +详细的程序入口请查看[`langbot_plugin.cli.__init__`](https://github.com/langbot-app/langbot-plugin-sdk/blob/main/src/langbot_plugin/cli/__init__.py)。