en develop plugin runtime

Debugging Plugin Runtime, CLI, SDK

Note

Plugin Runtime, CLI, SDK are open sourced at: https://github.com/langbot-app/langbot-plugin-sdk

Since LangBot depends on entities defined in langbot-plugin-sdk, we recommend opening VS Code in a new directory, placing both LangBot and langbot-plugin-sdk (git clone https://github.com/langbot-app/langbot-plugin-sdk) as subdirectories within it. The directory structure should look like:

langbot-projects
├── LangBot
├── langbot-plugin-sdk

Enter the LangBot directory and install dependencies:

cd LangBot
uv sync --dev

At this point, uv will automatically create a virtual environment (.venv) for you. If your editor asks whether to use this virtual environment, please select Yes.

If the prompt does not appear, please manually set the Python interpreter path to the interpreter in the venv from the bottom-right corner.

Then open the terminal at the bottom of VS Code, which will automatically activate the venv.

Or you can manually activate this virtual environment:

# Please modify the command according to your .venv path
source .venv/bin/activate

Start Plugin Runtime

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.
• --ws-debug-port: Debug port to listen on, default is 5401.
• --ws-control-port: Control port to listen on (for LangBot main program connection), default is 5400.
• -s: Use stdio to accept control connections. Use only in production environment.
• --skip-deps-check: To ensure that all plugin dependencies are installed, the Runtime will check and install all installed plugin dependencies on every startup. Use this parameter to disable this check.

Make LangBot Use Your Locally Modified langbot-plugin-sdk

If you have modified things like message entities or plugin data definitions, you need to update them in the LangBot environment to ensure data format compatibility during runtime.

In a terminal with the LangBot directory's virtual environment (.venv) activated, switch to the langbot-plugin-sdk directory and run:

uv pip install .

This will install your modified langbot-plugin-sdk into LangBot's environment.

Make LangBot Connect to This Runtime

Configure plugin.runtime_ws_url to ws://localhost:5400/control/ws in LangBot's data/config.yaml.

plugin:
  runtime_ws_url: ws://localhost:5400/control/ws

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

DEBUG_RUNTIME_WS_URL=ws://localhost:5401/plugin/debug/ws
PLUGIN_DEBUG_KEY=<debug key copied from the WebUI>

4. Start the plugin from its project directory:

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 '<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:

# Terminal 1: langbot-plugin-sdk directory
python -m langbot_plugin.cli.__init__ box

Point LangBot's data/config.yaml at the local Box Runtime:

box:
  enabled: true
  backend: local
  runtime:
    endpoint: ws://127.0.0.1:5410

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

export LANGBOT_BOX_CONTROL_TOKEN='<the exact same high-entropy secret on both sides>'

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

This codebase contains the following:

• langbot_plugin.api: Plugin-related entities and API definitions.
• langbot_plugin.assets: Plugin templates.
• langbot_plugin.cli: Plugin development CLI tools.
• langbot_plugin.entities: Plugin system-related entities not defined in API.
• langbot_plugin.runtime: Plugin runtime and underlying communication (stdio and websocket) implementation.

lbp CLI Tool

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