跳转至

快速开始

安装 Master 与 Worker，获取 client token，再通过 MCP 或 CLI/skill 连接 AI Agent。进阶内容（Docker 重建、宿主机 Worker、Nginx、故障排查）见 部署指南。

环境前提

组件 要求
Python 运行 deploy.py 需要 3.10+；运行时 Python 3.12 由 uv 自动管理
Git 任意较新版本
Docker + Docker Compose Master 必需；Worker 容器模式必需。需要 Docker Compose V2（docker compose 子命令）
操作系统 Linux / macOS / Windows

部署前不需要自行安装 Python 依赖。deploy.py 会自动安装 uv、Python 3.12、 虚拟环境以及运行时依赖。

第一步：安装并配置 Master

将 Master 安装在 Worker 和 Client 可以访问的机器上（公网服务器或同一内网）， 并填写合适的 <服务地址>。

公网部署提示： 面向公网时推荐配合域名在 Master 前挂 Nginx/TLS 反代， 走标准 443 端口。详见 部署指南中的 Nginx 配置。 <服务地址> 填写反代地址，例如 https://master.example.com。

局域网部署提示： 内网场景下 <服务地址> 应填 Master 主机的局域网 IP 加端口，例如 http://192.168.1.10:9210。确保防火墙允许 TCP 9210 入站 （Docker 默认监听 0.0.0.0:9210）。

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/tappat225/CapOwn/master/scripts/install.sh | sh -s -- master --public-url <服务地址>

# Windows PowerShell
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/tappat225/CapOwn/master/scripts/install.ps1))) -Component master -DeployArgs "--public-url <服务地址>"
或手动 clone 仓库安装 
git clone https://github.com/tappat225/CapOwn.git
cd CapOwn
python3 deploy.py install master --public-url <服务地址>
中国大陆 / 受限网络环境 
python3 deploy.py install master --public-url <服务地址> --mirror-cn

如果安装后想修改地址：

capown-master config set public-url <服务地址>

~/.capown/bin 会尽量自动加入 PATH。如未能自动配置，安装程序会打印手动添加的命令。

自动创建 starter 用户

首次安装时，会自动创建 starter 用户 chiral 和 bundle enrollment token。 部署输出中会显示生成的 Worker 和 Client 安装命令。Client 安装命令仅供 CLI/skill 使用；若使用 MCP，可直接兑换同一 enrollment URL 获取 client token，无需安装 CapOwn Client。

为其他用户创建 enrollment bundle：

capown-master tokens create alice

若用户 alice 还不存在，该命令会先创建用户，然后打印可直接执行的安装命令：

Worker: python3 deploy.py install worker https://master.example.com/api/enroll/cown_tmp_xxxxx
Client: python3 deploy.py install client https://master.example.com/api/enroll/cown_tmp_xxxxx
Files:  ~/.capown/master/enrollments/alice

请将 enrollment URL 和生成的文件视为机密。token 有效期内可注册多台设备。 默认 bundle token 有效期为 24 小时；可通过 --ttl <秒数> 覆盖。

第二步：安装 Worker

在希望被 Agent 远程调度的机器上安装：

  • 可指定 enrollment URL，通过 Master 分配的链接注册。
  • 可指定 --workspace /srv/my-project 设置沙盒工作目录。
# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/tappat225/CapOwn/master/scripts/install.sh | sh -s -- worker https://master.example.com/api/enroll/cown_tmp_xxxxx

# Windows PowerShell
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/tappat225/CapOwn/master/scripts/install.ps1))) -Component worker -Source "https://master.example.com/api/enroll/cown_tmp_xxxxx"
或手动 clone 仓库安装 
git clone https://github.com/tappat225/CapOwn.git
cd CapOwn
python3 deploy.py install worker https://master.example.com/api/enroll/cown_tmp_xxxxx

默认使用容器执行模式。Worker 宿主机默认工作目录为 ~/.capown/workspace， 挂载到容器内路径 /workspace。Bundle enrollment 下发的 TOML 与此默认一致 （execution_mode = "container" + home 相对 workspace 预设）。

后续可修改执行模式、workspace、超时等，详见 Worker 配置。

第三步：获取 Client 凭据

Master 的 MCP 和 REST API 都使用正式的 client token 鉴权。使用 MCP 时 不需要安装 CapOwn Client。访问 enrollment URL 时，Master 会消耗临时 token 的 client 名额并签发可撤销的 client token（无自动过期——请像 密钥一样保存与轮换）。

方式 A：直接使用 MCP，无需安装 Client

curl -fsS \
  -H "X-CapOwn-Enrollment-Role: client" \
  "https://master.example.com/api/enroll/cown_tmp_xxxxx"

Master 会返回包含 master_url 和 client_token 的 TOML。将 client_token 配置到 MCP Host 即可，不需要运行 deploy.py install client，也不需要安装 capown CLI。

enrollment URL 的 client 名额默认只能兑换一次。响应中包含明文 bearer token，请作为机密保存。

方式 B：安装 CLI/skill Client

需要 capown CLI 或 Agent skill 时再安装 Client：

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/tappat225/CapOwn/master/scripts/install.sh | sh -s -- client https://master.example.com/api/enroll/cown_tmp_xxxxx

# Windows PowerShell
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/tappat225/CapOwn/master/scripts/install.ps1))) -Component client -Source "https://master.example.com/api/enroll/cown_tmp_xxxxx"
或手动 clone 仓库安装 
git clone https://github.com/tappat225/CapOwn.git
cd CapOwn
python3 deploy.py install client https://master.example.com/api/enroll/cown_tmp_xxxxx

验证连通性：

capown workers                    # 列出可用 Worker
capown info <worker>              # 查看 Worker 详情
capown run <worker> "echo hello"  # 执行远程命令

第四步：连接 AI Agent

MCP

https://<master-host>/mcp
Authorization: Bearer <client-token>

配置、认证、Origin 策略见 MCP 指南。完整反向代理配置见 部署指南。

此路径不依赖本地 CapOwn Client。

CLI / skill（无 MCP Host）

将下面的 skill 链接发给 AI Agent：

https://raw.githubusercontent.com/tappat225/CapOwn/master/skills/capown-client/SKILL.md

若 Agent 已在本地仓库中工作，也可指向 skills/capown-client/SKILL.md。

四步流程： Master（含 enrollment）-> Worker -> 获取 client token -> MCP（无需安装 Client）或 CLI/skill。

高级选项（TOML enrollment、宿主机/容器模式、Nginx、直接 API、长任务）见 用户指南 与 部署指南。

卸载

python3 deploy.py uninstall worker          # 移除服务和运行时，保留配置
python3 deploy.py uninstall worker --purge  # 同时删除配置和数据
python3 deploy.py uninstall client
python3 deploy.py uninstall master --purge

添加 -y 跳过确认。详见 部署指南。

常见问题

注册 token 链接泄露了怎么办？

若公网可访问的 token 链接被陌生人获取，请立即在 Master 上重新生成 bundle token：

capown-master tokens create <用户名>

新 token 生成后旧 token 会自动失效（每个用户同一时间只允许一个活跃 bundle token）。同时：

  1. 检查已连接的 Worker： capown-master health 查看当前在线 Worker 列表， 确认没有被泄露 token 注册的可疑设备。
  2. 断开可疑 Worker（Master 端或其他管理层面）。
  3. 轮换凭据： 如果泄露的 token 已被用于注册 Worker 或 Client，考虑重新部署 对应设备的凭据。

默认 bundle token 有效期为 24 小时（可通过 --ttl 调整），泄漏后影响范围受此 窗口限制。

没有公网服务器怎么办？

如果 Master 和 Worker 都在同一局域网内，可以直接使用内网 IP 地址部署，无需公网 服务器。

如果需要跨网络但没有公网服务器，可借助 Tailscale、ZeroTier 等工具搭建虚拟局域网，在其中一台设备上运行 Master 即可。