RunBridge Node

Make a local browser available to remote programs and agents.

简体中文 · English · Quick start · Documentation · Changelog (Chinese) · Issues

RunBridge Node is the browser execution component of RunBridge. It runs on the browser device, connects to RunBridge Hub, executes Playwright operations in an independent Python worker, and sends results and page frames back to Hub.

Use it to provide an isolated browser test environment, or to reuse an existing Chrome instance's pages and login state with its owner's authorization. Programs and agents access the device through Hub's HTTP / MCP interface; Node manages browser processes, endpoints, and page objects locally.

Highlights

How it works and which mode to choose

Inspect online status, occupancy, and capabilities in the Hub dashboard. Managed mode is headless by default; subscribe to page frames through Hub. Node does not have a separate web management UI.

Quick start

Install from PyPI after this version is published

Prepare Python 3.14, uv, and Hub enrollment material as described below. Until upload, use the source route. With this installation, continue at step 2.

mkdir -p ~/runbridge-node
cd ~/runbridge-node
uv venv --python 3.14 .venv
uv pip install --python .venv/bin/python "runbridge-node[playwright]==0.8.2" -i http://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com
.venv/bin/python -m playwright install chromium

1. Install Node and prepare Chromium

On the Node device, prepare Git, Python 3.14.x, and uv. First obtain a reachable Hub base URL and the original enrollment.token from the Hub deployer. Save the token file to ~/Downloads/.

These commands use a macOS / Linux shell and install managed Chromium support:

git clone https://github.com/Pegasus-Yang/Run-Bridge-Node.git
cd Run-Bridge-Node
uv sync --locked --no-dev --extra playwright -i http://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com
.venv/bin/python -m playwright install chromium

uv creates .venv at the repository root. Linux also needs the browser's system libraries; see the Playwright browser guide. For installation from a wheel in a separate directory, see deployment.

2. Save enrollment material and configuration

umask 077
mkdir -p .runbridge
cp -n ~/Downloads/enrollment.token .runbridge/enrollment.token
chmod 600 .runbridge/enrollment.token

Create node.yaml in the current installation directory, replacing hub_url with the actual Hub base URL:

hub_url: http://hub.example:8787
enrollment_token_file: .runbridge/enrollment.token
tools:
  playwright: {}

This uses managed, headless Chromium, resource ID chromium, and identity file .runbridge/node.json. Relative paths resolve from the YAML file's directory.

3. Connect and hand off the resource

.venv/bin/runbridge-node run --settings node.yaml

Leave the terminal running. First startup enrolls, probes the browser, and connects; later starts reuse the identity. A separate register command is unnecessary.

Give the logged node_id, resource ID, and mode to the Hub deployer or client. Confirm ONLINE, fresh capabilities, and resource READY / FREE in Hub's dashboard. Follow the Hub client guide to claim Node, operate the page, close the session, and return Node. First startup needs neither a client access file nor Hub's claim credential in the Node process.

Supported scope

• Current Node: 0.8.2, paired with Hub 0.9.3. Python 3.14.x and matching Python Playwright are required. No separate Node.js/npm deployment or Playwright BrowserServer is needed.
• 33 project methods are explicitly implemented; see the Hub method reference. Hub provides HTTP / MCP; Node performs local execution.
• A Node browser resource accepts one active session at a time. Use independent Node instances for concurrent tasks on the same machine.
• Borrowed authorization covers the entire browser instance. Completed page operations persist; releasing resources does not undo business changes.
• Browser sessions and Node leases are released separately. Return Node at batch end; a maintainer reviews unknown cleanup.
• Some CLI messages and Hub dashboard labels remain Chinese. Browser locale defaults are unchanged by the English documentation.

Documentation and help

Development and contributions

Use Issues or submit a Pull Request. Include both component versions, OS, browser version and mode, reproduction steps, and redacted errors.

Development uses the root .venv. The contribution guide covers setup and validation and links to the detailed development manual in Chinese. Maintained by Pegasus-Yang.

License

This project uses the MIT License. Third-party dependencies retain their respective licenses.