# CapOwn **Repository Path**: TappaT/CapOwn ## Basic Information - **Project Name**: CapOwn - **Description**: No description available - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-07-03 - **Last Updated**: 2026-07-08 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README
# CapOwn **多主机远程操作与 AI Agent 协调系统** English | 简体中文
[![License](https://img.shields.io/badge/license-AGPL--3.0--only%20%2F%20Apache--2.0-blue)](LICENSE) [![Python](https://img.shields.io/badge/python-%3E%3D3.9-3776AB?logo=python&logoColor=white)](https://www.python.org/) [![Issues](https://img.shields.io/github/issues/tappat225/CapOwn)](https://github.com/tappat225/CapOwn/issues) [![Pull requests](https://img.shields.io/github/issues-pr/tappat225/CapOwn)](https://github.com/tappat225/CapOwn/pulls)
用户指南 | 部署指南 | 问题反馈 | 贡献说明

CapOwn 让本地 AI Agent 可以使用其他机器作为远程执行双手。Worker 主动向 Master 建立 HTTPS/SSE 出站连接，因此 NAT 后面的机器不需要公网 IP，也不需要开放入站端口。传输可以直接走标准 HTTPS 443 端口，使用 SSE 而不是 WebSocket，在许多受限网络环境里更容易使用。

CapOwn architecture: AI Agent connects through Master to outbound-only Workers

**一个 Agent。多台设备。无需入站端口。最小信任中继。** > **CapOwn 本身不是 AI Agent**，它兼容 Claude Code、Codex 等你已经在用的 Agent 工具，让它们获得跨设备远程执行能力。 ## 为什么需要 CapOwn 现代 AI 编程 Agent 经常知道该做什么，但真正能执行任务的机器在另一处：NAT 后面的 Linux 测试机、带 GPU 的工作站、NAS，或装有本地工具的桌面。 CapOwn 专注解决这个问题： - 在另一台机器上安装轻量 Worker - 让本地 Agent 发现这台机器 - 通过 Master 中继执行文件、Shell 和系统信息任务 - 返回结构化结果和机器可读错误 ## 核心功能 - **🚀 Worker 全出站连接** - Worker 通过 HTTPS + SSE 连接 Master - **🌐 网络环境友好** - 可直接走标准 HTTPS/443，不依赖 WebSocket - **🤖 Agent 友好动作** - Shell、文件读写/列目录、系统信息 - **📦 紧凑能力词表** - `shell.run`、`file.read`、`file.write`、`file.list`、`system.info` - **⚠️ 结构化错误** - 机器可读错误码：`worker_offline`、`workspace_violation`、`timeout`、`output_too_large` - **🔒 Workspace 控制** - 文件和 Shell 操作按 Worker 配置的 workspace 解析路径 - **⚡ 同步与异步任务** - 短任务同步返回，长任务可 dispatch 后轮询状态 - **🐳 灵活执行方式** - Docker 隔离或可信宿主机原生执行 - **👥 多用户 Master** - 按用户隔离 token，强制节点归属 - **📝 配置驱动部署** - TOML 文件或临时 enrollment URL ## 快速开始 ### 环境前提 | 组件 | 要求 | |---|---| | **Python** | >= 3.9（推荐 3.12+，内置 `tomllib` 无需额外依赖；已确认兼容至 Python 3.14） | | **Git** | 任意较新版本 | | **Docker + Docker Compose** | Master 必需；Worker 容器模式必需。Docker Compose V2（`docker compose` 子命令） | | **操作系统** | Linux / macOS / Windows（Master 仅支持 Linux + Docker；Worker 宿主机模式全平台支持） | > **注意：** Docker 仅 Master 和 Worker **容器执行模式**需要。 > 如果 Worker 使用**宿主机模式**（`host` execution mode）部署，则 Worker 机器**不需要安装 Docker**， > 命令会在宿主机上直接执行。 `deploy.py` 会自动为 Worker 宿主机模式创建 Python 虚拟环境 并安装依赖，无需 Docker。 ### 第一步：安装并配置 Master 将 Master 安装在 Worker 可以访问的机器上，通常是公网服务器或同一内网的机器。 ```bash git clone https://github.com/tappat225/CapOwn.git cd CapOwn python3 deploy.py install master ``` > 如果你在中国大陆或受限网络环境中，可使用中国镜像： > > ```bash > python3 deploy.py install master --mirror-cn > ``` 部署完成后，设置 Worker 和 Client 访问 Master 的 URL： ```bash capown-master config set public-url https://master.example.com ``` `~/.capown/bin` 会在可能的情况下自动加入 PATH。如果未能自动配置，安装程序会打印 手动添加的命令。 ### 第二步：创建用户 ```bash capown-master users add alice ``` Master 会为该用户分配一个固定的 `uid`。请记录下来，后续的用户管理命令（如重命名、 设置密码、修改角色）需要使用。 ### 第三步：创建 enrollment 链接 ```bash capown-master tokens create alice ``` 命令会打印一个短期有效的链接，例如： ```text https://master.example.com/api/enroll/cown_tmp_xxxxx ``` 请将该链接视为机密。如果 `public_url` 仍为占位符，CLI 会提示你设置真实 URL 并 重新创建链接。 ### 第四步：安装 Worker 在你希望 AI Agent 控制的机器上： ```bash git clone https://github.com/tappat225/CapOwn.git cd CapOwn python3 deploy.py install worker ``` 中国镜像支持： ```bash python3 deploy.py install worker --mirror-cn ``` ### 第五步：安装 Client 在 AI Agent 所在的机器上： ```bash git clone https://github.com/tappat225/CapOwn.git cd CapOwn python3 deploy.py install client ``` ### 第六步：将 CapOwn 添加到 AI Agent 将你的 AI Agent 指向 CapOwn 客户端 skill： ```text skills/capown-client/SKILL.md ``` 该 skill 会教会 Agent 如何使用 `capown` 命令发现 Worker、执行 Shell 命令以及 读写文件。 ### 第七步：开始使用 CapOwn ```bash capown workers capown info capown run "echo hello" ``` 以上就是完整的快速上手指南：Master、用户、enrollment 链接、Worker、Client、 Agent skill，一气呵成。 高级部署选项、TOML enrollment 文件、独立的 Worker/Client 凭据、宿主机/容器 执行模式、Nginx 配置、直接 API 调用和长任务管理，详见 [docs/user_guide.md](docs/user_guide.md) 和 [docs/deploy.md](docs/deploy.md)。 ### 卸载 通过 `deploy.py` 卸载各组件： ```bash python3 deploy.py uninstall worker python3 deploy.py uninstall master python3 deploy.py uninstall client ``` **常用参数：** | 参数 | 说明 | |---|---| | `--yes` | 跳过交互确认（适合脚本化） | | `--purge` | 同时删除配置和数据文件 | 默认情况下，配置文件和数据目录会保留（方便重装后继续使用）。 使用 `--purge` 会清除 token、数据库和本地状态。 Worker 的 workspace 目录（存放任务输出）默认不会被删除，`--purge` 时会单独询问。 ## 架构 ```text AI Agent / CLI | | HTTPS task dispatch v CapOwn Master | | SSE task events over outbound Worker connection v CapOwn Worker（宿主机驻留控制进程） | | 本地执行（宿主机后端）或 docker exec（容器后端） v 目标设备 workspace ``` ### 组件 | 组件 | 目录 | 职责 | |---|---|---| | Shared | `shared/` | 协议模型、认证工具、配置 schema | | Master | `master/` | Starlette 控制平面、注册表、路由器、SSE broker | | Worker | `worker/` | 轻量守护进程和执行器 | | Client | `client/` | CLI 与 Agent 使用指南 | | Docs | `docs/` | 部署和用户文档 | ## 文档 - [用户指南](docs/user_guide.md)：客户端配置、CLI 命令、直接 API 调用、 错误码和数据保留说明。 - [部署指南](docs/deploy.md)：Docker、宿主机 Worker、Nginx/SSE 代理配置和 故障排查。 - [CapOwn Agent Skill](skills/capown-client/SKILL.md)：AI Agent 使用 CapOwn 的建议。 ## 安全模型 CapOwn 是给你控制的机器使用的远程执行工具。 - Node 和 Client API 使用基于数据库的、按用户隔离的 bearer token。Token 以 SHA-256 哈希存储——明文 token 仅在创建时显示一次。 - 每个 Worker 归属于注册时所用 token 对应的用户。Client 调度强制检查归属： 用户的 Client token 只能操作该用户自己的 Worker。 - 容器执行后端使用 Docker namespace 边界进行任务隔离；Worker 控制进程 无论何种后端都运行在宿主机上。 - 宿主机执行后端在宿主机上直接运行命令，只应在可信机器上使用。 - Master 不持久化任务历史；任务状态查询转发至目标 Worker。 数据保留细节见 [docs/user_guide.md](docs/user_guide.md#data-retention)。 ## 贡献 欢迎贡献代码。发起 Pull Request 前，请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [CLA.md](CLA.md)。Pull Request 仅接受同意 CapOwn CLA 的贡献者提交。 ## License CapOwn 使用 open-core 授权模式。 | 范围 | 许可证 | |---|---| | `client/`、`worker/`、`shared/`、`docs/`、tests、部署工具、根目录项目文件 | Apache-2.0 | | `master/` | AGPL-3.0-only | | 商业 Master、托管服务、计费、租户管理、企业功能 | Proprietary | 详见 [LICENSE](LICENSE) 和 [LICENSES](LICENSES/) 目录。