连接你的 Grok Agent
Capricorn · AgentsHarness 的第一颗星座
AgentsHarness 让你随时随地远程使用 Agents。
Capri(Capricorn)是 Grok Build 的具体适配项目,我们基于 ACP 协议,搭配 capri-fe、capri-hub 实现远程 Agent 控制。
一个进程、一个端口,同时提供 Web 界面 和接口。macOS 上还提供一个菜单栏应用,负责 Host 启停、日志和设置入口,配置本身在网页设置页完成。
浏览器 ──本机──▶ Capri-host :8765 ──▶ grok
浏览器 ──远程──▶ capri-hub ──▶ Capri-host × N ──▶ grok
1、安装并登录 Grok Build(或设置 XAI_API_KEY)。
2、从 Releases 里选一种装上。
下载 Capri-vX.Y.Z-macos.zip(或 Capri-vX.Y.Z-macos.dmg,X.Y.Z 为所下载 Release 的版本号),把 Capri.app 拖进「应用程序」后打开。应用只提供 Apple Silicon(arm64)版本;Intel Mac 请从 Releases 取命令行二进制。
1、菜单栏会出现摩羯图标。
2、首次使用点击摩羯图标,选择「设置…」,浏览器会打开本机的 /settings 页面。
3、在网页里完成本机、Hub、代理和启动偏好配置,点击保存。
4、回到托盘菜单启动或重启 Host,再点「打开 Capri FE」即可进入本地 Web UI。
首次打开若被系统拦下,右键点「打开」,或:
xattr -dr com.apple.quarantine /Applications/Capri.app下载 Capri-vX.Y.Z-windows-amd64.zip(或 Capri-vX.Y.Z-windows-arm64.zip,按系统架构选择;X.Y.Z 为 Release 版本号),解压后进入 Capri
目录,双击 Capri.exe。
目录结构:
Capri/
├── Capri.exe 双击运行的就是它:托盘图标、对话框、Host 进程的启停
└── bin/
└── Capri-host.exe 干活的引擎(HTTP + grok),由 Capri.exe 拉起
引擎不要单独双击——它是个控制台程序,双击只会开一个黑窗口。整个目录一起保留,
Capri.exe 按相对位置找 bin/Capri-host.exe。
点击托盘菜单的设置进入网页设置界面,配置好即可保存,然后通过托盘菜单启动或重启 Host。
从 Releases 下对应平台的 Capri-host-*:
chmod +x Capri-host # 按实际文件名
./Capri-host可以只用环境变量配置,适合脚本、launchd、systemd,以及在服务器上跑。
git clone https://github.com/AgentsHarness/capri-host.git
cd capri-host
go run ./cmd/capri-host浏览器打开 http://localhost:8765。
要出 Windows 那套目录(Capri/Capri.exe + Capri/bin/Capri-host.exe,清单按架构生成):
./packaging/windows/make-exes.sh amd64 arm64macOS 应用同理:./packaging/macos/make-app.sh(arm64,macOS 13+)。
打包脚本会用 Keychain 里的签名身份签 app(优先 Capri Dev,CAPRI_CODESIGN_IDENTITY 可指定;
没有可用身份时退回 ad-hoc)。这一点对权限有实际影响:ad-hoc 签名的代码身份是 cdhash,
源码或版本一变,系统里已授权的屏幕录制等权限就失配,表现为反复弹权限提示。用证书签名则身份恒定,
授权一次即可。首次使用先跑一次 ./packaging/macos/make-cert.sh 创建本地自签证书。
在 tag 对应提交上、macOS 本机执行:
scripts/release-local.sh v0.5.1 --build-only
scripts/release-local.sh v0.5.1 --notes-file /tmp/notes.md脚本会先构建 ../acp-fe 并嵌入,再出 4 个平台二进制、Windows zip、macOS app/dmg,
产物在 dist/release/<tag>/。--allow-dirty 可带未提交改动出包。
在一台能被访问的服务器上先起 capri-hub,并部署 capri-fe,通过前端左上角添加 Host 获得配对码。
macOS 应用和 Windows 托盘都在网页设置页里填 Hub URL 和配对码,配对成功后地址会留在 config.json。
命令行启动则需要提供环境变量:
# 自行修改
HUB_URL=http://<hub>:8787
HUB_PAIR_CODE=XXXXXX
HOST_ID=pc
HOST_NAME="家里的 Mac"
FE_TOKEN=XXXXXX
nohup ./Capri-host >> Capri-host.log 2>&1 & echo $! > capri-host.pid配对成功后 token 写在 ~/.capri-host/hub.json,之后只需带 HUB_URL、FE_TOKEN 重启。浏览器打开独立部署的前端地址,选这台 Host 即可。
两处可配,环境变量优先于文件:
~/.capri-host/config.json——macOS 应用和 Windows 托盘读写的是同一份,也可以手写;- 环境变量——命令行、launchd、systemd 用这套,会覆盖文件里的同名字段。
所以装了应用之后依然可以临时 PORT=9000 ./Capri-host。
{
"bind": "127.0.0.1",
"port": 8765,
"host_id": "mba",
"host_name": "MacBook Air",
"hub_url": "https://agents.example.com",
"fe_token": "",
"grok_bin": "",
"hub_pair_code": "",
"proxy": "",
"no_proxy": ""
}测试或便携安装可设 CAPRI_HOME 换掉配置目录。
| 变量 | 默认 | 说明 |
|---|---|---|
PORT |
8765 |
HTTP 端口(界面 + 接口) |
BIND |
127.0.0.1 |
监听地址。默认只听回环,只有本机能够直连;要让手机等同网段设备访问,显式设 BIND=0.0.0.0——那必须同时设 FE_TOKEN,否则拒绝启动 |
GROK_BIN |
grok |
grok 可执行文件;留空则按常见路径探测 |
HOST_ID |
local |
多机时用来区分 |
HOST_NAME |
Local Host |
界面上的名字 |
XAI_API_KEY |
— | 可选;否则用 grok login |
HUB_URL |
— | 设置后连上 Hub |
HUB_PAIR_CODE |
— | 一次性配对码 |
FE_TOKEN |
— | 本机接口的访问密钥(/api/*、/events)。与 Hub 的 FE_TOKEN 是两把独立的钥匙,见下 |
HUB_QUIC_PIN |
— | 自签 hub 的 QUIC 证书指纹(见 docs/DEPLOY.md) |
PROXY |
— | 出网代理,可只写 host:port(自动补 http://)。留空则 macOS 读取系统网络设置里的代理;系统未开时直连 |
NO_PROXY |
— | 不走代理的地址列表,逗号分隔。留空则沿用系统网络设置里的排除列表 |
CAPRI_HOME |
~/.capri-host |
配置目录(config.json、hub.json 都在这下面) |
Hub 和每台 Host 各有一把 FE_TOKEN,它们保护的对象不同,不要求同值:
- 经 Hub 中继的请求由 Host 进程自己注入凭据,浏览器只出示 Hub 那把;
- 浏览器直连本机端口(
127.0.0.1:8765,省一跳延迟、Hub 挂了也还能用)时,出示的才是这台 Host 那把。
所以典型配法是:只在 Hub 上设 FE_TOKEN,Host 留空——回环 + 无密钥 = 近路是免鉴权的本机请求,
浏览器全程只问一次。给 Host 也设上一把同样可以:页面会先拿 Hub 那把探一次本机
(GET /api/probe),两把同值就不再多问,不同值才弹一次「这台 Host 的钥匙」。
Host 的密钥被拒只会让那一台退回 Hub 中继,不影响 Hub 登录。
| 项目 | 简介 |
|---|---|
| AgentsHarness | 总项目 |
| capri-hub | 中继节点,转发用户和 Agent 消息 |
| capri-fe | WebUI |
MIT

