// Capsem project overview and navigation. Use when you need to understand what Capsem is, how the codebase is organized, which crate does what, or which skill to consult for a specific area. This is the map of the project -- start here when orienting on any task.
| name | dev-capsem |
| description | Capsem project overview and navigation. Use when you need to understand what Capsem is, how the codebase is organized, which crate does what, or which skill to consult for a specific area. This is the map of the project -- start here when orienting on any task. |
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.
| Crate | What | Key modules |
|---|---|---|
capsem-core | Shared library. All business logic lives here. | vm/ (machine, config, vsock, serial), net/ (MITM proxy, policy, CA, SSE), mcp/ (gateway, tools, policy), hypervisor/ (Apple VZ, KVM), image.rs (ImageRegistry, fork/clone) |
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-mcp | MCP server for AI agents. Stdio, bridges to service. | main.rs (rmcp handler, UDS client) |
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 file/snapshot (when CAPSEM_SESSION_DIR is set). 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. Bundled frontend/dist as offline fallback. 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 (lifecycle multi-call: shutdown/halt/poweroff/reboot/suspend) |
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) |
Rule: if logic could be reused or tested without a specific crate, it belongs in capsem-core.
| Path | What | Skill |
|---|---|---|
crates/ | Rust workspace | /site-architecture |
frontend/ | Astro 5 + Svelte 5 + Tailwind v4 + Preline | /frontend-design |
site/ | Marketing website (Astro + Svelte 5) | /site-marketing |
docs/ | Documentation site (Astro Starlight) | /site-infra |
src/capsem/builder/ | Python image builder CLI | /build-images |
guest/config/ | Guest TOML configs | /build-images |
guest/artifacts/ | capsem-init, bashrc, diagnostics | /dev-capsem-doctor, /build-initrd |
assets/ | Built VM assets (gitignored, per-arch) | /build-images |
graphics/ | Brand icons and app icons (source of truth) | /dev-capsem |
skills/ | AI agent skills | /dev-skills, /meta-organize-skills |
config/ | defaults.toml, CA keypair | /site-architecture |
scripts/ | preflight, integration test, doctor session | /release-process |
When working on a specific area, consult the relevant skill:
| 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 | Setup wizard, service registration, self-update, install tests |
/dev-setup | New developer onboarding |
/dev-skills | Skills system internals |
| 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 |
| Skill | When |
|---|---|
/build-images | capsem-builder, guest config, rootfs |
/build-initrd | Guest binary repack, fast iteration |
/release-process | Release, CI, signing, docs, changelog |
| Skill | When |
|---|---|
/frontend-design | Design system, colors, Preline, Svelte 5 runes |
/site-architecture | System architecture, service daemon, gateway, key files |
/site-infra | Astro Starlight docs site |
AI Agent -> capsem-mcp (stdio) -> HTTP/UDS -> 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).
/etc/capsem/corp.toml) -- highest priority, MDM-distributed~/.capsem/user.toml) -- user overridesconfig/defaults.toml) -- compiled-in defaultscapsem create -n <name>) are persistent -- their workspace and rootfs overlay survive stops and can be resumed. capsem create is always detached; capsem shell is the interactive entry point (bare capsem shell = temp VM + auto-destroy).com.apple.security.virtualization.capsem-core owns all business logic. App crate and agent crate are thin shells.capsem fork <vm> <image-name> snapshots a VM into a reusable template. capsem create --image <name> boots from it. Images depend only on a base squashfs version (flat genealogy -- no image-to-image deps). Asset cleanup protects squashfs versions referenced by any image. Images live in ~/.capsem/images/.capsem setup is the primary install path. On first use, auto-runs non-interactively (detects credentials, installs service, downloads assets). Users can re-run capsem setup --force to reconfigure.
Install layout (~/.capsem/):
bin/ -- capsem, capsem-service, capsem-process, capsem-mcp, capsem-mcp-aggregator, capsem-mcp-builtin, capsem-gateway, capsem-trayassets/ -- manifest.json, v{VERSION}/{vmlinuz, initrd.img, rootfs.squashfs}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.
Capsem release process, CI pipeline, Apple code signing, notarization, documentation site, and post-release verification. Use when preparing a release, debugging CI failures, working with Apple certificates, updating the documentation site, or cutting a new version. Covers the full release lifecycle from pre-release checklist through post-release verification.
Capsem development toolchain -- all just recipes, what they do, when to use which, and dependency chains. Use when you need to know how to build, run, test, or ship Capsem, or when deciding which just command to run for a given change. This is the toolchain reference.
Capsem testing policy and workflow. Use whenever running tests, writing new tests, or verifying changes work. Covers the three test tiers (unit, smoke, full), TDD red-green-refactor, adversarial security testing, coverage policy, and the mandatory end-to-end VM validation. For VM-specific tests see dev-testing-vm, for hypervisor tests see dev-testing-hypervisor, for frontend tests see dev-testing-frontend.
Building Capsem VM images with capsem-builder. Use when working with guest image configuration, Dockerfiles, kernel builds, rootfs builds, the builder CLI, or guest config TOML files. Covers the config-driven build system, guest config layout, Dockerfile templates, multi-arch support, the builder CLI commands, AND the internal architecture for modifying the builder itself (models, context flow, template variables, adding install managers).
The capsem-doctor in-VM diagnostic suite. Use when writing, running, or extending capsem-doctor tests, adding new diagnostic categories, debugging VM sandbox issues, or understanding what capsem-doctor validates. Covers all 11 test categories, how to run subsets, the conftest infrastructure, and how to add new tests.
Debugging methodology for Capsem. Use when investigating bugs, test failures, unexpected behavior, or any issue that needs diagnosis. Enforces the correct workflow -- reproduce with a test first, diagnose the root cause, then offer a comprehensive fix. Never jump to fixing code without understanding why it broke.