Define the microVM environment architecture and path contract
Open
@JAORMX is already working on this.
Since Aug 14, 2026.
documentation
enhancement
- Dominant language
- Go
- Stars
- 152
- Forks
- 16
- Avg merge
- 14h 48m
- Merged PRs (30d)
- 536
Description
Parent: #526
Outcome
The microVM feature has one explicit architectural contract for path identity, trust boundaries, package/module boundaries, environment profiles, lifecycle, and deferred identity capabilities before implementation fans out.
Scope
- Add the new ADR covering the external local microvmd, nested module boundary, host/guest responsibilities, session-lifetime environment, and no-local-fallback rule.
- Define the three path roles precisely:
- source checkout supplied by the local client;
- prepared host session worktree persisted as the session Workspace;
- guest execution root
/workspacereturned by the live Environment Workspace.
- Define which project artifacts are discovered host-side from the prepared worktree and which user-global artifacts remain outside the VM.
- Define skill-asset materialization/read-only mounting.
- Define
environment_profileindependently from the existing tool-surfaceprofile. - Define the local trusted-UID identity mode and the reserved #452-compatible future principal assertion.
- Define supported first-release platforms and explicit deferrals: schedules, remote placement, multi-user enforcement, cross-principal sharing.
- Update ADR 0027 resource and rehydration inventories for every daemon, VM, cache, socket, stream, registry, worktree, reconciler, and lifecycle record that outlives a call.
Acceptance
- Every persisted and live path field has one non-overlapping meaning.
- The agent-facing tool path never receives or requires the host source/worktree path.
- No heavy microVM dependency enters
engine/or the root module's default build. - The trust boundary clearly distinguishes guest egress from host service egress.
- Deferred jhrozek identity issues are named with their exact trigger and do not block local phase 1.
- Architecture, implementation notes, usage, user docs, and generated
llms.txtremain consistent.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.