stacklok / stacklok/mecatl

Define the microVM environment architecture and path contract

Open
#527 0 comments 0 reactions 1 assignee View on GitHub

@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 /workspace returned 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_profile independently from the existing tool-surface profile.
  • 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.txt remain consistent.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.