version: "1.0.0" name: dev-setup description: Setting up a Capsem development environment from scratch. Use when onboarding a new developer, setting up a new machine, or troubleshooting environment issues. Covers prerequisites, first-time setup, tool installation, VM asset builds, container runtime configuration (Colima/Docker memory and CPU requirements), and verification steps.

Developer Setup

Prerequisites

• macOS 13+ (Ventura or later) -- required for Virtualization.framework
• Apple Silicon (arm64) -- primary target. Intel Macs are not supported for VM features.
• Docker (via Colima on macOS) -- needed for just build-assets (kernel + rootfs builds)

Required tools

Run just doctor to check all of these:

Rust targets (auto-installed by just doctor-fix):

• aarch64-unknown-linux-musl -- guest binaries (arm64)
• x86_64-unknown-linux-musl -- guest binaries (x86_64)

Cargo tools (auto-installed by just doctor-fix):

• cargo-llvm-cov -- coverage
• cargo-audit -- vulnerability scanner
• cargo-tauri -- Tauri CLI
• b3sum -- BLAKE3 checksums

Container runtime setup

On macOS, Docker runs inside a Colima VM. The default memory allocation may be too small -- the rootfs build runs apt installs, npm installs, and curl-based CLI installers concurrently, which can OOM-kill the build (exit code 137).

Minimum: 12GB RAM. Recommended: 16GB RAM, 8 CPUs (Tauri's GTK/webkit2gtk dep chain pushes the install-test build past 8GB on cold caches; 12GB is the floor that doesn't OOM).

Colima (macOS)

# First-time setup
brew install colima docker
colima start --vm-type vz --vz-rosetta --memory 16 --cpu 8
 
# Restart with new resources
colima stop
colima start --vm-type vz --vz-rosetta --memory 16 --cpu 8
 
# Verify
docker info | grep -E 'Total Memory|CPUs'

Colima recovery discipline

If Docker-dependent recipes fail on macOS, do not report Docker/Colima as unavailable until you have checked for the common half-running Colima state. The signature is:

• colima list says the profile is Running
• docker version / docker info cannot connect to

~/.colima/default/docker.sock

• colima ssh -- docker ps fails with kex_exchange_identification,

Connection reset by peer, or colima status reports error retrieving current runtime: empty value

First recovery attempt:

colima stop
colima start
docker version

If the profile needs its expected resources restored, start with the explicit Capsem defaults instead:

colima stop
colima start --vm-type vz --vz-rosetta --memory 16 --cpu 8
docker version

Only after that restart fails should you treat Colima as a real environment blocker. Record the exact failed command and the Docker/Colima output.

Linux

Docker runs natively on Linux -- no Colima or memory tuning needed.

sudo apt install docker.io

just doctor checks these resources automatically and fails if below minimum.

First-time setup

# 1. Clone and enter
git clone <repo> && cd capsem
 
# 2. Bootstrap (interactive: prompts [Y/n] before each install; --yes for CI)
./bootstrap.sh
#   ./bootstrap.sh --yes    # non-interactive
 
# 3. Boot the VM to verify everything works
just run "echo hello from capsem"

bootstrap.sh lives at the repo root (not under scripts/). It runs just build-assets as part of doctor's auto-fix, so step 3 just confirms the VM boots.

What bootstrap installs

Three phases. Default at every prompt is Yes (Enter accepts; type n to decline). --yes and non-tty input both auto-accept.

Kernel version

guest/config/build.toml ships kernel_branch = "auto", which makes resolve_kernel_version pick the newest non-EOL longterm release from kernel.org/releases.json and fetch its latest patch (e.g. 6.18.26). Set kernel_branch = "X.Y" (e.g. "6.6") to pin for reproducibility.

Or step by step:

just doctor          # Check tools (colored output, structured recap)
just doctor-fix      # Auto-fix missing targets, cargo tools, config files
just build-assets    # Build kernel + rootfs (~10 min)
just run "echo hi"   # Verify VM boots

If step 4 prints "hello from capsem" and exits cleanly, you're set.

Daily workflow

just run              # Build + boot VM interactively (~10s)
just run "CMD"        # Build + boot + run command + exit
just test             # Unit tests + cross-compile + frontend check
just ui               # Frontend dev server (mock mode, no VM)
just dev              # Full Tauri app with hot-reload

See /dev-just for the complete recipe reference.

API keys (optional, needed for integration tests)

Create ~/.capsem/user.toml:

[providers.anthropic]
api_key = "sk-ant-..."
 
[providers.google]
api_key = "AIza..."

Needed for: just test (integration tests exercise real AI API calls), interactive AI sessions inside the VM.

Claude Code permissions

To avoid repeated permission prompts when using just and capsem commands, add these to your Claude Code settings. Run /update-config or edit .claude/settings.local.json:

{
  "permissions": {
    "allow": [
      "Bash(just *)",
      "Bash(uv run *)",
      "Bash(cargo *)",
      "Bash(pnpm *)",
      "Bash(cd frontend && pnpm *)",
      "Bash(npx *)",
      "Bash(python3 scripts/*)",
      "Bash(rustup *)"
    ]
  }
}

This allows:

• just * -- all recipes (run, test, build-assets, query-session, list-sessions, doctor, etc.)
• uv run * -- capsem-builder CLI and Python scripts
• cargo * -- Rust builds, tests, checks
• pnpm * -- frontend package management and builds
• npx * -- skills CLI and other npx tools
• python3 scripts/* -- project scripts (check_session, list_sessions, etc.)
• rustup * -- target/component management

Codesigning

The app binary must be codesigned with com.apple.security.virtualization entitlement or Virtualization.framework calls crash. The justfile handles this automatically via _sign recipe.

Prerequisites (macOS only):

• Xcode Command Line Tools: xcode-select --install
• entitlements.plist must exist in the repo root (checked into git)

Verification: just doctor includes a signing test that compiles a tiny binary, signs it with the entitlements, and verifies the operation succeeds. Run just doctor after initial setup to confirm signing works.

Linux developers: codesign is not available and not needed on Linux. VM features use the KVM backend when /dev/kvm and /dev/vhost-vsock are available. Use just benchmark for the same artifact-recording performance suite as macOS.

Troubleshooting

just run fails with codesign error

• Run just doctor -- it will diagnose the specific signing issue
• Ensure Xcode CLTools are installed: xcode-select --install
• Check entitlements file exists: cat entitlements.plist
• Try manual sign: codesign --sign - --entitlements entitlements.plist --force target/debug/capsem
• Check SIP status: csrutil status

just doctor fails

Run just doctor-fix to auto-fix all fixable issues. Fixes run in dependency order (rustup targets before cargo tools before build-assets before pack-initrd). Non-fixable issues show install hints.

just build-assets or just test-install fails with exit code 137 (or 143 mid-cargo-build)

The container runtime VM ran out of memory. Bump Colima to at least 12GB (16GB recommended):

• Colima: colima stop && colima start --vm-type vz --vz-rosetta --memory 16 --cpu 8
• Linux: Docker runs natively, no memory tuning needed

just build-assets fails with "Release file not valid yet"

The container VM's clock has drifted. The builder uses Acquire::Check-Valid-Until=false to work around this, but if you see this error on an old builder version:

• Colima: colima stop && colima start --vm-type vz --vz-rosetta --memory 16 --cpu 8 (resets clock)
• Docker Desktop: restart Docker Desktop

just build-assets fails (other)

• Check Docker is running: docker info
• Check guest config is valid: uv run capsem-builder validate guest/
• On first run, Docker image pulls can be slow

just run fails with "assets not found"

Run just build-assets first. Assets are gitignored and must be built locally.

cargo run or cargo test crashes with signing error

• .cargo/config.toml must exist and be tracked in git -- it configures the custom runner (scripts/run_signed.sh) that signs binaries with Virtualization.framework entitlements before execution
• If missing: git checkout .cargo/config.toml
• The justfile _sign recipe signs separately, so just run works even without the cargo runner -- but direct cargo run/cargo test and IDE integrations will crash
• Lesson: bare .gitignore patterns (no / prefix) match at any depth. Always anchor with / when you mean root-only (e.g., /config.toml not config.toml), or you risk silently ignoring files in subdirectories like .cargo/

Cross-compile errors

• Check .cargo/config.toml has linker config for musl targets
• Run rustup target add aarch64-unknown-linux-musl x86_64-unknown-linux-musl
• Platform-specific type issues: use as _ for libc calls (see /dev-rust-patterns)

Disk full / Colima eating all disk space

Docker builds accumulate images, build cache, and stopped containers inside the Colima VM. The VM uses a Virtualization.framework raw disk that only grows, never shrinks on its own -- even after docker system prune, macOS doesn't get the space back.

The _docker-gc recipe runs automatically after build-assets, cross-compile, and test-install to prevent this. It prunes containers, images >72h, build cache >72h, and runs fstrim to release freed blocks back to macOS. If disk is already full:

# One-time recovery
docker system prune -af --volumes           # free space inside VM
colima ssh -- sudo fstrim /mnt/lima-colima  # release it to macOS

To check current state: colima ssh -- docker system df (inside VM) and du -sh ~/.colima (host).

Docker credential helper error (docker-credential-osxkeychain not found)

When Colima is installed standalone (without Docker Desktop), ~/.docker/config.json may reference a credential helper that doesn't exist. The symptom is docker run failing to pull images with exec: "docker-credential-osxkeychain": executable file not found.

Fix: set credsStore to empty string in ~/.docker/config.json:

{ "credsStore": "" }

just doctor checks for this under "Container Runtime" and will flag the mismatch.

VM boot hangs

• Check codesigning: codesign -dvv target/debug/capsem 2>&1 | grep entitlements
• Check assets exist: ls assets/arm64/vmlinuz assets/arm64/rootfs.squashfs
• Check kernel architecture matches host: wrong-arch kernel causes silent hang. VmConfig::build() now rejects mismatched kernels at config time.
• Try with debug logs: RUST_LOG=capsem=debug just run

Doctor architecture

The doctor system is three bash scripts:

scripts/
  doctor-common.sh    # Entry point, cross-platform checks, fix registry, recap
  doctor-macos.sh     # macOS: Colima, Rosetta, codesigning, brew hints
  doctor-linux.sh     # Linux: KVM, apt/dnf hints

just doctor calls doctor-common.sh. just doctor-fix calls doctor-common.sh --fix.

Fix registry

All fixable issues use an ordered fix registry defined at the top of doctor-common.sh. Each entry has an ID, command, and description. Checks call fixable <id> <label> to mark a fix as needed. Fixes run in registry order (dependency order), deduped by design.

Registry order (each depends on the ones above it):

1. rustup-targets -- cross-compile targets
2. llvm-tools -- rust-lld linker
3. cargo-llvm-cov, cargo-audit, b3sum, cargo-tauri -- cargo tools
4. entitlements, cargo-config, run-signed -- git checkout config files
5. pnpm-install -- frontend deps
6. build-assets -- VM kernel + rootfs (needs docker)
7. pack-initrd -- guest binaries (needs assets)

Design rules

• Fixable checks use `fixable <id> <label>`, not raw fail(). This registers the fix in the ordered registry.
• Non-fixable checks use `fail()` with an install hint. System tools (node, docker, etc.) can't be auto-installed safely.
• Platform-specific checks live in `doctor-macos.sh` / `doctor-linux.sh`. Each defines check_platform() and tool_hint().
• Test, don't just check. The codesigning section compiles and signs a test binary. docker buildx version tests functionality, not just file existence.
• Recover Colima before declaring Docker dead. On macOS, a stale Colima VM

can leave the Docker socket present but unusable. Use the Colima recovery discipline above before filing or reporting a Docker/Colima blocker.

• Bootstrap calls doctor. bootstrap.sh checks bare minimums (bash, git, curl, rustup, just), installs Python/frontend deps, then runs doctor-common.sh --fix.