Skip to content

CapOwn — Architecture

Overview

CapOwn is a distributed multi-host remote operation and AI Agent coordination system. A central Master exposes MCP Streamable HTTP and the existing REST API, then routes operations to multiple Worker nodes over HTTPS + SSE. Workers require no inbound ports.

Diagram

[MCP Host / CLI / API Client]
    | (MCP Streamable HTTP or REST)
    v
[Master (public IP) -- central router]
    ^ (HTTPS POST: report results)
    | (SSE long-poll: push task instructions)
    |
    +-- [Worker @ Node A]
    +-- [Worker @ Node B]
    +-- [Worker @ Node C]
    ...

Design Constraints

  • All-outbound connections: Workers only need outbound HTTPS. No inbound ports required.
  • Central routing hub: All inter-node communication routes through Master.
  • Capability/intelligence split: Workers provide execution; Agents provide LLM decisions.
  • Two northbound interfaces: MCP is the standard agent integration. The stdlib-only CLI and skill remain supported for restrictive networks and clients without MCP support.
  • Dual execution backends: Workers support container (Docker) and host (native) task execution. The Worker control process always runs on the host. In container mode, tasks execute inside a managed Docker container that bind-mounts a selected host directory as the workspace; host mode executes tasks directly on the host system.

Components

Component Role
Master MCP/REST gateway, node registry, SSE broker, task router, auth gateway
Worker Lightweight daemon that connects to Master, authenticates, reports runtime metadata, executes tasks, and reports results
Client Stdlib-only CLI for direct, scripted, and restrictive-network access
MCP host Agent host that discovers and calls CapOwn tools through /mcp

Worker Startup Sequence

  1. Load or generate Ed25519 keypair from ~/.capown/worker/identity.toml.
  2. Enroll (first run only): submit enrollment_token + public_key to POST /api/workers/register. The Master returns a worker_id which is persisted locally.
  3. Challenge-response auth: request a nonce, sign it with the private key, submit to POST /api/workers/auth/verify to obtain a session token.
  4. Report runtime metadata: call POST /api/workers/{worker_id}/reconnect with current hostname, OS, mode, capabilities, and workspace so the Master has up-to-date information after any restart.
  5. Open SSE connection to GET /api/events for task dispatch.
  6. On disconnect or session expiry, repeat from step 3 (or re-enroll if the worker has no identity). Metadata is reported again after each re-auth.

Directory Structure

CapOwn/
├── deploy.py            # Unified deployment script (menu-driven)
├── AGENTS.md            # Operating guide for AI coding assistants
├── shared/              # Protocol models, auth, config schemas, enrollment helpers
├── master/              # Starlette control plane: MCP/REST adapters, services, routing
├── worker/              # Daemon, executors, execution backends, tool registry, CLI
├── client/              # CLI tool (capown) and client config loader
├── deploylib/           # Deployment library: app copy, install, platform utils, services
├── skills/
│   └── capown-client/
│       └── SKILL.md     # AI Agent skill for CapOwn client
├── tests/               # Standalone test scripts (no pytest/unittest)
├── docs/                # Architecture, deployment, user guide, CLI contract, API reference
├── scripts/             # Design records (non-authoritative)
├── coding_prompt/       # Historical development records
├── README.md / README_en.md
├── CONTRIBUTING.md / CLA.md / TESTING.md
└── .gitignore