RunBridge Hub

通过 HTTP / MCP，让程序和 Agent 使用远程设备上的浏览器。

简体中文 · English · 快速开始 · 完整文档 · 更新日志 · 问题反馈

RunBridge Hub 是 RunBridge 的服务端。它接纳浏览器设备上的 RunBridge Node，统一分配设备使用权、管理浏览器会话并转发操作结果。调用方通过 HTTP 或 MCP 使用远程浏览器，无需直接连接 Node 的浏览器端口。

适合自动化程序、Agent 工具接入，以及需要集中分配浏览器设备的测试团队。浏览器、Playwright 和页面对象留在 Node 设备，Hub 自身只需 Python 环境。

功能亮点

Related MCP server: Get Gather

实际效果

节点总览将设备连接、资源占用和能力放在同一页面，支持桌面与手机。点击节点可查看详情；总览使用独立只读口令。

截图来自本地验收场景，展示当时的数据。运行后的总览显示所连接 Hub 的实际状态；字段含义见节点总览指南。

工作方式

Hub 与 Node 分别部署：Hub 提供服务入口，Node 在浏览器所在设备执行。两者的配置、身份与运行环境各自独立。

快速开始

Hub 0.9.3 已发布至 PyPI，可按下方命令安装。也可从 GitHub Releases 下载安装包，再按独立目录安装指南部署，或使用源码安装路线。

从 PyPI 安装

准备 Python 3.14 与 uv，在新的部署目录执行。选择本方式后直接继续第 2 步；仅使用 HTTP 时可去掉 [mcp]。

镜像同步可能晚于首次发布。若下方阿里云镜像尚未提供此版本，可从 PyPI 文件列表下载 wheel，按独立目录安装指南安装。

mkdir -p ~/runbridge-hub
cd ~/runbridge-hub
uv venv --python 3.14 .venv
uv pip install --python .venv/bin/python "runbridge-hub[mcp]==0.9.3" -i http://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com
.venv/bin/runbridge-hub generate-token --output .runbridge/enrollment.token
.venv/bin/runbridge-hub generate-token --output .runbridge/hub.token

1. 安装 Hub

在 Hub 机器准备 Git、Python 3.14.x 和 uv。以下命令使用 macOS / Linux shell：

git clone https://github.com/Pegasus-Yang/Run-Bridge-Hub.git
cd Run-Bridge-Hub
uv sync --locked --no-dev -i http://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com
.venv/bin/runbridge-hub generate-token --output .runbridge/enrollment.token
.venv/bin/runbridge-hub generate-token --output .runbridge/hub.token

uv 在仓库根目录创建 .venv。两份凭据分别供 Node 登记和调用方领取 Node使用。已有 wheel 的独立目录安装方法见部署与运行。

2. 保存配置并启动

在当前安装目录创建 hub.yaml，将 public_url 换成 Node 与调用方实际可达的 Hub 基址：

host: 0.0.0.0
enrollment_token_file: .runbridge/enrollment.token
hub_token_file: .runbridge/hub.token
public_url: http://hub.example:8787

.venv/bin/runbridge-hub serve --settings hub.yaml

保留此终端，另开终端检查：

curl --fail http://127.0.0.1:8787/health

预期返回 {"status":"ok","protocol_version":2}。点击启动日志的 Dashboard URL 可打开节点总览；尚未登记设备时列表为空。凭据文件和包含只读口令的总览链接应妥善保管。

源码安装可按需补充 MCP 可选依赖；上面的 PyPI 命令已经包含此 extra：

uv sync --locked --no-dev --extra mcp -i http://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com

在 hub.yaml 增加 mcp_enabled: true 后重启。Agent 使用 Streamable HTTP 连接实际 Hub 基址后的 /mcp；连接参数与调用步骤见 MCP 接入。

3. 接入 Node，验证浏览器操作

将 Hub 基址与真实 enrollment.token 私密交给设备维护者，按 Node 快速开始上线设备。另向调用方提供独立 hub.token，按调用方教程领取 Node，保存返回的 .runbridge/access.json。

源码安装已经包含示例。PyPI 或 wheel 安装请先在部署目录按相同路径下载两份标准库脚本：

mkdir -p doc/reference/examples
curl --fail --location https://raw.githubusercontent.com/Pegasus-Yang/Run-Bridge-Hub/main/doc/reference/examples/%E6%89%A7%E8%A1%8C%E4%BC%9A%E8%AF%9D%E8%B0%83%E7%94%A8.py --output doc/reference/examples/执行会话调用.py
curl --fail --location https://raw.githubusercontent.com/Pegasus-Yang/Run-Bridge-Hub/main/doc/reference/examples/node_lease.py --output doc/reference/examples/node_lease.py

运行示例，打开网页、读取标题、保存 PNG、关闭会话并交还 Node：

.venv/bin/python doc/reference/examples/执行会话调用.py --access-file .runbridge/access.json --resource-id chromium --url https://example.com --screenshot .runbridge/page.png
.venv/bin/python doc/reference/examples/node_lease.py release --access-file .runbridge/access.json

资源 ID 使用 Node 实际上报的值，目标网页需由 Node 设备访问。核对截图内容、cleanup=COMPLETE 与租约 RELEASED。完整步骤与不依赖外部网站的示例见快速开始。

支持范围

• 当前 Hub 0.9.3，配套 Node 0.8.2，需要 Python 3.14.x；Hub 无需安装浏览器、Playwright 或 Node.js。

• 提供 33 项项目方法、27 个 MCP 工具。调用方式借鉴 Playwright，具体支持以方法表为准；官方 SDK 直连、任意脚本和 SDK 回调不在当前范围内。

• managed 浏览器支持 HTTP / MCP，borrowed Chrome 通过 HTTP 使用；页面画面用于观察，业务结果由调用方验证。

• 浏览器会话与 Node 租约分别释放。关闭浏览器后，整批任务结束还需交还 Node；清理未知时保持隔离，见租约接口。

文档与帮助

开发与贡献

欢迎通过 Issues 反馈或提交 Pull Request。请附上两端版本、运行环境、复现步骤和已隐藏秘密的错误信息。

源码开发使用根目录 .venv，依赖同步、pytest 与隔离联调见本地开发与联调；提交范围与验证要求见贡献指南。项目由 Pegasus-Yang（天马）维护。

许可证

本项目采用 MIT License。随 Hub 分发的 Phosphor Icons 保留其原始 MIT 许可证与版权声明，其他第三方依赖遵循各自的许可证。