连接远程 Holon 运行时

在一台机器上运行 Holon，从另一台机器使用它——团队共享服务器、无头主机，或远程开发机。本页帮你选访问方式、建立连接，并确认连接可用。

访问模式

holon daemon start 和 holon serve 都接受 --access 标志：

远程服务端

Tunnel 模式（Cloudflare）

启动一个可通过 Cloudflare Tunnel 访问的 daemon：

holon daemon start --access tunnel

也可以使用独立的服务端：

holon serve --access tunnel

隧道生命周期由运行时管理。你这边不需要任何 Cloudflare 配置——Holon 会自动创建并管理临时隧道。

Tailnet 模式（Tailscale）

在自己设备之间做私有 mesh 访问：

holon daemon start --access tailnet
holon serve --access tailnet

需要宿主机已安装并认证 Tailscale。

LAN 模式

同网络、已知 IP 时使用：

holon serve --access lan --host 192.168.1.10 --port 8787

自定义主机和端口

覆盖默认监听地址：

holon daemon start --access tunnel --port 9000
holon serve --access lan --host 0.0.0.0 --port 8787

远程连接

TUI 连接

从远程终端连接：

holon tui --connect https://your-server:8787 --token "your-token"

从文件读取 token：

holon tui --connect https://your-server:8787 --token-file ~/.holon/remote.token

使用已保存的 token profile：

holon tui --connect https://your-server:8787 --token-profile my-profile

HTTP API

同一个 token 也用于认证 HTTP 控制平面请求：

curl -H "Authorization: Bearer your-token" \
  https://your-server:8787/api/agents/list

完整 API 面见 HTTP 控制平面参考。

Token 管理

提供 token

Holon 不会替你生成控制 token。自己选一个密钥，通过 --token、--token-file 或 HOLON_CONTROL_TOKEN 环境变量交给服务端：

# 从文件读取控制 token
holon daemon start --access tunnel --token-file ~/.holon/remote.token

Token profile

把多个 token 存成命名的凭据 profile，再按名字选用：

holon config credentials set office --kind bearer_token --stdin
holon config credentials set home --kind bearer_token --stdin

然后按 profile 名连接：

holon tui --connect https://office:8787 --token-profile office
holon tui --connect https://home:8787 --token-profile home

通过 Android 客户端进行移动端访问

你也可以使用原生的 Holon Android 客户端在手机或平板上连接远程运行时。输入远程 HTTPS 基础 URL 和访问凭据即可建立经过系统 Keystore 加密的移动端会话。详见连接 Android 客户端。

Daemon 管理

daemon 启动后，常规管理命令都能远程使用：

holon daemon status
holon daemon logs
holon daemon restart
holon daemon stop

安全注意事项

• 始终使用 token。只要监听非回环地址，或使用 --access lan/--access tailnet，Holon 就会拒绝在没有 token 的情况下启动。--access tunnel 也应设置 token：隧道是公网可达的。
• 跨公网连接时优先用 tunnel 或 tailnet，而不是 LAN 模式。它们提供加密和认证，无需暴露裸端口。
• 轮换 token：用新的 --token-file 重启 daemon。
• 只需要本机连接时用 --access local。这是默认值，也是最安全的选择。
• HTTP 控制平面会执行信任边界规则：即使是只读路由（Agent 状态、事件、任务），远程访问也仍然需要有效 token。
• 团队部署与多用户：在多成员协作环境中，建议配置 OIDC 身份认证（auth.mode = "oidc"），使用企业单点登录取代单一共享 Token，并审计各操作人身份。参见配置 OIDC 身份认证。

另请参阅

• TUI 参考 — 导航、斜杠命令和远程连接
• HTTP 控制平面 — 编程访问的 API 参考
• 排查 Holon 任务问题 — 连接问题
• 通过 HTTP 自动化 Holon — 用代码驱动 Holon
• 配置 OIDC 身份认证 — 单点登录与审计归属
• 连接 Android 客户端 — 在移动设备上管理 Agent