Repository navigation
Description
Plan
spec-minvmd-host-daemon
Source: gominimal/inbox#164 · parent #151 · proposal Minimal as a Session Manager · kernel dep gominimal/pkgs#154 · reference impl ~/code/min-ctl
Introduction/Overview
minvmd is the macOS-only host daemon that brings up a Linux microVM via libkrun, supervises its lifecycle, and bridges a host UDS to a vsock port inside the VM so the minimal CLI can talk to minimald transparently — exactly as it does natively on Linux. It is the third process in the Minimal One architecture (alongside minimal and minimald) and exists solely to absorb the VM boundary that macOS imposes.
The crate is reimplemented clean in the minimal workspace, drawing patterns and hard-won lessons from ~/code/min-ctl (FFI safety, lifecycle state machine, RAII recovery guards, error fidelity, no $HOME virtiofs, TSI connection-cap awareness) but not vendoring its code. Networking is explicitly deferred to #160.
Goals
- New
crates/minvmdbuilds green on macOS (aarch64 + x86_64), no-op shim on Linux, no CI regressions on the Linux-only workflow. minimalCLI on macOS opens a connection to in-VMminimaldover a host UDS without knowing a VM exists (transparent vsock bridge).- VM boots from a
virtio-linuxkernel + Alpine rootfs in under ~5s cold; warm reattach is sub-second. minvmdauto-spawns on first CLI call (Docker-Desktop model per all: clippy fix, update rustls-webpki #151) and survives client exit.minvmd status/minvmd stopwork; PID and socket discovery follow XDG conventions; concurrent CLI invocations don't race lifecycle.
User Stories
- As a Mac user, I want to run
minimal lson a fresh install so that I get[]end-to-end without manually starting a VM. - As a Mac user, I want my second
minimal lsto be instant so that the VM cold-start cost is amortized. - As a Mac user, I want to run
minvmd statusso that I can see VM state, vcpus, ram, and uptime. - As a Mac user, I want to run
minvmd stopso that the VM shuts down gracefully and the nextminimalcall cold-starts a fresh VM. - As a Linux user, I want
minvmdto not be installed at all so that my install path stays simple.
Demoable Units of Work
Requirement IDs use the format R{unit}.{seq} (R1.1, R1.2 for Unit 1; R2.1 for Unit 2). These IDs are referenced directly by the planner — do not renumber after approval.
Unit 1: Crate scaffold, FFI wrappers, libkrun smoke test
Purpose: Land the bones — crate, FFI bindings, build script, codesign step. Boot a libkrun context to the marker "VM started, exited cleanly" with no rootfs work.
Depends on: None
Affected areas: crates/minvmd/ (new), crates/minvmd/src/krun/ (new), crates/minvmd/minvmd.entitlements (new), crates/minvmd/build.rs (new), Cargo.toml (workspace), justfile
Functional Requirements:
- R1.1: The
minvmdcrate shall compile onaarch64-apple-darwinandx86_64-apple-darwinand shall compile to a no-op stub ontarget_os = "linux"so the existing Linux-only CI stays green. - R1.2: FFI bindings shall live in a single
src/krun/raw.rsmodule; everyunsafecall shall carry a// SAFETY:comment naming the libkrun preconditions (pointer lifetime, NUL-termination, range bounds, ownership transfer). - R1.3: Safe wrappers (
src/krun/ctx.rs) shall validate all inputs in safe Rust (range checks, NUL-termination, allocation lifetimes) before crossing the FFI boundary; FFI return codes shall be translated to a typedVmError::Backend { op: &'static str, source: std::io::Error }preserving the original errno, built viaio::Error::from_raw_os_error(ret.checked_neg().unwrap_or(libc::EOVERFLOW)). The return-code translation lives as a free function in thekrunFFI module, not as a method onVmError. - R1.4: Release builds shall be code-signed with
minvmd.entitlementsgrantingcom.apple.security.hypervisorand nothing else; ajustfiletarget shall reproduce the signing step locally. - R1.5: A smoke test
tests/krun_smoke.rs(gated onMINVMD_E2E=1, marked#[ignore]by default) shall create a libkrun context, configure 1 vcpu + 512 MiB, set/bin/trueas exec, and confirmkrun_start_enterexits cleanly.
Proof Artifacts:
- File:
crates/minvmd/src/krun/raw.rscontains FFI declarations for the libkrun functions used in this unit (krun_create_ctx,krun_set_vm_config,krun_set_exec,krun_start_enter,krun_free_ctx) with// SAFETY:comments demonstrates the FFI scaffold and safety discipline. - CLI:
MINVMD_E2E=1 cargo test -p minvmd --test krun_smoke -- --include-ignoredexits 0 on a Mac with libkrun installed demonstrates end-to-end FFI bring-up.
Unit 2: VM bring-up with virtio-linux kernel + Alpine rootfs
Purpose: Actual Linux boot. minvmd boot brings up an Alpine VM that reaches userspace and writes a "READY" marker to vsock from a guest-side init.
Depends on: Unit 1
Affected areas: crates/minvmd/src/image.rs (new), crates/minvmd/src/vm.rs (new), crates/minvmd/src/cmd/boot.rs (new), crates/minvmd/src/cmd/vmm_child.rs (new)
Functional Requirements:
- R2.1: The kernel artifact shall be the
vmlinuzoutput of thevirtio-linuxminimal package (pkgs#154); on aarch64 the artifact isImage.gz, on x86_64bzImage. Path resolution shall happen at runtime via aMINVMD_KERNEL_PATHenv var so the package-graph wiring can land in a follow-up without changing this spec. - R2.2: The rootfs shall be an Alpine minirootfs (version-pinned, sha256-verified). For v0.1 the path is supplied via
MINVMD_ROOTFS_PATH; staging is performed byscripts/fetch-alpine.sh(downloads upstream Alpine minirootfs, verifies sha256, extracts to~/.cache/minimal/minvmd/rootfs/). Migration to a siblingalpine-minirootfsminimal package is tracked as an open question. - R2.3:
minvmd boot(parent) shall configure the libkrun context via the safe wrappers, thenexec-spawn a hiddenminvmd __krun-vmmchild that callskrun_start_enter(the parent does not block onkrun_start_enterbecause that call never returns on success). The parent shall write avmm.pidfile and surface child-exit codes via signal handling. - R2.4: Boot shall complete to a guest-side marker (writes
READY\non a designated vsock port) within 5s on a warm laptop; the parent shall block on this marker before reporting boot success. - R2.5: No network device shall be added to the libkrun config in v0.1; gvproxy/TSI integration is owned by .github/workflows/ci.yml: check if
Cargo.lockis up-to-date #160. Default libkrun vsock is acceptable since v0.1 does not expose TCP to the guest.
Proof Artifacts:
- CLI:
MINVMD_KERNEL_PATH=/tmp/vmlinuz MINVMD_ROOTFS_PATH=/tmp/alpine-minirootfs minvmd boot --foregroundboots and printsvm-upto stdout within 5s, and a host-side reader on the vsock marker socket readsREADYdemonstrates kernel+rootfs come up. - Test:
tests/boot_e2e.rs(gatedMINVMD_E2E=1,#[ignore]) asserts the marker round-trip end-to-end.
Unit 3: UDS↔vsock bridge for ssh.sock
Purpose: The product feature — a host UDS the CLI talks to, bridged by libkrun to the in-VM vsock port where minimald listens. Bidirectional, transport-agnostic, multiple concurrent connections. minvmd does not relay bytes itself — libkrun owns the host UDS and the vsock forwarding.
Depends on: Unit 2
Affected areas: crates/minvmd/src/krun/raw.rs (add krun_add_vsock_port2), crates/minvmd/src/krun/ctx.rs (wrap it), crates/minvmd/src/vm.rs (register the vsock port before boot), crates/minvmd/src/sock.rs (host UDS path resolution, parent-dir + permissions), guest-side vsock→UDS shim (see R3.4)
Socket model (Option A — libkrun-owned, no host relay). Tom's minimald speaks SSH (russh) over a raw UnixListener stream and works over any bidirectional byte stream (its test harness drives it over an in-memory UnixStream pair). The provider socket therefore needs only a faithful, multiplexed bytestream — nothing protocol-aware. libkrun's krun_add_vsock_port2 delivers exactly that, so minvmd stays a thin lifecycle/transport daemon rather than a userspace byte relay (the rejected Option B). The provider-owns-socket and connect-and-prune discovery rules in docs/session-domain-diag.md hold under this model: the host UDS is the provider socket; a stale socket after a crash fails connect-and-check and is pruned by minimal.
Functional Requirements:
- R3.1: Before
krun_start_enter,minvmdshall register the host UDS viakrun_add_vsock_port2(ctx, VSOCK_PORT, HOST_UDS_PATH, listen = true). Per libkrun's header,listen = truemeans connections are initiated from the host side: libkrun listens on the host UDS and bridges each accepted connection to a guest process listening on vsockVSOCK_PORT. This matches the SSH direction — hostminimalis the client, in-VMminimaldis the server. (Thelisten = falsedefault is the guest-initiated direction and is wrong here.) - R3.2: The host UDS path shall be
$XDG_RUNTIME_DIR/minimal/minimald.sock(fallback~/.minimal/local/minimald.sock). Because libkrun binds the socket,minvmdshall create the parent directory (mode 0700) before boot, setumaskso the bound socket is owner-only (0600), and verify/chmodthe path to 0600 once it appears. - R3.3: libkrun shall multiplex multiple concurrent host connections, each bridged to an independent vsock connection to
VSOCK_PORT;minvmdcarries no per-connection state. The path is transport-agnostic — bytes in, bytes out, no SSH/russh parsing (russh subsystem dispatch lives inminimald, per crates/minimal: improve tasks list inminimal status, add task description field #156). - R3.4: v0.1 uses a vsock stub. The guest-side responder for bring-up is a small stub that listens on vsock
VSOCK_PORTdirectly and answers the health /list-sessionsping with an empty list — no shim, no realminimaldin the guest. This is sufficient to prove the full host→guest path (Units 1–3) and is the only guest-side component this spec implements. The realminimaldlistens on a UNIX socket, not vsock, so swapping it in later requires either a vsock→UDS shim or a vsock-nativeminimald; that decision is deferred (Open Questions Parallel builds #3) —minimaldis Tom's crate. - R3.5: On guest unavailability (VM crash,
minimaldexit, no guest listener), a host connect/exchange shall fail at the libkrun bridge;minvmdshalltracing::warn!where observable, andminimal's provider discovery shall treat the failed connect as "stale provider — prune and continue", not a hard error. The TSI loopback ~62-concurrent-connection cap (per~/code/min-ctllessons.md) shall be documented as a comment near the vsock registration; v0.1 needs <10 concurrent connections.
Proof Artifacts:
- Test:
tests/bridge_e2e.rs(gatedMINVMD_E2E=1,#[ignore]) boots a VM whose guest listens on vsockVSOCK_PORT(stub or shim, e.g.socat VSOCK-LISTEN:VSOCK_PORT,fork EXEC:cat), opens 5 concurrent host UDS connections, each writes a distinct payload and reads it back. All 5 succeed demonstrates libkrun-multiplexed bidirectional bridging. - CLI: With a stub
minimaldreachable on vsockVSOCK_PORT, runningnc -U $XDG_RUNTIME_DIR/minimal/minimald.sockfrom the host (or a CLI integration) yields the emptylist-sessionsresponse end-to-end demonstrates the host→guest path.
Unit 4: Lifecycle daemon — auto-spawn, status, stop
Purpose: Daemon UX. minimal calling minvmd for the first time auto-spawns it; subsequent calls reuse; minvmd status introspects; minvmd stop shuts down gracefully.
Depends on: Unit 3
Affected areas: crates/minvmd/src/cmd/{run,status,stop}.rs (new), crates/minvmd/src/state.rs (new), crates/minvmd/src/lifecycle.rs (new), crates/minimal2/src/main.rs (extend)
Functional Requirements:
- R4.1: State and PID files shall live under
$XDG_STATE_HOME/minimal/minvmd/(default~/.local/state/minimal/minvmd/):state.toml(lifecycle enum +vmm_pid+started_at),vmm.pid,lifecycle.lock.state.tomlwrites shall be atomic (tmp + rename + fsync). - R4.2:
minvmd runshall be a foreground supervisor (parent of the libkrun child + owner of the bridge);minvmd run --detachshall background-spawn and return only after the host UDS is accepting connections, with a configurable timeout (default 8s). - R4.3:
minvmd statusshall print human-readable status by default and JSON with--json(fields:state,vmm_pid,uptime_seconds,vcpus,ram_mib). Exit code 0 if running, 1 if stopped, 2 on lock contention. - R4.4:
minvmd stopshall SIGTERM the vmm child, wait up to 5s, SIGKILL on timeout, then removevmm.pidand resetstate.tomltoStopped. The command shall be idempotent — stopping an already-stopped VM exits 0. - R4.5: On macOS,
crates/minimal2shall checkstate.tomlbefore connecting to the UDS; if nominvmdis running it shall spawnminvmd run --detachand wait (with timeout) for the UDS. On Linux this path shall be a no-op. - R4.6: State transitions shall be guarded by an
fd-lock-style file lock onlifecycle.lockso concurrent CLI invocations cannot race. Recovery from a panicking transition (e.g. crash mid-Starting) shall be handled by an RAII guard modelled onmin-ctl'sStartingGuard— drop without explicit commit resets toStopped. - R4.7: All lifecycle transitions shall pass through a pure
next_state(current: Lifecycle, action: Action) -> Result<Lifecycle, InvalidTransition>function with no I/O, exhaustively unit-tested.
Proof Artifacts:
- Test:
crates/minvmd/src/lifecycle.rsincludes table-driven#[test]s for every legal and illegal transition;cargo test -p minvmd lifecycle::passes demonstrates the pure state machine. - CLI:
minvmd stop && minvmd status --jsonprints{"state":"stopped",...}and exits 1 demonstrates stop + status semantics. - CLI: From a clean state (no minvmd running),
minimal lson a Mac succeeds within 8s and a subsequentminvmd statusreportsrunning; a secondminimal lscompletes in <500ms demonstrates auto-spawn + warm reuse.
Non-Goals (Out of Scope)
- Networking — gated on .github/workflows/ci.yml: check if
Cargo.lockis up-to-date #160 (gvproxy spike). v0.1 VMs have no net device; in-session package installs and outbound git operations will not work yet. Document loudly. - Multi-VM / multi-tenant — single named VM (
default); multi-VM is a v0.2+ concern. minvmd init/ OCI image fetch / cosign verification — kernel and rootfs paths are passed in via env. Image-fetch pipelines are a separate concern (virtio-linux+ a future Alpine package + the minimal graph).- Virtiofs / live host mounts — per
~/code/min-ctllessons (TCC + provenance xattr issues, fd starvation), v0.1 has zero live mounts. File transport into the VM isminimald's problem (tar push/pull per all: clippy fix, update rustls-webpki #151). brew servicesregistration — auto-spawn from the CLI suffices for v0.1; a brew service can layer on later without changing the contract.- PTY supervision / session sandboxing — those live in
minimald, notminvmd. - Linux build of
minvmdbeyond the no-op shim — nothing to run on Linux. - OS suspend/resume of the VM, RAM resizing, vcpu hot-add — deferred.
- Lifting code from
min-ctl— we reference patterns only; no code vendoring.
Design Considerations
Process model
krun_start_enter never returns on success — it exit()s with the guest workload's exit code. This forces a parent/child split:
minvmd run (parent — supervisor)
└── minvmd __krun-vmm (hidden child — calls krun_start_enter)
└── libkrun + Alpine VM (the actual VM)
└── minimald (pid-1) (in-VM, via krun_set_exec)
Parent owns: state.toml, lifecycle.lock, and lifecycle supervision. The host UDS is not a parent-owned accept loop — libkrun binds and forwards it (registered via krun_add_vsock_port2 before the child enters), so neither parent nor child runs a userspace byte relay. Child owns: libkrun context, kernel/rootfs paths. They communicate via a single-use auth token (written to state dir mode 0600, verified by child, deleted immediately) plus signals. This pattern is lifted from ~/code/min-ctl/src/cmd/vmm_child.rs and ~/code/min-ctl/src/cmd/start.rs.
Reference patterns (no code vendored)
| Pattern | min-ctl reference |
|---|---|
| FFI safety wrappers | src/vm/krun/raw.rs |
| Lifecycle state machine | src/vm/lifecycle.rs |
StartingGuard RAII recovery |
src/cmd/start.rs:64-138 |
| Atomic state persistence | src/vm/state.rs |
| Child VMM entry pattern | src/cmd/vmm_child.rs |
| Single-use auth token (T36) | src/cmd/start.rs |
| XDG home resolution | src/home.rs |
Hard lessons baked in
- No
$HOMEvirtiofs — TCC + provenance xattr issues on macOS Tahoe. Zero virtiofs mounts in v0.1. - TSI ~62 concurrent connection cap — fine for v0.1 (<10 concurrent), document the constraint, revisit when networking lands.
- Error fidelity — never collapse
Backend { op, source: io::Error }into aString; the errno survives viaio::Error::from_raw_os_errorandError::source(). - Stubs are sticky — every stub shall
panic!/bail!/unimplemented!explicitly; no silent no-ops.
What we deliberately do not do (vs min-ctl)
- No OCI image fetch + cosign — the package graph owns image integrity.
- No K8s quantity / Go duration parsers, no
config.toml— overkill for v0.1. - No
shell/attach/exec/push/pull/mount/logs/mcpsubcommands — those are min-ctl's product surface, not minvmd's. minvmd is a pure transport-and-VM-lifecycle daemon.
Repository Standards
- Workspace conventions from
CLAUDE.md: workspace-pinned deps;cargo fmt && cargo test -- --include-ignored;cargo clippy --allow-dirty --fix --all-targets -- -D warnings; noprintln!/eprintln!outside the CLI surface (usetracing); structured fields not interpolated strings (tracing::info!(pkg = %name, "msg")); typed error enums in library code,anyhow::Resultonly at CLI boundaries. - Naming:
minvmd(matchesminimald). - Platform gates:
#[cfg(target_os = "macos")]for all libkrun-touching code; a stub Linux entry thatbail!s. - Tests: integration tests under
tests/; libkrun-touching tests#[ignore]and gated onMINVMD_E2E=1; pure state-machine + parser tests run unconditionally. - Unsafe: every
unsafeblock carries a// SAFETY:comment justifying every caller invariant. - Dependencies:
nix,tokio,anyhow,serde,toml,tracing(already in workspace);fd-lock(new, workspace-pin). Link libkrun directly viabuild.rs; do not pull alibkruncrate dependency.
Verification
Project maturity: Established
Available commands:
| Check | Command |
|---|---|
| Lint | cargo clippy --allow-dirty --fix --all-targets -- -D warnings |
| Build | cargo build -p minvmd (Linux: shim; macOS: full) |
| Test | cargo test -p minvmd (unit + pure); MINVMD_E2E=1 cargo test -p minvmd -- --include-ignored (full) |
Greenfield bootstrapping: N/A — all commands available
End-to-end manual verification (Mac):
cargo build -p minvmd --release && codesign --entitlements crates/minvmd/minvmd.entitlements --force -s - target/release/minvmd- Build
virtio-linux(pkgs#154); stage an Alpine minirootfs viascripts/fetch-alpine.sh; exportMINVMD_KERNEL_PATHandMINVMD_ROOTFS_PATH. minvmd run --detach && minvmd status --json→ reports{"state":"running",...}.nc -U ~/.local/state/minimal/minvmd/minimald.sockreaches a stubminimaldrunning in the VM.minvmd stop && minvmd status→ reportsstopped, exit 1.
CI gate: existing Linux-only CI stays green via the no-op shim. Optional build-macos job that runs cargo check -p minvmd once a Mac runner is available.
Technical Considerations
- libkrun linking — pinned to a known-good version (initially the slp/krun Homebrew tap version used by min-ctl, currently v1.18.0).
build.rsemitscargo:rustc-link-searchandcargo:rustc-link-arg=-Wl,-rpathpointing at/opt/homebrew/libwith aLIBKRUN_PREFIXenv override. - Hidden
__krun-vmmsubcommand — modelled on min-ctl'ssrc/cmd/vmm_child.rs. Not in--help; verified-via-auth-token; the only entry point that callskrun_start_enter. - State file format — TOML with serde; one file per VM (in v0.1, only
default). Lifecycle enum isNotProvisioned | Stopped | Starting | Running | Stopping. - Auto-spawn from
minimal2— implementation lives incrates/minimal2/src/main.rsbehind#[cfg(target_os = "macos")]. On Linux it is a no-op; the CLI talks tominimalddirectly.
Security Considerations
- Single entitlement:
com.apple.security.hypervisor. No network, no file-access-outside-home, no Apple Developer Program membership required (ad-hoc signing viacodesign -s -). - Host UDS perms: mode 0600, owner-only.
LOCAL_PEERCREDcheck recommended but not required at v0.1 since the UDS perms already gate access. - No authentication on the bridge — fine because access is mode-gated. Do not expose the bridge over TCP without rethinking auth.
- Single-use auth token between parent
minvmd runand childminvmd __krun-vmm(T36 pattern from min-ctl): written to$XDG_STATE_HOME/minimal/minvmd/vmm.authmode 0600, verified by child, deleted on first read. Prevents stray re-execs of the hidden subcommand. - Image provenance is deferred — v0.1 reads kernel + rootfs from caller-supplied paths. Once the minimal package graph wires the artifacts, content-addressed hashes already provide integrity.
Success Metrics
- Mac developer runs
minimal lson a fresh install with no setup beyond install + first-time package fetch and gets a result in < 8s cold, < 500ms warm. - Crate compiles green in CI on Linux (no-op shim) and is buildable on Mac.
- Smoke test (
MINVMD_E2E=1) covers FFI bring-up, boot-to-marker, and 5-way concurrent bridge connections. - Zero
unsafeblocks without a// SAFETY:comment. Zerounwrap()outside#[cfg(test)]. Zeroprintln!/eprintln!outside the CLI surface.
Open Questions
-
Alpine rootfs source. v0.1 spec specifies
scripts/fetch-alpine.sh(download + sha256-verify upstream Alpine minirootfs to~/.cache/minimal/minvmd/rootfs/). Migration path: write a siblingalpine-minirootfsminimal package ingominimal/pkgsoncevirtio-linux(crates/minimal: print available tasks inminimal status#154) merges, then minvmd consumes both via the package graph instead of env vars. Track as a follow-up issue. -
Vsock port for
minimald. Proposed 2222 (avoids min-ctl's agent port 7350 so they can coexist on a Mac dev box). Confirm with crates/minimal: improve tasks list inminimal status, add task description field #156 owner. (VSOCK_PORTis a named constant either way.) -
Guest-side vsock terminator for the real
minimald. Bring-up is settled: v0.1 uses a vsock stub that listens onVSOCK_PORTdirectly (R3.4), so no terminator is needed yet. The open decision is how the realminimaldgets reached once it replaces the stub, since it binds a UNIX socket, not vsock:- (a) vsock→UDS shim — a tiny in-guest process listens on
VSOCK_PORTand forwards each connection 1:1 tominimald'sssh.sock(e.g.socat VSOCK-LISTEN:VSOCK_PORT,fork UNIX-CONNECT:ssh.sock). Keepsminimaldbyte-identical across host-Linux and in-VM; adds a process and a hop. - (b) vsock-native
minimald— generalize the listener edge (Connection::from_socket/Server::run_on_uds) overimpl AsyncRead + AsyncWrite, which russh already supports, and add arun_on_vsock. No protocol change, one fewer hop; givesminimalda second listen mode.
RESOLVED → (b) vsock-native
minimald, per @twitchyliquid64 (docs(minvmd): minvmd host-daemon spec #280 (comment)): generalize the russh listener edge overimpl AsyncRead + AsyncWriteand add arun_on_vsock, so nothing funky runs inside the VM — no in-guest shim. v0.1 still ships the vsock stub (R3.4); the swap-in is a follow-up inminimald(Tom's crate). Resolved sub-point: theadd_vsock_port2listenflag istruefor our host-initiated direction, per the installedlibkrun.h. - (a) vsock→UDS shim — a tiny in-guest process listens on
-
In-VM
minimaldsupervision. Runminimaldas pid-1 viakrun_set_exec(..., "minimald"), or boot a tiny init (busybox/OpenRC) that launches it? Pid-1 is simpler butminimaldthen owns signal forwarding + zombie reaping. Proposed: pid-1 for v0.1; revisit if reaping becomes painful. -
Brew distribution. Out of scope per non-goals, but flagging that the codesign step must be reproducible on contributors' machines — justfile target covers this.
Scope notes
- macOS-only; Linux is a no-op shim, so the existing Linux-only CI stays green. The
MINVMD_E2Eproof artifacts need a Mac runner — CI gate is the shim build plus an optionalcargo check -p minvmdon a Mac runner. - Networking is deferred to .github/workflows/ci.yml: check if
Cargo.lockis up-to-date #160; v0.1 VMs have no net device. - Open Question Parallel builds #3 is resolved to (b) vsock-native
minimald(see the Open Questions section). It does not block Units 1–3, which build against the v0.1 vsock stub (R3.4). - Open Question Cycle detection #2 (vsock port 2222) wants a nod from the crates/minimal: improve tasks list in
minimal status, add task description field #156 owner but is a named constant — non-blocking. - The source spec lives in docs(minvmd): minvmd host-daemon spec #280, left open for now.
sdd-specwill open its own spec PR from this tracking issue.
Pull Requests
Package dogfood + Stage 2 (minimald running in the guest), stacked:
- feat(minvmd): boot a microVM from kernel + rootfs built as minimal packages #367 — boot a microVM from kernel + rootfs built as minimal packages (Stage 1, merged)
- feat(minvmd,minimald): boot minimald as pid-1 via initramfs #373 — Stage 2: boot minimald as pid-1 via initramfs (stacks on main)
- feat(minimald,minvmd): serve sessions directly over the vsock bridge #374 — Stage 2: serve sessions over the vsock bridge (stacks on feat(minvmd,minimald): boot minimald as pid-1 via initramfs #373)
- [WIP] feat(minvmd,minimald): Stage 2 — minimald as guest pid-1 (e2e integration) #362 — superseded by feat(minvmd,minimald): Stage 2 — minimald as pid-1 via initramfs #368 (closed)
- feat(minimald): vsock guest (pid-1) mode for minvmd #361, feat(minvmd,minimald): Stage 2 — minimald as pid-1 via initramfs #368 — superseded by feat(minvmd,minimald): boot minimald as pid-1 via initramfs #373 + feat(minimald,minvmd): serve sessions directly over the vsock bridge #374, re-sliced along capability lines (boot, then session); block-root dropped as a stepping stone (closed)
Upstream packages (gominimal/pkgs): gominimal/pkgs#229 (microvm-rootfs + virtio-kernel-raw), gominimal/pkgs#231 (libssl fix).
Steer the pipeline with the comment commands from the spec.md template (/spec, /fastpath, /triage, /approve, /dispatch, /revise <note>, /execute), each gated to commenters with write access. Merging the spec PR advances to architecture; merging the architecture PR posts the proposed plan as a comment here. When an agent needs a human decision it applies needs-human and comments — clear the label once answered and the agent resumes.
Activity
spec(minvmd-host-daemon): add specification for minvmd macOS VM host …
gominimal-aw-bot commentedon Jun 3, 2026
Pull request created: #313
gominimal-aw-bot commentedon Jun 3, 2026
Spec PR opened: spec(minvmd-host-daemon): minvmd macOS VM provider host daemon.
Please review and merge the spec PR to advance the tracking issue from the spec phase into triage. Merging the spec PR will close the spec sub-issue (
Closes #<spec-sub-issue>is added to the PR body bysdd-pr-sanitize).docs(minvmd): address review feedback and add repo conventions
docs(minvmd): add specification for minvmd macOS VM host daemon
docs(minvmd): address review feedback and add repo conventions
gominimal-aw-bot commentedon Jun 3, 2026
The spec PR has been merged: spec(minvmd-host-daemon): minvmd macOS VM provider host daemon.
The merged spec file is at
docs/specs/01-spec-minvmd-host-daemon/01-spec-minvmd-host-daemon.md.Next step: A write-access author comments
/triageon this tracking issue to start the architecture phase.norrietaylor commentedon Jun 3, 2026
/triage
33 remaining items
gominimal-aw-bot commentedon Jun 5, 2026
✅ Feature complete — all units closed.
Every deliverable under tracking issue #311 is now done:
The tracking issue is in
sdd:done. A human should do the final review and close this issue.[-]feature: minvmd macOS VM provider host daemon[/-][+]feature: minvmd VM provider host daemon[/+]feat(minimal2): enable minvmd auto-spawn on Linux
jessie-minimal commentedon Jun 18, 2026
feat(sessions,minimald,minvmd): session persistence contracts + provi…
feat(sessions,minimald,minvmd): session persistence contracts + provi…
feat(sessions,minimald,minvmd): session persistence contracts + provi…
feat(sessions,minimald,minvmd): session persistence contracts + provi…