AgentHub

简体中文 | English

个人 AI Agent 控制台

AgentHub 用来统一管理你自己机器上的 Codex、Claude、Kimi、OpenCode 等本地 agent runtime。

你可以把 server 跑在笔记本、本地工作站或 VM 上，通过 Tailscale private mode 或 HTTPS public relay 接入；然后在 Web、Android、Windows 桌面端统一控制多台电脑、多条终端 session、多个 agent backend。

AgentHub 不是托管 SaaS，也不是任意远程 shell。agent 继续运行在你的机器上，使用你的文件、工具和运行环境；AgentHub 负责会话收件箱、控制界面、worker 接入和审计记录。

架构关系和部署形态见：架构图

它解决什么

• 统一会话收件箱。 把本机和远程机器上的 Codex、Claude、Kimi、OpenCode 会话放到同一个入口。
• 多机器控制。 Windows、Linux 和 macOS worker 都可以接入，消息、健康检查和任务会路由到对应机器。
• 手机和桌面都能用。 Web、Android、Windows 和 macOS 桌面端可以接入同一个 AgentHub server；客户端首启先配置自己的 server URL。
• Tailscale-first 私有模式。 不需要把 worker 端口暴露到公网，也能从手机控制本机 agent。
• Public relay 公开入口。 如果你有域名和 HTTPS 反代，也可以把 Web/App 入口放到公网，worker 仍然可以只走私网或出站连接。
• 配置优先。 语音识别、服务器地址、worker 根目录、provider 密钥都走配置，不写死维护者环境。
• 1.0 Workbench Mode。 在保留 Session 控制台的基础上，新增异步任务工作台：写任务书、派发到本地 worker、跟踪执行与 artifact、验收或要求返工。

典型使用场景

• 只有一台主力电脑。 直接在 Windows、macOS 或 Linux 上跑 AgentHub server，通过 Tailscale 地址让手机和桌面端接入；worker 可以和 server 在同一台机器上。
• 一台云端 VM + 多台本地电脑。 VM 提供稳定 HTTPS 入口，本地 Windows / Linux / macOS worker 通过 Tailscale private mode 或 public relay 接入，适合长期在线和多机器协作。
• 手机查看和轻量控制。 Android APK 首启填写你的 server URL，之后用同一个账号查看 session、发回复、处理审批和查看状态。
• 不想暴露 worker。 只把 Web/API 入口暴露给 HTTPS，worker 继续通过 Tailscale 或出站连接通信，不开放 SSH、数据库或 worker 端口。
• 给工程 agent 部署。 把 Deployment brief template 填好，再让 Codex / Claude Code 按 AI deployment runbook 执行。

小技巧：

• 本机 server 场景下，Android 里优先填 Tailscale DNS 或 100.x.y.z 地址，避免局域网 IP 变化。
• 公网 VM 场景下，Web/App 入口必须使用 HTTPS；普通公网 http:// 不应该用于登录态。
• worker 可以和 server 同机，也可以分布在多台电脑上；AgentHub 只负责任务路由和状态同步，agent runtime 仍然使用 worker 本机环境。
• React Native iOS 客户端已经进入源码和 CI 支持面，可完成 Simulator 编译；安装到真机或发布 App Store 仍需要 Apple 签名、provisioning 和真机验证。
• macOS desktop 已进入自动打包链路；公开分发的签名和 notarization 需要维护者在 GitHub Actions 配置 Apple 凭据。

快速开始

先选一种 server 安装模式，再抄对应命令：

模式	适合谁	默认入口	第一步
本机模式	只有一台主力电脑，先把自己的 agent 跑起来	http://localhost:43073	npm run local:dev
Docker 模式	已有 Docker，希望少碰 Python/Node 运维细节	http://localhost:8080	docker compose -f deploy/docker-compose.selfhost.yml up -d --build
VM 模式	需要长期在线、HTTPS 和公网入口	https://agenthub.example.com	`curl -fsSL https://myagenthub.dev/install.sh

完整对比见：

• Local server mode
• Docker self-host mode
• Self-host quickstart

官网版安装选择页：

• https://myagenthub.dev/install/
• https://myagenthub.dev/download/
• https://myagenthub.dev/release/
• https://myagenthub.dev/press/

装 worker：直接走 npm / npx

如果你的 server 已经起来了，单独给 Windows、Linux 或 macOS 机器装 worker 时，优先走这个入口：

npx agenthub-worker doctor
npx agenthub-worker install --api-url https://agenthub.example.com --enrollment-token ahe_worker_enroll_xxx --platform linux --worker-id build-vm-01 --workspace-root /srv/work

Windows 和 macOS 机器同样使用 npx agenthub-worker install。macOS 使用 --platform macos --workspace-root "$HOME/Work"，并以当前用户的 LaunchAgent 常驻；详见 macOS Worker。

推荐方式：直接给另一个 agent 一份部署提示词

如果你想最快部署，优先从这两个文件开始，让另一个 agent 或实施人员直接照着执行：

• AI deployment runbook
• Deployment brief template

这条路径适合：

• 你想把部署交给 Codex、Claude Code 或其他工程 agent
• 你不想自己手动拼接安装命令和配置项
• 你要在本机、Tailscale 或 VM 三种模式之间快速切换

部署完成后：

• Android APK 首启先填写 AgentHub server URL
• 然后进入对应站点的登录页
• 不是免登录，而是先选自己的 server，再登录自己的账号

本机模式：一条命令拉起本地控制台

适合已经在用 Tailscale，只想先让手机或桌面端接管本机 agent 的场景。默认本机端口组是：

• Web/UI: http://localhost:43073
• API/healthz: http://127.0.0.1:43080

copy .env.example .env
python -m venv .venv
.\.venv\Scripts\python -m pip install -r apps/api/requirements.txt
npm install
npm run local:dev

打开 http://localhost:43073，用 AGENTHUB_BOOTSTRAP_TOKEN 创建第一个 owner，然后在 Android 或 Windows 桌面端填入本机或 Tailscale 地址。

指南：Local server mode

Docker 模式：用 compose 起一个完整控制面

适合想要统一容器化，但暂时不想自己手装 Python、Node.js、nginx 或 systemd 的场景。

cp .env.example .env
docker compose -f deploy/docker-compose.selfhost.yml up -d --build

默认入口：

http://localhost:8080

指南：Docker self-host mode

有公网入口：用 HTTPS 自托管到 VM

适合需要长期在线、worker bundle 下载、公网入口或 public relay 的场景。

最快入口：

curl -fsSL https://myagenthub.dev/install.sh | bash -s -- \
  --domain agenthub.example.com \
  --install-root /opt/agenthub \
  --admin-email you@example.com

仓库内脚本入口：

sudo bash scripts/install-selfhost-linux.sh \
  --domain agenthub.example.com \
  --install-root /opt/agenthub \
  --admin-email you@example.com

指南：Self-host quickstart

如果你想先比对三条路径的差异，再决定装哪一种，官网完整版在这里：

• https://myagenthub.dev/install/
• https://myagenthub.dev/download/
• https://myagenthub.dev/release/

当前支持范围

端	状态	说明
Web self-host	已支持	主控制台和 API
Android APK	已支持	首启先配置 server URL，再进入登录
React Native Android	1.0 候选	会话、任务、文件、图片、语音、审批和通知；Release 同时产出 APK/AAB
Windows desktop	已支持	Electron 客户端，首启配置服务器
macOS desktop	1.0 候选	自动构建 DMG/ZIP；公开分发需签名与 notarization
Windows worker	已支持	bundle + PowerShell 安装脚本
Linux worker	已支持	bundle + shell/systemd 安装脚本
macOS worker	已支持	bundle + 每用户 LaunchAgent 安装脚本
iOS client	源码与 CI 支持	React Native 客户端可通过 Simulator 编译；签名 IPA/真机分发尚未完成

文档入口

• English README
• Architecture diagrams
• Local server mode
• Docker self-host mode
• Self-host quickstart
• Tailscale private mode
• Configuration reference
• Public website deployment
• Branding and logo source
• Worker package release
• macOS Worker
• Deployment
• Security model
• Testing
• OSS release flow
• Open-source launch checklist
• Launch copy
• Contributing

构建

npm run web:build
npm run desktop:build
npm run desktop:package:win
npm run desktop:package:mac
npm run mobile:build:debug
npm run mobile:build:release
npm run mobile:native:build:android:debug
npm run mobile:native:build:android
npm run mobile:native:build:ios

生成可下载的 worker bundles：

.\.venv\Scripts\python.exe scripts\build-worker-bundle.py --output-root .runtime\worker-bundles

验证

npm run api:test
npm run web:test
npm run web:build
npm run desktop:test
npm run mobile:test
npm run mobile:native:test
npm run mobile:native:typecheck
npm run release:version:check
.\.venv\Scripts\python.exe scripts\audit-public-export.py

公开仓不应该包含私有生产域名、部署凭据、本地数据库、运行日志、签名密钥或生成出的 release 产物。