stacklok / stacklok/mecatl

Build the authenticated guest filesystem and exec protocol

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

@JAORMX is already working on this.

Since Aug 14, 2026.

enhancement
Dominant language
Go
Stars
152
Forks
16
Avg merge
14h 48m
Merged PRs (30d)
536

Description

Parent: #526

Outcome

The host harness executes filesystem operations and Bash inside the exact same guest namespace through a versioned, authenticated, bounded protocol over libkrun/go-microvm vsock-to-UDS transport.

Scope

  • Define protocol negotiation and required capability discovery.
  • Bind every connection/request to session ID, opaque EnvironmentRef, generation, and local owner.
  • Add structured Workspace operations matching the current contract: Read, Stat, ReadVersion, CreateFile, conditional ReplaceFile, Glob, and Grep.
  • Preserve mecatl's I/O-free read ledger, create-only behavior, conditional replacement, structured conflict errors, and path confinement.
  • Add structured exec frames for start, ordered stdout/stderr, exit, cancellation, and terminal transport faults.
  • Cancellation kills the guest process group and preserves partial output.
  • Bound frames, output, duration, concurrency, and resource use; provide backpressure.
  • Keep SSH for bootstrap/debugging only.
  • Authenticate the local control socket through Linux/macOS peer credentials; reserve a future credential-free principal assertion following #452 without passing bearer tokens/scopes/authority.

Acceptance

  • Read/Edit/Write/Grep/Glob and Bash observe one coherent /workspace namespace.
  • A concurrent external change produces a model-visible version conflict rather than an overwrite.
  • Nonzero process exit is not a transport error; cancellation and transport failure are distinguishable.
  • Wrong owner/session/ref/generation, stale or replayed endpoints, malformed/oversized frames, and unauthenticated peers fail closed.
  • The guest cannot connect to another session's data plane or the microvmd control plane.
  • Protocol skew rejects missing required capabilities rather than degrading to host execution.

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.