Getting Started¶

Install Master and a Worker, obtain a client token, then connect an AI agent via MCP or the CLI/skill. Advanced topics (Docker rebuilds, host-mode Worker, Nginx, troubleshooting) are in the Deployment Guide.

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

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

Step 1: Install and configure the Master¶

Install the Master on a machine reachable by both Workers and Clients (a public server or the same LAN). Provide a suitable <server-address>.

Public deployment tip: Pair the Master with an Nginx/TLS reverse proxy on standard port 443. See Configure Nginx. Set <server-address> to your reverse proxy address, e.g. https://master.example.com.

LAN tip: Use the Master host's LAN IP plus port, e.g. http://192.168.1.10:9210. Allow inbound TCP 9210 (Docker listens on 0.0.0.0:9210 by default).

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

# Windows PowerShell
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/tappat225/CapOwn/master/scripts/install.ps1))) -Component master -DeployArgs "--public-url <server-address>"

Or install by cloning the repository manually

git clone https://github.com/tappat225/CapOwn.git
cd CapOwn
python3 deploy.py install master --public-url <server-address>

Mainland China / restricted network

python3 deploy.py install master --public-url <server-address> --mirror-cn

To update the address after installation:

capown-master config set public-url <server-address>

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

Starter user created automatically¶

On a fresh installation, the starter user chiral and a bundle enrollment token are created automatically. Generated Worker and Client install commands appear in the deploy output. The Client install command is only needed for the CLI/skill path. MCP users can redeem the same enrollment URL for a client token without installing CapOwn Client.

To create enrollment bundles for additional users:

capown-master tokens create alice

If user alice does not exist yet, the command creates that user first, 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. Multiple devices can be registered during the token's lifetime. By default, bundle tokens expire after 24 hours; use --ttl <seconds> to override.

Step 2: Install a Worker¶

On the machine you want your AI agent to control remotely:

Pass the enrollment URL from the Master for one-step registration.
Pass --workspace /srv/my-project to set a custom sandbox workspace path.

# 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"

Or install by cloning the repository manually

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

Default execution mode is container. On the Worker host the default workspace is ~/.capown/workspace, mounted into the container as /workspace. Bundle enrollment TOML matches that default (container mode with a home-relative workspace preset).

Execution mode, workspace path, timeouts, and other settings can be changed after installation. See Worker configuration.

Step 3: Obtain Client credentials¶

Master MCP and REST APIs authenticate with an issued client token. You must obtain this token, but you do not need to install CapOwn Client when using MCP. CapOwn does not register client devices. When the enrollment URL is redeemed, the Master consumes its temporary client slot and issues a revocable client token (no automatic expiry—store and rotate it like a secret).

Option A: Use MCP directly without installing Client¶

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

The Master returns TOML containing master_url and client_token. Configure that token in your MCP host. You do not need deploy.py install client or the capown CLI.

The client slot in an enrollment URL can normally be redeemed only once. The response contains a plaintext bearer token; store it as a secret.

Option B: Install the CLI/skill Client¶

Install Client only when you want the capown CLI or Agent skill:

# 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"

Or install by cloning the repository manually

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

Verify connectivity:

capown workers                    # list available Workers
capown info <worker>              # view Worker details
capown run <worker> "echo hello"  # execute a remote command

Step 4: Connect your AI agent¶

MCP¶

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

See the MCP Guide for configuration, authentication, Origin policy, and reverse-proxy notes (full Nginx setup is in Deployment).

This path does not depend on a local CapOwn Client installation.

CLI / skill (no MCP host)¶

Send this skill URL to your AI agent:

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

Or, in a local clone, point the agent at skills/capown-client/SKILL.md.

Four steps: Master (with enrollment) -> Worker -> client token -> MCP (no Client install) or CLI/skill.

Advanced options (TOML enrollment, host/container mode, Nginx, API usage, long-running tasks): User Guide and Deployment Guide.

Uninstall¶

python3 deploy.py uninstall worker          # remove service and runtime, keep config
python3 deploy.py uninstall worker --purge  # also delete config and data
python3 deploy.py uninstall client
python3 deploy.py uninstall master --purge

Add -y to skip confirmation. See the Deployment Guide for details.

FAQ¶

The enrollment token URL was leaked — what should I do?¶

If an enrollment URL that is reachable from the public internet was obtained by an unintended party, immediately regenerate the bundle token on the Master:

capown-master tokens create <username>

The old token is automatically revoked (only one active bundle token per user at a time). Also:

Check connected Workers: capown-master health lists currently online Workers. Verify no unexpected devices registered with the leaked token.
Disconnect suspicious Workers at the Master or other management layer.
Rotate credentials if the leaked token was already used to register Workers or Clients.

The default bundle token TTL is 24 hours (configurable via --ttl), which limits the exposure window.

Don't have a public server?¶

If Master and Workers are on the same LAN, use LAN IP addresses — no public server is required.

For cross-network scenarios without a public server, set up a virtual network with tools such as Tailscale or ZeroTier, then run the Master on one of those devices.