arch(minvmd-host-daemon): minvmd macOS VM provider host daemon by gominimal-aw-bot[bot] · Pull Request #317 · gominimal/minimal

gominimal-aw-bot · 2026-06-03T23:16:17Z

Architecture record for the minvmd macOS VM provider host daemon (#311).

Adds docs/specs/01-spec-minvmd-host-daemon/architecture.md capturing:

Process model: parent/child split forced by krun_start_enter's diverging semantics; parent supervises lifecycle, child enters the VMM.
Socket model: libkrun-owned host UDS via krun_add_vsock_port2(listen=true) — no userspace byte relay in minvmd.
Lifecycle state machine: pure next_state function, atomic state.toml persistence, fd-lock concurrency guard, RAII recovery.
Platform gating: #[cfg(target_os = "macos")] for libkrun code; Linux stub keeps CI green.
Auto-spawn: minimal2 spawns minvmd run --detach on macOS when no daemon is running.
Alternatives: userspace byte relay (rejected — duplicates libkrun's in-kernel work) and direct minimald on macOS (not viable — requires Linux namespaces).

Translated from the plan document on the tracking issue (issue #311 carries plan:provided).

Next step: Review and merge this PR to advance the tracking issue to phase B (Unit decomposition).

Refs feature: minvmd VM provider host daemon #311

Generated by sdd-triage for issue #311 · ● 34.7M · ◷

Closes #316

Summary by CodeRabbit

Documentation
- Added architecture specification documenting the design and implementation strategy for the minvmd system component, including lifecycle management and integration approach.

Architecture record for the minvmd macOS VM provider host daemon (#311). Translated from the plan document: process model (parent/child split), socket model (libkrun-owned UDS, no host relay), lifecycle state machine, platform gating, and auto-spawn from minimal2. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

coderabbitai · 2026-06-03T23:16:31Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 70fd4856-4c84-4a75-a99c-bdb693c2a7b2

📥 Commits

Reviewing files that changed from the base of the PR and between c7c87b4 and 2837f35.

📒 Files selected for processing (1)

docs/specs/01-spec-minvmd-host-daemon/architecture.md

📝 Walkthrough

Walkthrough

This pull request introduces the complete architecture specification for minvmd, a macOS-only VM provider host daemon that bridges host and guest processes via libkrun. The spec defines the three-process supervisor model, socket bridging, persisted lifecycle state machine with atomic recovery, platform-specific gating, required module structure, and design alternatives considered.

Changes

minvmd macOS Host Daemon Specification

Layer / File(s)	Summary
Architecture Overview and Process Model `docs/specs/01-spec-minvmd-host-daemon/architecture.md`	Defines frontmatter and the chosen three-process approach: parent supervisor, hidden child invoking `krun_start_enter`, and guest workload running `minimald` as pid-1.
Socket and Communication Model `docs/specs/01-spec-minvmd-host-daemon/architecture.md`	Specifies libkrun-owned UDS ↔ vsock bridging via `krun_add_vsock_port2`, crash-prune semantics, and macOS auto-spawn from `minimal2` with UDS readiness polling.
Lifecycle State Machine and Recovery `docs/specs/01-spec-minvmd-host-daemon/architecture.md`	Documents pure state machine with persisted `state.toml`, fd-based `lifecycle.lock`, atomic writes, and `StartingGuard` RAII pattern to prevent stuck states on crash.
Platform Gating and minimal2 Integration `docs/specs/01-spec-minvmd-host-daemon/architecture.md`	Covers macOS-only conditional compilation of libkrun code; Linux builds provide no-op shim; `minimal2` conditionally spawns `minvmd` on macOS with state polling.
Module Structure and Dependencies `docs/specs/01-spec-minvmd-host-daemon/architecture.md`	Enumerates `crates/minvmd` modules (image, vm, sock, state, lifecycle, cmd subcommands) and workspace dependencies: libkrun FFI addition and `fd-lock` for locking.
Design Rationale and Out-of-Scope `docs/specs/01-spec-minvmd-host-daemon/architecture.md`	Documents rejected alternatives (userspace relay), rules out direct Linux isolation on macOS, and lists knowledge gaps (networking, gvproxy, TSI deferred).

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related issues

Issue #311 (feature: minvmd macOS VM provider host daemon) — This spec document directly implements the requirements outlined in that issue, covering all R1–R4 functional areas.
Issue #312 — References the same minvmd daemon specification document being added.

Possibly related PRs

gominimal/minimal#313 — Both PRs add documentation specs for the same minvmd macOS host-daemon architecture, defining the lifecycle/process split and UDS↔vsock bridge model.

Suggested reviewers

norrietaylor

Poem

🐰 A spec takes shape on Hypervisor's stage,
Where libkrun dances with sockets and state,
Three processes waltz, recovering with care,
From macOS to Linux, bridging the air,
Minimal's daemon now mapped and fair! 🎭

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR is a documentation-only architecture specification that records planned design decisions from issue `#311` but does not implement the actual code requirements (FFI bindings, lifecycle state machine, boot flow, socket bridging, tests) outlined in the linked issue.	This PR documents the architecture; the actual implementation of minvmd code against the requirements in `#311` will be a separate PR that must verify: FFI discipline, build constraints, lifecycle state machine, socket bridging, boot flow, and test coverage.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and clearly describes the main change: adding an architecture specification for minvmd, the macOS VM provider host daemon.
Out of Scope Changes check	✅ Passed	The PR contains only the intended architecture specification document with no out-of-scope changes; all content is directly related to recording the minvmd design from issue `#311`.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

gominimal-aw-bot · 2026-06-03T23:20:08Z

sdd-validate — Architecture boundary

Boundary: Architecture
Gate set: Architecture gates
Result: Clean pass — no findings

Gate	Result
Decision and rationale present	✅ Pass — "Chosen approach" section documents process model (parent/child split forced by `krun_start_enter` semantics), socket model (libkrun-owned host UDS), lifecycle state machine (pure `next_state` function), platform gating, and auto-spawn, each with clear rationale.
Alternatives considered	✅ Pass — Two alternatives evaluated: (1) userspace byte relay in `minvmd` (rejected — duplicates libkrun in-kernel work, adds latency and complexity), (2) direct `minimald` on macOS (not viable — requires Linux namespaces).
Consistent with existing decisions	✅ Pass — No existing `decisions/` directory; no prior records to conflict with.
No implementation detail masquerading as a decision	✅ Pass — The cross-cutting decisions (process model, socket model, lifecycle state machine, platform gating) are genuinely architectural. The module table in "Data and interface changes" describes the architectural decomposition, not coding preferences.

All architecture gates passed. No Blocker, Warning, or Info findings.

Generated by sdd-validate for issue #317 · ● 5.9M · ◷

gominimal-aw-bot Bot mentioned this pull request Jun 3, 2026

feature: minvmd VM provider host daemon #311

Closed

5 tasks

github-actions Bot mentioned this pull request Jun 3, 2026

architecture: minvmd macOS VM provider host daemon #316

Closed

norrietaylor enabled auto-merge (squash) June 3, 2026 23:23

norrietaylor approved these changes Jun 3, 2026

View reviewed changes

norrietaylor merged commit cded362 into main Jun 3, 2026
14 checks passed

norrietaylor deleted the arch/minvmd-host-daemon-1e922f2c512e3876 branch June 3, 2026 23:23

coderabbitai Bot mentioned this pull request Jun 4, 2026

feat(minvmd): add krun_add_vsock_port2 FFI binding and host UDS bridge #345

Merged

Navigation Menu

Uh oh!

arch(minvmd-host-daemon): minvmd macOS VM provider host daemon - #317

arch(minvmd-host-daemon): minvmd macOS VM provider host daemon#317
norrietaylor merged 1 commit into
mainfrom
arch/minvmd-host-daemon-1e922f2c512e3876

gominimal-aw-bot Bot commented Jun 3, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jun 3, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related issues

Possibly related PRs

Suggested reviewers

Poem

❌ Failed checks (1 warning)

Uh oh!

gominimal-aw-bot Bot commented Jun 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

gominimal-aw-bot Bot commented Jun 3, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jun 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related issues

Possibly related PRs

Suggested reviewers

Poem

❌ Failed checks (1 warning)

Uh oh!

gominimal-aw-bot Bot commented Jun 3, 2026

sdd-validate — Architecture boundary

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

gominimal-aw-bot Bot commented Jun 3, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 3, 2026 •

edited

Loading