Files
LangBot/docs/en/plugin/compatibility.mdx
bdc0dc11e1 refactor(runtime): use stdio for Core-launched Plugin/Box runtimes on Windows (#2952)
Plugin and Box now share one transport rule via
ManagedRuntimeConnector.select_runtime_transport(): an explicit endpoint,
Docker or --standalone-* means WebSocket to an external runtime; every
other case (Windows, Linux, macOS) launches the runtime as a child
process and talks over its stdio pipes.

The Windows-only "subprocess + WebSocket" branch is removed from both
connectors together with its helpers (control-token generation, port
probing, readiness polling, subprocess disposal). Since langbot-plugin
0.6.0 the runtime side reads/writes stdio from blocking threads on
Windows, so the WinError 6 that motivated the branch no longer applies.

Docs (zh/en/ja compatibility + deep-dive, ARCHITECTURE.md, dev-docs
reviews) now describe the actual transports, including the Windows
runtime-to-worker WebSocket on the plugin debug port.

Refs #2545

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: multica-agent <github@multica.ai>
2026-11-09 20:01:35 +08:00

33 lines
2.2 KiB
Plaintext

---
title: "System Compatibility"
---
The LangBot plugin system consists of three layers of processes: the LangBot main program, the Plugin Runtime, and one worker process per plugin. This page explains how these layers communicate on each operating system.
## LangBot and the Plugin Runtime
The transport between LangBot and the Plugin Runtime depends only on who starts the Runtime, not on the operating system:
| Deployment | Transport |
|---|---|
| Running LangBot directly (Windows / Linux / macOS) | LangBot launches the Plugin Runtime as a subprocess and communicates over the subprocess's stdio |
| Docker | WebSocket to `plugin.runtime_ws_url` (default Compose service `langbot_plugin_runtime:5400`) |
| Started with `--standalone-runtime` | WebSocket to `plugin.runtime_ws_url`; you start the Runtime yourself |
The Box Runtime follows the same rule: stdio when LangBot runs directly; WebSocket under Docker, with `--standalone-box`, or when `box.runtime.endpoint` is configured.
<Note>
On Windows, asyncio's `ProactorEventLoop` cannot register the anonymous pipes a subprocess inherits with IOCP, so calling `connect_read_pipe` / `connect_write_pipe` on them fails with `WinError 6`. Since `langbot-plugin` 0.6.0 the Runtime reads and writes stdio from blocking background threads on Windows, so LangBot uses stdio on Windows just as it does on Linux / macOS, with no extra configuration.
</Note>
## The Plugin Runtime and plugin workers
The Plugin Runtime launches one worker subprocess for each installed plugin:
- **Linux / macOS**: communicates over the worker subprocess's stdio.
- **Windows**: the Runtime launches the worker as a subprocess, and the worker connects back to the Runtime's plugin debug port over WebSocket (`ws://localhost:<port>/plugin/ws`).
The debug port defaults to `5401` and follows the port in `plugin.display_plugin_debug_url`. On Windows, make sure this port is free and that loopback connections are not blocked by a firewall. When running several LangBot instances on the same machine, give each instance a different `display_plugin_debug_url` port.
LangBot selects all of the above automatically from the deployment and the operating system; you do not need to configure the transport manually.