Site Architecture

---
name: site-architecture
description: Capsem system architecture: service, per-VM processes, CLI, guest agent, vsock, network proxy. Use when you need the design to write, review, or debug across components.
---

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