comate-relay

远程 sandbox Agent 的中转服务。Agent（comate --rpc-relay）主动拨出到这里，桌面和手机也连这里，中转按连接原样转发。 中转不懂协议、不存业务状态：只存账号、Agent 记录和登录令牌（SQLite），重启只丢在线状态。

快速上手

comate-relay user add alice                     # 交互式输入两次密码；脚本里用 --password-stdin
comate-relay agent add --user alice --name box  # 打印 agent_id 和令牌，令牌只显示这一次
comate-relay serve                              # 默认只听 127.0.0.1:8765

启动后标准输出只有一行就绪信息：{"type": "ready", "url": "http://127.0.0.1:8765/", "insecure": false}。 浏览器打开这个地址就是 demo 页：登录 → 看自己名下的 Agent（在线状态、版本、主机名、工作目录）→ 点一个进会话。

远程终端默认不能把会话切到「全部放行」（bypassPermissions）：Agent 主人启动时加 comate --rpc-relay --allow-bypass 才放开。 没放开时切换会被拒，demo 页提示「这台电脑没有允许远程开启『全部放行』」。

局域网里用手机验收（Agent 跑在 docker 容器里）：见 acceptance/README.md。

子命令

接口

WebSocket 的令牌一律放子协议：["comate-rpc", 令牌]。

控制连接上的 agents 服务（用 comate_rpc 框架写，TS 类型在 packages/comate_rpc/ts/src/generated/relay/）：

传输安全

• 默认只听 127.0.0.1。
• 监听非本机地址：给 --certfile / --keyfile 就跑 HTTPS / WSS；都不给、也没加 --allow-insecure-http 就拒绝启动。
• 加了 --allow-insecure-http：启动，日志打 WARNING，就绪信息 insecure: true。只在可信的局域网里用。
• 放在反向代理后面：让中转只听本机或内网地址，由代理做 HTTPS。

配置与初值

没有配置文件，全部是命令行参数；除 --allow-insecure-http 外都有对应的环境变量，命令行优先。

登录失败计数按账号名记在内存里，最多 10 万个名字（实测约 10 MB），满了忘掉最久没被试过的；账号名最长 64 个字符。