Capsem Architecture

System overview

Capsem sandboxes AI agents in air-gapped Linux VMs on macOS using Apple's Virtualization.framework (with a KVM backend for Linux). It runs as a daemon service (like Docker). The system has these layers:

Host-side:

• capsem-service (daemon): always-running background service. Axum HTTP server over Unix Domain Socket (~/.capsem/run/service.sock). Manages VM lifecycle, routes API calls to per-VM processes. It is the only client of a VM owner: container setup (service-owned OCI pull and staging), exposures (/vms/{id}/exposures, admitted by the owner as network.lifecycle events), and the capsem.stream.v3 WebSocket at /vms/{id}/stream (terminal, streaming exec, container attach) all translate to typed owner IPC here; CLI, TUI, web and SDKs never dial a per-VM socket.
• capsem-process (per-VM): one process per sandbox. Boots the VM, bridges vsock connections (terminal + control), manages structured jobs (exec, file I/O) via a job store.
• capsem (CLI): user-facing CLI. Sessions are named by the service (vm-N unless the user supplies a name) and sized by create flags with fixed defaults. capsem shell opens the TUI/session picker, creates or attaches through the authenticated gateway, using the Rust SDK and shared API types. Direct UDS HTTP is restricted to local status/asset administration and service startup. Failed gateway authentication never falls back to UDS. User-facing copy says sessions; implementation/debug output may say VM when describing the virtualization layer.
• @capsem/mcp (npm MCP server): separately installed stdio server for AI agents. Uses the TypeScript SDK and an explicit gateway URL/token; it has no UDS, VM-runtime, or virtualization access.
• capsem-gateway (HTTP gateway): TCP-to-UDS reverse proxy (default port 19222). Bearer token auth, CORS, 10MB body limit. Provides an explicit route table plus /status (cached 1s) and /vms/{id}/stream (authenticated capsem.stream.v3 WebSocket upgrade tunneled unchanged to the service, which translates it to typed VM-owner IPC). Unknown routes return 404; the frontend and tray app connect through the gateway. Writes runtime files to ~/.capsem/run/ (gateway.token, gateway.port, gateway.pid).
• capsem-app (Tauri GUI): thin webview shell. Connects to gateway at http://127.0.0.1:19222. No VM logic, no capsem-core dependency. The registered shell commands live in crates/capsem-app/src/lib.rs: frontend logging, log-path diagnostics and opening external URLs. Update checks use the service API. Bundles web/app/dist so the app can render the service-unavailable screen when gateway is unreachable.
• capsem-tray (system tray): menu-bar companion process. Polls the gateway for VM status, shows running/stopped counts, and provides quick actions (open dashboard, quit). Non-standalone: refuses to run without --parent-pid pointing at a live capsem-service, acquires a system-wide singleton lock at ~/.capsem/run/tray.lock (only one tray ever in the menu bar), and self-exits within 500ms when its parent dies. Contract enforced by capsem-guard on the companion side, not the spawner.
• capsem-guard (shared library): parent-watch + singleton primitives used by capsem-tray and capsem-gateway. Provides watch_parent_or_exit, Singleton::try_acquire, and the umbrella install(parent_pid, lock_path). Guarantees companions die with their parent and can't run standalone or as multiple instances -- closes the orphan-accumulation class of bug that kill_on_drop(true) alone cannot cover under SIGKILL/OOM/test-harness termination. See /dev-rust-patterns lesson 18.

Guest-side:

• capsem-init (capsem-init): PID 1, sets up air-gapped networking, mounts filesystems, deploys guest binaries, launches daemons, writes boot timing JSONL
• capsem-pty-agent (capsem-pty-agent): main guest agent -- PTY bridge, control channel, exec, file I/O, shutdown handler (see "Guest agent architecture" below)
• capsem-tun (capsem-tun): guest end of a network cable. One tap per attached network, MAC capsem_proto::privatelink::mac_of(address), MTU 65521, pumping ethernet frames as u16-framed records over that cable's own vsock:5009 connection. The VM owner holds each cable's stream and hands a duplicate to that network's switch on plug(). A wire, not a stack: it parses nothing, and every protocol crosses it.
• capsem-sysutil (capsem-sysutil): guest suspend helper. Opens its own vsock:5004 connection independently of the agent, so suspend works even if the agent is hung. Symlinked by capsem-init only to /usr/local/bin/suspend; in-VM shutdown commands are disabled.
• capsem-net-proxy (capsem-net-proxy): redirects HTTPS traffic to host MITM proxy via vsock
• capsem-mcp-server (capsem-mcp-server): guest MCP stdio-to-framed-vsock relay for tool calls to the host MITM MCP endpoint

Reference routing

• Read references/service-and-guest-protocols.md before changing the service/process topology, CLI or MCP execution paths, gateway/service routes, host IPC, vsock framing or ports, or any guest agent binary.
• Read references/storage-network-and-lifecycle.md before changing VM storage or forks, network interception, security or logger ownership, ephemeral sessions, installation, service registration, companion launch, or updates.
• Read references/crate-and-privilege-model.md before moving responsibilities between crates, changing capsem-process permissions or environment, changing session/socket/share boundaries, or changing MITM CA-key handling.
• Read references/key-files.md before locating the implementation owner for an architectural change; it is the full annotated source map.
• Read references/tauri-v2.md before changing capsem-app or its Tauri v2 configuration and IPC. The app remains a thin webview shell; VM operations and update checks route through the gateway.

Core invariants

• All VM operations route through capsem-service to one capsem-process per session. No other host binary boots a VM or talks to guest vsock directly.
• The service and gateway expose an explicit route table. Unknown routes return 404; do not add compatibility aliases or generic forwarding. Every public method/path pair is approval-locked in config/public-surface.toml.
• Terminal bytes, control messages, lifecycle requests, and exec output use distinct vsock responsibilities. Preserve the port and framing contract in references/service-and-guest-protocols.md.
• The guest is air-gapped: it has no real NIC, DNS, or direct internet. HTTPS reaches the host only through the guest net proxy and the MITM/security path.
• VMs start unplugged. A private network is one confined L2 switch process (capsem-router --network); plug()/unplug() connect a VM's cable to it. Plugged VMs talk over any protocol. The switch forwards on MAC only and is a network, not a security boundary: never add per-flow relays, admission, or IP/TCP parsing to it. See references/storage-network-and-lifecycle.md.
• Corp config owns enterprise constraints and wins; the user's settings.toml and built-in defaults supply the rest of the policy; the one VM runtime and OCI images own what a guest runs; settings own UI preferences. All enforcement and detection compiles into one SecurityRuleSet over SecurityEvent.
• Credential capture/injection belongs to the credential broker. Durable ledger storage belongs to capsem-logger; routes, MCP helpers, UI handlers, benchmarks, and network formatters must not open SQLite or own projection caches. Missing tables or columns are schema failures, never empty data.
• Workspace and overlay bytes are session state, never a hidden image-authoring rail; package changes go through the runtime package set (/build-images) or an OCI image under images/.
• capsem-process clears its inherited environment, uses 0600 sockets and a 0700 session directory, attaches read-only assets and guest binaries, and shares only session_dir/guest/ with the VM. These controls do not confine a compromised same-UID host worker by themselves. The VM owner, proxy, ledger and native MCP workers enforce OS confinement before readiness. The service retains native MCP child handles and generation-bound cleanup authority.
• capsem-app contains no VM logic or capsem-core dependency. Gateway and tray are service-owned companions and must self-exit with their parent.

Key source files

Read references/key-files.md for the full annotated source map.

Tauri v2 reference

Read references/tauri-v2.md for Tauri v2 patterns and the registered handler in crates/capsem-app/src/lib.rs for shell commands. All VM operations and update checks route through the gateway.