Dev Capsem

---
name: dev-capsem
description: Capsem project overview and navigation: what it is, how the crates fit, which skill owns what. Start here when orienting on any task.
---

# Capsem

Capsem sandboxes AI agents in air-gapped Linux VMs on macOS using Apple's Virtualization.framework (with KVM for Linux). Runs as a daemon service (like Docker). Built with Rust and Astro.

## Engineering standard

Quality, security and performance are P0 and every coding agent's
responsibility. See something, say something, do something.
When you notice a defect or an improvement while working -- a bug, a fragile
path, a lint or guard failure, a small refactor that clarifies, a way to make
something faster or more reliable, a vulnerable dependency -- do not walk past
it as "not my problem." Small: fix it test-first (`/dev-testing`) and commit
it in its own scoped commit. Too big to fold in: open a GitHub bug with enough
detail to act on. A vulnerability is fixed immediately, test-first, in its own
`security:` commit -- never parked, never filed publicly while unfixed. Stop
to ask only for genuine judgment calls (user-visible behavior, weakening a
security boundary, real scope, or a maintainer's dependency choice), and even
then lead with a recommendation. The full contract is
`AGENTS.md` -> "Fix what you find".

## Crate map

| Crate | What | Key modules |
|-------|------|-------------|
| `capsem-foundation` | Dependency-light host primitives shared across product crates. | `paths.rs`, `uds.rs`, `poll.rs`, `telemetry.rs`, `log_layer.rs`, `ipc_handshake.rs` |
| `capsem-cache` | Bounded observable cache mechanics; callers own freshness policy. | `bounded.rs`, `snapshot.rs`, `telemetry.rs` |
| `capsem-archive` | Append-only, block-compressed body archive for one session ledger. | `format.rs`, `writer.rs`, `reader.rs` |
| `capsem-crypto` | Accelerated hashes, integrity verification, randomness, TLS keys, JWT verification, signatures, and secret handling. | `verify.rs`, `random.rs`, `tls.rs`, `jwt.rs`, `secrets.rs` |
| `capsem-ledger` | Confined session-ledger worker and archive codec executor. | `main.rs`, `codec.rs` |
| `capsem-telemetry` | Single owner of every `metrics`-facade metric name, kind, unit, and description. Emitters import names from here. | `lib.rs` (`MetricSpec`, `describe_all`), `db.rs`, `dns.rs`, `mitm.rs`, `security.rs`, `virtio_blk.rs` |
| `capsem-assets` | VM asset lifecycle and manifest compatibility. | `asset_manager.rs`, `manifest_compat.rs` |
| `capsem-api` | Gateway wire types and OpenAPI contract. | `document.rs`, `hypervisor.rs`, `vm_info.rs` |
| `capsem-sdk` (`sdk/rust`) | Async HTTP gateway clients, shared API DTOs, and bounded local gateway discovery. | `transport.rs`, `hypervisor.rs`, `local.rs` |
| `capsem-config` | Product config contracts, parsing, validation, and provider/MCP identity. | `types.rs`, `validation.rs`, `provider_profile.rs`, `mcp.rs`, `resolver.rs` |
| `capsem-credentials` | Credential provider contracts and durable credential storage. | `provider.rs`, `store.rs`, `durable.rs` |
| `capsem-core` | VM, hypervisor, security-engine, network-intercept, and session-runtime domain library. | `vm/`, `net/`, `security_engine/`, `mcp/`, `hypervisor/`, `image.rs` |
| `capsem-service` | Daemon service. Axum HTTP over UDS, VM lifecycle. | `main.rs` (routes, IPC), `api.rs` (request/response types) |
| `capsem-process` | Per-VM process. Boots VM, bridges vsock, job store. | `main.rs` (vsock setup, IPC handler) |
| `capsem-proxy` | Confined HTTP/DNS proxy worker for VM and standalone traffic. | `main.rs` |
| `capsem` | CLI client. Rust SDK over authenticated gateway HTTP; local status/asset administration and startup use UDS. | `main.rs` (create, resume, shell, list, exec, run, stop, delete, persist, purge, info, logs, restart, version, doctor, fork, image) |
| `capsem-tui` | Terminal control UI over the gateway API. | `main.rs`, view/state modules |
| `capsem-admin` | Runtime image build, asset, release, and config validation administration. | `main.rs` |
| `@capsem/mcp` (`mcp/typescript`) | Separately installed host MCP server for AI agents. Stdio, typed SDK, authenticated gateway HTTP. | `cli.ts`, `server.ts`, tool modules |
| `capsem-router` | Confined TCP publication companion. Relays declared listeners to granted VSOCK data descriptors; no VM control authority. | `lib.rs`, `main.rs` |
| `capsem-network` | Private networks between VMs: the u16-framed ethernet frame codec for a cable and the switch's MAC forwarding table. Pure code; the I/O lives in `capsem-router --network`, one L2 switch per network that VMs `plug()` into. | `frames.rs`, `switch.rs` |
| `capsem-mcp-transport` | Connected HTTP capabilities and native role bootstrap; no VM, policy or secret ownership. | `http_transport.rs`, `native_worker.rs` |
| `capsem-mcp-aggregator` | Low-privilege subprocess. Connects to external MCP servers and routes tool calls. Service supervises it; the VM owner receives connected asynchronous MessagePack RPC. No ambient VM / DB / FS / network access. | `runtime.rs`, `server_manager.rs` |
| `capsem-mcp-builtin` | Stdio MCP server subprocess exposing built-in tools: HTTP (fetch, grep, headers) and the `echo` transport probe. Service-owned through the aggregator's narrow peer capability. | `main.rs` (rmcp handler) |
| `capsem-gateway` | TCP-to-UDS HTTP gateway. Frontend + tray connect through this. | `main.rs` (Axum router), `proxy.rs`, `status.rs`, `terminal.rs`, `auth.rs` |
| `capsem-app` | Thin Tauri webview shell. Points at gateway (`http://127.0.0.1:19222`). Shell commands are registered in `src/lib.rs` (frontend logging, log-path diagnostics and external URL opening); update checks use the service API. Bundles `web/app/dist` so it can render the service-unavailable screen. Crate name matches directory; binary is `capsem-app`. | `lib.rs` |
| `capsem-tray` | System tray. Polls gateway for VM status, quick actions (open dashboard, quit). | `main.rs`, `menu.rs` |
| `capsem-agent` | Guest binaries. Cross-compiled for aarch64/x86_64-linux-musl. | `main.rs` (PTY agent + file I/O), `net_proxy.rs` (TCP relay), `mcp_server.rs` (MCP relay), `sysutil.rs` (guest suspend helper; in-VM shutdown disabled) |
| `capsem-logger` | Session DB schema, queries, async writer. | `schema.rs`, `writer.rs`, `events.rs` |
| `capsem-proto` | Shared protocol types. | `ipc.rs` (ServiceToProcess/ProcessToService), `lib.rs` (HostToGuest/GuestToHost) |
| `capsem-guard` | Companion-process lifecycle primitives: parent-watch + singleton flock. Used by gateway and tray to refuse-standalone, enforce one-instance, and self-exit when the service dies (incl. SIGKILL). | `src/lib.rs` (`install`, `Singleton`, `watch_parent_or_exit`) |
| `capsem-bench` | Host/guest benchmark harness and result collection. | `main.rs`, collectors and dimensions |
| `capsem-mock-server` | Hermetic HTTP/TLS/WebSocket upstream for tests and benchmarks. | `main.rs` |

Rule: reusable logic belongs in the lowest-dependency crate that owns its
domain. Cross-process wire contracts belong in `capsem-proto`; host plumbing in
`capsem-foundation`; assets, config, and credentials in their named crates; VM,
hypervisor, security-engine, and host network runtime in `capsem-core`.

## Directory map

| Path | What | Skill |
|------|------|-------|
| `crates/` | Rust workspace | `/site-architecture` |
| `web/app/` | Astro 7 + Svelte 5 + Tailwind v4 + owned semantic CSS | `/frontend-design` |
| `web/marketing/` | Marketing website (Astro + Svelte 5) | `/site-marketing` |
| `web/docs/` | Documentation site (Astro Starlight) | `/site-infra` |
| `build_system/builder/` | Python builder and gate package | `/build-images`, `/dev-gate` |
| `build_system/scripts/` | Thin functional command boundaries | `/dev-gate`, `/release-process` |
| `guest/artifacts/` | capsem-init, bashrc, diagnostics | `/dev-capsem-doctor`, `/build-initrd` |
| `cache/target/assets/` | Built VM assets (gitignored, per-arch) | `/build-images` |
| `web/graphics/` | Brand icons and app icons (source of truth) | `/dev-capsem` |
| `skills/` | AI agent skills | `/dev-skills`, `/meta-organize-skills` |
| `config/` | Runtime image source (`docker/image`), corp, and settings config | `/site-architecture`, `/build-images` |

## Skill map

When working on a specific area, consult the relevant skill:

### Development
| Skill | When |
|-------|------|
| `/dev-just` | Which just recipe to run |
| `/dev-testing` | Test policy, TDD, coverage |
| `/dev-debugging` | Bug investigation workflow |
| `/dev-rust-patterns` | Async, cross-compile, error handling |
| `/dev-capsem-doctor` | In-VM diagnostic suite |
| `/dev-installation` | Package install, service registration, self-update, install tests |
| `/dev-setup` | New developer onboarding |
| `/dev-skills` | Skills system internals |

### Subsystems
| Skill | When |
|-------|------|
| `/dev-mitm-proxy` | MITM proxy, SSE parsing, telemetry |
| `/dev-mcp` | Guest MCP endpoint, tool routing |
| `/dev-testing-hypervisor` | KVM, Apple VZ, VirtioFS |
| `/dev-testing-vm` | In-VM tests, session inspection, fixtures |
| `/dev-testing-frontend` | vitest, visual verification |

### Build & release
| Skill | When |
|-------|------|
| `/build-images` | VM runtime builds: kernel, rootfs, OBOM |
| `/build-initrd` | Guest binary repack, fast iteration |
| `/release-process` | Release, CI, signing, docs, changelog |

### Frontend & site
| Skill | When |
|-------|------|
| `/frontend-design` | Owned design system, semantic colors, Svelte 5 runes |
| `/site-architecture` | System architecture, service daemon, gateway, key files |
| `/site-infra` | Astro Starlight docs site |

## Communication paths

```
AI Agent    -> @capsem/mcp (stdio)     -> authenticated gateway HTTP -> capsem-service -> capsem-process -> vsock -> guest
User CLI    -> capsem (Rust SDK)       -> authenticated gateway HTTP -> capsem-service -> capsem-process -> vsock -> guest
Desktop UI  -> capsem-gateway (TCP)    -> HTTP/UDS -> capsem-service -> capsem-process -> vsock -> guest
Tray app    -> capsem-gateway (TCP)    -> HTTP/UDS -> capsem-service -> capsem-process -> vsock -> guest
Guest HTTPS -> iptables -> vsock:5002  -> Host MITM proxy -> upstream
Guest MCP   -> framed vsock:5002      -> MITM MCP endpoint -> external MCP servers
```

Vsock ports: 5000 (control), 5001 (terminal), 5002 (MITM + framed guest MCP), 5004 (lifecycle/capsem-sysutil), 5005 (exec output).

## Config hierarchy

1. Corp config (`corp.toml`) -- enterprise constraints, reporting endpoints,
   and locked rule/plugin policy. Corp wins.
2. User settings (`~/.capsem/settings.toml`) -- rules, detections, MCP,
   plugins, and UI/app preferences.
3. Built-in defaults compiled into the binary.

The service merges the three into one per-VM policy file,
`vm/active_policy.toml`, at every boot. There is no `user.toml` policy rail.

Config naming is strict:
- `schema` validates one contract shape.
- `catalog` lists discovered or materialized instances.
- UI metadata renders settings only.
- `admin`, `guest`, and `registry` are not config authority roots.
- The only top-level config directories are `settings/`, `corp/`,
  `docker/`, and `data/`. Adding another root is a contract change and needs
  a failing guard first.
- `capsem-admin` is a validator/materializer/builder, not an authoring wizard.
  It must not grow `init`, `new`, `add`, provider, registry, or backend
  workspace authoring commands.

## Key invariants

- Guest VM is air-gapped. No real NIC, no real DNS, no direct internet.
- Guest binaries are read-only (chmod 555). Rootfs mounted read-only.
- **Every session boots the one VM runtime.** Applications come from OCI
  images; policy comes from corp + settings + built-in defaults; size comes
  from create flags with fixed defaults.
- The binary must be codesigned with `com.apple.security.virtualization`.
- Domain libraries own reusable logic; binary crates keep entrypoints focused
  on parsing, wiring, lifecycle, and presentation. Do not move unrelated logic
  into `capsem-core` merely because more than one caller needs it.
- **Fork images are first-class objects.** `capsem fork <session> <image-name>`
  clones a session into a reusable template. Forked images depend on the
  runtime asset set and must remain compatible with it.
- **Public surfaces are approval-gated.** `config/public-surface.toml` is the
  exact allowlist for public Just recipes, Capsem CLI command paths, and
  service HTTP method/path pairs. `tests/test_public_surface_contract.py`
  fails on additions, removals, renames, or count drift. Never refresh that
  ledger mechanically; a surface change requires explicit product approval.

## Installation

Release packages are the primary install path. Native install validation is
owned by the platform-neutral glow-up contract: Linux exercises the package in
the systemd install rail; macOS installs the signed exact package in a clean
Tart guest and boots its payload through physical Apple VZ. There is no public
native-install or release-command fork.

**Install layout** (`~/.capsem/`):
- `bin/` -- capsem, capsem-service, capsem-process, capsem-mcp-aggregator, capsem-mcp-builtin, capsem-gateway, capsem-tray
- `@capsem/mcp` -- separately installed npm package; native installation does not install Node.js or download it
- `assets/` -- manifest.json and the runtime VM assets such as `vmlinuz`,
  `initrd.img`, and EROFS rootfs images
- `run/` -- service.sock, service.pid, gateway.token, gateway.port, gateway.pid, instances/

**Service registration**: LaunchAgent (macOS: `com.capsem.service`) / systemd user unit (Linux: `capsem.service`). Auto-restarts on crash. See `/dev-installation` for the full wizard flow.