dev-capsem

# 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-archive` | Append-only, block-compressed body archive for one session ledger. | `format.rs`, `writer.rs`, `reader.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, no local discovery. | `transport.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` | CLI client. HTTP over UDS to service. | `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` | Profile, asset, and release validation/materialization 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-aggregator` | Low-privilege subprocess. Connects to external MCP servers and routes tool calls. Communicates with `capsem-process` via length-prefixed msgpack on stdio. No VM / DB / FS access. | `main.rs` (frame loop, server manager) | | `capsem-mcp-builtin` | Stdio MCP server subprocess exposing built-in tools: HTTP (fetch, grep, headers) and the `echo` transport probe. Managed by the aggregator. | `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`). 2 IPC commands: `open_url`, `check_for_app_update`. Bundles `web/app/dist` so it can render the service-unavailable screen. Crate name matches directory; binary is `capsem-app`. | `main.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/` | Profile, corp, settings source config and profile payloads | `/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` | profile-derived image builds, 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 (HTTP/UDS) -> 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 -- enterprise constraints, reporting endpoints, and locked rule/plugin policy 2. Profile config -- VM assets, rules, detections, MCP, plugins, packaged root, and profile defaults 3. Settings config -- UI/app preferences only There is no `user.toml` policy rail. A VM boots a profile; profile/corp own security behavior. Settings are not policy. Config naming is strict: - `schema` validates one contract shape. - `catalog` lists profile instances discovered or materialized from profile source. - UI metadata renders settings only. - `admin`, `guest`, and `registry` are not config authority roots. - The only top-level config directories are `settings/`, `corp/`, `profiles/`, `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. - **Sessions run profiles.** A session is created from a profile. The profile selects assets, packaged root files, MCP config, plugins, rules, detections, and UI-facing name/description/icon. Session status must reflect profile readiness and compatibility. - 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 base profile asset set and must remain compatible with the profile contract. - **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 profile-selected 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.