// 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.
| name | dev-capsem-doctor |
| description | 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. |
capsem-doctor is a pytest-based diagnostic suite that runs inside the guest VM. It verifies sandbox integrity, network isolation, runtime environment, and AI agent functionality. It's the smoke test gate -- every change must pass it before shipping.
just run "capsem-doctor" # Full suite (~10s total including VM boot)
just run "capsem-doctor -k sandbox" # Only sandbox tests
just run "capsem-doctor -k network" # Only network tests
just run "capsem-doctor -x" # Stop on first failure
just run "capsem-doctor -v" # Extra verbose
| File | What it validates |
|---|---|
test_sandbox.py | Read-only rootfs, binary permissions (chmod 555), no setuid/setgid, kernel hardening (no modules, no debugfs, no IPv6, no swap, no kallsyms), process integrity (pty-agent, dnsmasq running; no systemd, sshd, cron), network isolation (dummy0, fake DNS, iptables, no real NICs) |
test_network.py | MITM CA in system store + certifi, curl without -k works, Python urllib HTTPS, CA env vars set (SSL_CERT_FILE, REQUESTS_CA_BUNDLE, NODE_EXTRA_CA_CERTS), HTTP/80 blocked, non-443 ports blocked, direct IP blocked, multi-domain DNS faking, AI provider domains reachable |
test_environment.py | TERM/HOME/PATH env vars correct, shell is bash, kernel version, aarch64 arch, mount points (/proc, /sys, /dev, /dev/pts), tmpfs verification |
test_runtimes.py | Python3, Node.js, npm, pip3, git version checks; Python file I/O; Node file I/O; git init+commit workflow |
test_utilities.py | ~36 unix utilities available (coreutils, text processing, network, system tools, capsem-bench) |
test_workflows.py | Text write/read, JSON roundtrip (Python + Node), shell pipes, large file (10MB) |
test_ai_cli.py | claude, gemini, codex installed and executable without crashing |
test_virtiofs.py | VirtioFS root mount, ext4 loopback upper, loop device active, workspace write/read/large file/subdir, system overlay writable, pip install works, file delete+recreate (skipped in block mode) |
test_mcp.py | Guest MCP endpoint tool routing, domain blocking via MCP |
test_injection.py | Security injection tests |
conftest.py | Test infrastructure (auto-skip outside VM, run() helper, output dir fixture) |
# Auto-skip if not in capsem VM (checks root + writable /root)
def pytest_ignore_collect(collection_path, config):
if os.geteuid() != 0 or not os.access("/root", os.W_OK):
return True
# Shell command runner
def run(cmd, timeout=10):
return subprocess.run(cmd, shell=True, capture_output=True, text=True, timeout=timeout)
# Shared output directory: /root/tests
@pytest.fixture
def output_dir():
return TESTS_OUTPUT_DIR
guest/artifacts/diagnostics/test_*.py file, or create test_<category>.pyfrom conftest import run for shell commands, output_dir fixture for temp filesjust run "capsem-doctor" picks up changes immediately (diagnostics repacked into initrd)just build-assets then just run "capsem-doctor"guest/artifacts/diagnostics/test_*.py (in the repo)/usr/local/lib/capsem-tests/test_*.py (baked by Dockerfile.rootfs)_pack-initrd (fast iteration)test_readonly_rootfs, test_ca_in_certifirun() for shell commands, check .returncode and .stdout/.stderrpytest.mark.skipifCapsem 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).
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.
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.