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

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

Skill map

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

Development

Subsystems

Build & release

Frontend & 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.