CapOwn

Multi-host remote operation and AI Agent coordination

English | 简体中文

Documentation | Deployment | Issue Tracker | Contributing

CapOwn lets a local AI Agent use other machines as remote execution hands. Workers keep an outbound HTTPS/SSE connection to a Master, so machines behind NAT do not need public IPs or inbound ports. The transport runs over standard HTTPS port 443 using SSE instead of WebSocket, making it work reliably in restricted network environments.

One Agent. Many devices. No inbound ports. Minimal-trust relay.

CapOwn is not an AI Agent itself — it works with Claude Code, Codex, and other agent tools you already use, giving them cross-device remote execution capabilities.

Why CapOwn

Modern AI coding agents often know what to do, but the right machine is somewhere else: a Linux test box behind NAT, a workstation with a GPU, a NAS, or a desktop with local-only tools.

CapOwn focuses on solving this specific problem:

• Install a lightweight Worker on another machine
• Let a local Agent discover it
• Run file, shell, and system information tasks through a Master relay
• Get structured results and machine-readable errors back

Key Features

• 🚀 Outbound-only workers - Workers connect to Master over HTTPS + SSE
• 🌐 Network-friendly transport - Runs over standard HTTPS/443, does not rely on WebSocket
• 🤖 Agent-friendly actions - Shell, file read/write/list, and system info
• 📦 Compact capability vocabulary - shell.run, file.read, file.write, file.list, system.info
• ⚠️ Structured errors - Machine-readable codes: worker_offline, workspace_violation, timeout, output_too_large
• 🔒 Workspace controls - File and shell operations resolved against configured Worker workspace
• ⚡ Sync and async tasks - Short synchronous calls or dispatch longer tasks and poll status
• 🐳 Flexible execution - Container isolation (Docker) or trusted native host execution
• 👥 Multi-user Master - Per-user tokens, enforced node ownership
• 📝 Config-driven deployment - TOML files or temporary enrollment URLs

Quick Start

Prerequisites

Component	Requirement
Python	3.10+ to run deploy.py; runtime Python 3.12 is managed automatically via uv
Git	Any recent version
Docker + Docker Compose	Required for Master; required for Worker container mode. Docker Compose V2 (docker compose subcommand)
Operating System	Linux / macOS / Windows (Master requires Linux + Docker; Worker host mode supports all platforms)

No Python dependencies need to be installed before deployment. deploy.py installs uv, Python 3.12, virtual environments, and runtime dependencies automatically.

Note: Docker is only required for the Master and for Worker container execution mode. If the Worker is deployed in host mode (host execution mode), the Worker machine does not need Docker — commands run directly on the host.

deploy.py automatically creates a Python virtual environment and installs dependencies for Worker host-mode deployments, no Docker needed.

Step 1: Install and configure the Master

Install the Master on a machine reachable by your Workers, usually a public server or a machine on the same network.

git clone https://github.com/tappat225/CapOwn.git
cd CapOwn
python3 deploy.py install master --public-url https://master.example.com

For direct LAN use, pass the Master host IP and published port instead:

python3 deploy.py install master --public-url http://192.168.1.10:9210

If you are in mainland China or a restricted network, use China mirrors:

python3 deploy.py install master --public-url https://master.example.com --mirror-cn

For LAN + China mirrors:

python3 deploy.py install master --public-url http://192.168.1.10:9210 --mirror-cn

For internet-facing deployments, you can put the Master behind Nginx/TLS and use standard HTTPS port 443, then set --public-url https://master.example.com. See Configure Nginx.

If you did not pass --public-url during install, set the URL that Workers and Clients will use to reach the Master:

capown-master config set public-url https://master.example.com
capown-master config set public-url http://192.168.1.10:9210  # LAN example

For direct LAN access, make sure the Master host firewall allows inbound TCP 9210. The default Docker publish address is 0.0.0.0:9210.

~/.capown/bin is added to your PATH when possible. If not, the installer prints the command to add it.

Step 2: Create an enrollment bundle

capown-master tokens create alice

If alice does not exist yet, the command creates that user first. It then prints ready-to-run install commands:

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

Treat the enrollment URL and generated files as secrets. If public_url still looks like a placeholder, the CLI warns you to set the real URL and recreate the bundle.

Step 3: Install a Worker

On the machine you want your AI Agent to control:

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 installs use container execution mode by default. The default host workspace is ~/.capown/workspace, mounted into the execution container as /workspace. You can customize execution mode, workspace, timeouts, and other settings later; see the Worker configuration section in the user guide.

China mirror support:

python3 deploy.py install worker https://master.example.com/api/enroll/cown_tmp_xxxxx --mirror-cn

During the enrollment token's lifetime, you can register multiple Worker machines at once.

Step 4: Install the Client

On the machine where your AI Agent runs:

git clone https://github.com/tappat225/CapOwn.git
cd CapOwn
python3 deploy.py install client https://master.example.com/api/enroll/cown_tmp_xxxxx

Optional status check after the Client is installed:

capown workers
capown info <worker>
capown run <worker> "echo hello"

Step 5: Give the Skill to Your AI Agent

Paste this skill path into your AI Agent and ask it to add the skill to its skill list:

skills/capown-client/SKILL.md

The skill teaches the agent how to use the capown command to discover Workers, run shell commands, and read or write files.

That is the full five-step happy path: Master, enrollment bundle, Worker, Client, agent skill, done.

Advanced deployment options, TOML enrollment files, separate Worker/Client credentials, host/container execution modes, Nginx setup, direct API calls, and long-running tasks are documented in docs/user_guide.md and docs/deploy.md.

Uninstalling

See docs/deploy.md for uninstall instructions.

Architecture

CapOwn has four main components: a Master (central control plane), Worker (remote execution daemon), Client (CLI/SDK), and Shared protocol library. Workers connect outbound to the Master over HTTPS + SSE, so machines behind NAT need no inbound ports.

See docs/architecture.md for the full architecture and directory layout.

Documentation

• User guide: client config, CLI commands, direct API calls, error codes, and data retention.
• Deployment guide: Docker, host mode Worker deployment, Nginx/SSE proxy notes, and troubleshooting.
• CapOwn Agent Skill: guidance for AI Agents using CapOwn.

Security Model

CapOwn uses bearer token authentication (SHA-256 hashed, per-user) with ownership-enforced dispatch. Workers connect outbound-only; the Master does not persist task history. See docs/user_guide.md for details.

Contributing

Contributions are welcome. Before opening a pull request, read CONTRIBUTING.md and CLA.md. Pull requests are accepted only from contributors who agree to the CapOwn CLA.

License

CapOwn uses an open-core licensing model.

Scope	License
client/, worker/, shared/, docs/, tests, deployment tooling, root project files	Apache-2.0
master/	AGPL-3.0-only
Commercial Master, hosted service, billing, tenant admin, enterprise features	Proprietary

See LICENSE and the files under LICENSES for details.