基于 ACP 协议的远程 Agent 控制台
把本机的 Agent，装进任何一块屏幕
手机、平板、另一台电脑的浏览器里，继续本机正在跑的会话。Agent 仍然在你自己的机器上读文件、跑命令；浏览器只负责掌控。
// 一个进程、一个端口，同时提供 Web 界面和接口。
P01
浏览器 — 只负责掌控：发指令、看结果、审批权限。门禁密钥存在本地，不进构建产物。
0组件
0端口起步
0位配对码
0分钟有效
0命令在中继执行
§1
三个组件
BILL OF MATERIALS| Item | 变量 | Port | 说明 |
|---|---|---|---|
| A01 | Capri FE React 19 · TypeScript · Vite · Tailwind |
:5173 开发服务器；生产由 Host 内嵌托管 |
对齐终端界面常用能力的 Web 前端：斜杠命令、权限审批、图片、后台任务、Git / MCP / 记忆。左上角随手切换机器。
|
| A02 | Capri Host Go 1.26 · ACP · stdio JSON-RPC |
:8765 界面 + 接口同端口 |
跑在有 Agent 的那台机器上，自动拉起内核，并把 Web 界面一起端出来。不用 nginx，不用另起静态服务器。
|
| A03 | Capri Hub Go 1.26 · QUIC · WebSocket |
:8787 HTTP；节点主通道 UDP 8788 |
汇集你所有的节点：家里的、办公室的、服务器上的。它不执行任何命令，只做配对、发现和转发。
|
§2
能力
SPECIFICATIONS
2.1
换个屏幕，接着说
在手机、平板、另一台电脑的浏览器里，继续本机正在跑的会话。恢复会话不重放全量历史，打开就能接上。
2.2
多台机器，一个入口
左上角切换节点：家里的、办公室的、服务器上的。每台机器一个标识，中继负责找到它。
2.3
该有的都有
斜杠命令、权限审批、图片、后台任务、Git / MCP / 记忆——对齐终端界面的常用能力。
2.4
代码不出你的机器
Agent 在节点那台机器上自己读文件、跑命令。浏览器只发指令、看结果。中继不执行任何命令。
2.5
一个进程，一个端口
节点二进制里嵌着前端构建产物，打开根路径就是界面，同端口提供接口。不用 nginx。
2.6
先 QUIC，挡了就退
节点到中继默认走 QUIC；UDP 被挡时自动回退 WebSocket，功能不受影响。域名经代理丢 UDP 时可强制拨号地址。
2.7
配一次，之后就忘了它
中继启动打印六位配对码，十五分钟有效。配对成功后 token 写在那台机器上，重启只需要中继地址。
2.8
没人看的时候安静
中继模式下没有浏览器订阅时，节点暂停实时上报以省流量；打开页面自动恢复。
// 只在一台机器上用？不必起中继，直接跑节点即可。
§3
快速开始
PROCEDURE3.1 本机：一条命令
chmod +x ./capri-host
./capri-host
# 浏览器打开 http://localhost:87653.2 从源码跑
go run ./cmd/capri-host3.3 起中继
FE_TOKEN=$(openssl rand -hex 24) go run ./cmd/capri-hub3.4 把节点接进来
HUB_URL=http://your-relay:8787 \
HUB_PAIR_CODE=XXXXXX \
HOST_ID=macbook HOST_NAME="办公室 Mac" \
./capri-host3.5 查看 / 换新配对码
curl http://127.0.0.1:8787/api/pairing
curl -X POST http://127.0.0.1:8787/api/pairing/rotate3.6 前端开发
npm install
npm run dev
# 代理默认指向本机节点；换目标：
VITE_PROXY_TARGET=http://your-relay:8787 npm run dev§4
环境变量
PARAMETERS| Scope | 变量 | 默认 | 说明 |
|---|---|---|---|
| 节点 | PORT | 8765 | HTTP 端口（界面 + 接口） |
| 节点 | GROK_BIN | grok | Grok Build 可执行文件 |
| 节点 | HOST_ID | local | 多节点时用来区分 |
| 节点 | HOST_NAME | Local Host | 界面上显示的名字 |
| 节点 | FE_TOKEN | — | 入口鉴权；与中继同语义，建议同值 |
| 节点 | HUB_URL | — | 设置后进入中继模式 |
| 节点 | HUB_PAIR_CODE | — | 一次性配对码 |
| 节点 | HOST_TOKEN | — | 已配对 token，优先于配对码 |
| 节点 | XAI_API_KEY | — | 可选；否则用内核自带登录 |
| 节点 | HUB_QUIC_HOST | — | 强制 QUIC 拨号地址（代理丢 UDP 时用） |
| 中继 | PORT | 8787 | HTTP 端口 |
| 中继 | QUIC_PORT | 8788 | 节点主通道 UDP 端口 |
| 中继 | FE_TOKEN | — | 浏览器访问密钥，生产必设 |
| 中继 | REQUIRE_FE_TOKEN | — | 设为 1 时，没配密钥会拒绝启动 |
| 中继 | CORS_ORIGINS | * | 生产写成前端真实源 |
| 前端 | VITE_PROXY_TARGET | http://localhost:8765 | 开发代理目标 |
§5