docs(infra): design Compass self-host runner + adoption strategy (RIG-3070) by rigel-mintaka · Pull Request #804 · RigelBuild/compass

rigel-mintaka · 2026-08-31T18:54:48Z

Documents Matt's ruled self-host runner topology and adoption strategy as a frozen-on-merge contract in a new design record under docs/designs/infra/runtime/compass-runner-adoption-strategy/. Mints DL-318.

What this record freezes

The security boundary follows the trust model, not the deployment uniformly (Matt, 2026-08, amended 2026-08-31):

Untrusted multi-tenant operation = microVM-only. Running code from mutually-distrusting tenants needs the KVM hardware-isolation boundary; microVM (cloud-hypervisor/KVM) is required there. The frozen corpus already fixes that end state (microvm-runner.md:403-405); this record scopes that end state to the untrusted-multi-tenant trust model.
Self-host single-tenant = podman is a permanent, supported entry tier, requiring no /dev/kvm — it runs on any cheap VPS or box. A self-host operator runs their own agents on their own code on their own box, so there is no untrusted tenant to isolate and the KVM boundary is optional. microVM is the recommended (not required) self-host upgrade, for defense-in-depth or an operator who runs untrusted code or shares the box. This amends the frozen KVM-only amendment with a self-host carve-out, honestly flagged as reopening a frozen decision, and distinguished from the amendment's own already-rejected carve-out (which was about the untrusted-multi-tenant boundary, not this single-tenant case).
Embedded-local is REVIVED as the cross-OS developer front door. With podman permanent for self-host, a developer's own laptop is the single-tenant case in its purest form (no untrusted tenant to isolate), so embedded-local is legitimate: install the app, launch, sign in with your own Claude Code / Codex subscription, and go. This record records the direction only; the app-architecture reversal (un-retiring compass-app's supervisor invocation / embedded config arm / bundle, reversing DL-235's client-only charter) is designed in the compass-native lane's embedded-revival record.
The always-on-server argument survives as the graduation motivation, not an argument against embedded. The funnel is embedded-local (front door, your box) → self-host stack (always-on, dedicated box/VPS) → the hosted service. "Dual runtimes" here means the two existing SelectBackend stack backends (podman + microVM), both already shipping — embedded-local runs the same podman backend locally, not a third runtime.
macOS: podman-machine is the Mac embedded-local front-door path and a permanent Mac self-host option (no nested virt, any Mac); microVM-on-Mac stays nested-only/unsupported; the remote-Linux client path (DL-235-era) stands.

Relationship to the frozen corpus

The ruling ratifies one frozen record, records the deferred reversal of a second, and amends a third:

DL-259 stands — the self-host microVM stack remains a host-level KVM bring-up, no compose/Swarm packaging. The podman carve-out adds a tier beside it, it does not repackage the KVM stack.
DL-235 is being reversed — its client-only charter retired embedded supervision; under the 2026-08-31 embedded-revival ruling that reversal is designed in the compass-native lane's record. This record records only the topology direction that motivates it.
The KVM-only amendment is amended with a self-host carve-out — its no-fallback posture is ratified for untrusted multi-tenant operation and amended for self-host single-tenant, where podman is a first-class permanent runtime choice, not a lesser boundary imposed on an unwitting tenant. This carve-out is the net-new ruling in the record.

Scope boundary

How a hosted multi-tenant service adopts, sequences, and deploys the microVM-only boundary is a managed-plane concern and is out of scope for this public OSS record (docs/concepts/self-host-and-managed.md). This record carries the core capability and the self-host/embedded adoption strategy only.

Tasks (filed at freeze)

T1 — microVM production-readiness bar (OQ-1) frozen and the microVM-only pinning path supported (backend pinned behind the VerifyMicroVMSupport hard gate); podman backend retained permanently for self-host. Owner: compass-runner.
T2 — guided self-host onboarding guide, opening with the embedded-local front door, then both self-host graduation paths (podman entry tier, recommended microVM upgrade). Owner: distribution/docs lane.

The embedded app-architecture reversal is deliberately NOT a task here — it is the compass-native lane's record. OQ-1 (microVM readiness bar), OQ-2 (VPS provider pick), OQ-3 (macOS podman-machine socket spike) are deferred and non-freeze-blocking.

Ledger-impact: mints DL-318 in docs/designs/DECISIONS.md.
Spec-impact: none (design record; the runner-topology spec follows the impl tasks post-freeze).
Refs RIG-3070

Co-authored-by: Matt Wilkinson matt@rigel.build

linear-code · 2026-08-31T18:54:51Z

RIG-3070

github-actions · 2026-08-31T18:56:30Z

Compass engineering docs preview: https://9e745fcb.compass-eng-docs.pages.dev

Deployed from compass-obs/rig-3070-runner-adoption-strategy at da36ec0.

Changed pages:

…sh macOS (RIG-3139) Designs the reversal of the RIG-2542 client-only retirement: mode="embedded" returns to the Compass native app as the low-friction onboarding / local-dev front door, ADDED ALONGSIDE the fully-surviving client mode. The retirement's premise (the microVM Runner's KVM floor retiring local agent execution) is falsified now that podman is a permanent supported single-tenant tier per the trust-model boundary (DL-318, compass-obs #804). Covers the mode-selection contract, supervisor re-wire against the current stack, cross-OS preflight, bundle re-scope (sidecars return, postgres stays a DL-260 container), the macOS podman-machine provisioning spike, and the UI embedded boot arm. Records the record on the ui/ design path (RIG-3113 dissolved product/ into ui/) and lands the ledger delta in DECISIONS.md: new rows DL-319 (dual-mode thesis), DL-320 (dual-mode app.toml), DL-321 (sidecar bundle sans postgres); status flips DL-235/237/238 → Superseded by DL-319/320/321. DL-236's standalone-compass-stack half stays Active. Folds Matt's freeze-gate topology + backend feedback: the §Topology matrix separates the two independent axes (app mode: embedded/client; runner backend: podman/microVM) and records the recommended backend per funnel entry — embedded-local is podman-primary (macOS cannot do microVM; WSL2 has no KVM out of the box), self-host is microVM-recommended with podman the cost-sensitive tier, managed is microVM. Scrubs managed-hosted to the trust-model boundary only, with an OSS-core scope note keeping product-strategy specifics out of this repo. Adds three load-bearing open questions with recommendations for Matt's gate: OQ-9 (docker socket vs force-podman — force-podman: the --userns=keep-id:uid= isolation boundary is podman-specific), OQ-10 (apple/container as a macOS backend — defer: macOS-26 + Apple-silicon-only, pre-1.0), OQ-11 (embedded microVM on Linux — v1 container-only, follow-up). Also folds the prior review passes' podman-version FATAL preflight (delta 4, OQ-8) and the doc-comment reconciliations. Refs RIG-3139 Spec-impact: adds the embedded-mode revival design record (Draft) under docs/designs/ui/ Ledger-impact: DL-319/320/321 added; DL-235/237/238 flipped to Superseded Co-authored-by: Matt Wilkinson <matt@rigel.build>

trunk-io · 2026-09-03T01:15:02Z

Merging to main in this repository is managed by Trunk.

To merge this pull request, check the box to the left or comment /trunk merge below.

After your PR is submitted to the merge queue, this comment will be automatically updated with its status. If the PR fails, failure details will also be posted here

…sh macOS (RIG-3139) (#833) Designs the reversal of the RIG-2542 client-only retirement: mode="embedded" returns to the Compass native app as the low-friction onboarding / local-dev front door, ADDED ALONGSIDE the fully-surviving client mode. The retirement's premise (the microVM Runner's KVM floor retiring local agent execution) is falsified now that podman is a permanent supported single-tenant tier per the trust-model boundary (DL-318, compass-obs #804). Covers the mode-selection contract, supervisor re-wire against the current stack, cross-OS preflight, bundle re-scope (sidecars return, postgres stays a DL-260 container), the macOS podman-machine provisioning spike, and the UI embedded boot arm. Records the record on the ui/ design path (RIG-3113 dissolved product/ into ui/) and lands the ledger delta in DECISIONS.md: new rows DL-319 (dual-mode thesis), DL-320 (dual-mode app.toml), DL-321 (sidecar bundle sans postgres); status flips DL-235/237/238 → Superseded by DL-319/320/321. DL-236's standalone-compass-stack half stays Active. Folds Matt's freeze-gate topology + backend feedback: the §Topology matrix separates the two independent axes (app mode: embedded/client; runner backend: podman/microVM) and records the recommended backend per funnel entry — embedded-local is podman-primary (macOS cannot do microVM; WSL2 has no KVM out of the box), self-host is microVM-recommended with podman the cost-sensitive tier, managed is microVM. Scrubs managed-hosted to the trust-model boundary only, with an OSS-core scope note keeping product-strategy specifics out of this repo. Adds three load-bearing open questions with recommendations for Matt's gate: OQ-9 (docker socket vs force-podman — force-podman: the --userns=keep-id:uid= isolation boundary is podman-specific), OQ-10 (apple/container as a macOS backend — defer: macOS-26 + Apple-silicon-only, pre-1.0), OQ-11 (embedded microVM on Linux — v1 container-only, follow-up). Also folds the prior review passes' podman-version FATAL preflight (delta 4, OQ-8) and the doc-comment reconciliations. Refs RIG-3139 Spec-impact: adds the embedded-mode revival design record (Draft) under docs/designs/ui/ Ledger-impact: DL-319/320/321 added; DL-235/237/238 flipped to Superseded Co-authored-by: Matt Wilkinson <matt@rigel.build>

…-3070) Frozen-on-merge design record for the self-host runner topology and adoption strategy. The security boundary follows the trust model: untrusted multi-tenant operation requires the microVM hardware boundary; self-host single-tenant deployments keep podman as a permanent, supported entry tier (no /dev/kvm), microVM recommended not required; embedded-local mode revived as the cross-OS podman-backed developer front door (app-architecture reversal designed in the compass-native embedded-revival record). Records DIRECTION only. When and how a hosted multi-tenant service sequences its move to microVM-only is a managed-plane rollout decision, out of scope here (docs/concepts/self-host-and-managed.md). Encodes DL-318. Stacked on the managed-boundary naming-rule convention docs (RIG-3153). Co-authored-by: Matt Wilkinson <matt@rigel.build>

rigel-mintaka force-pushed the compass-obs/rig-3070-runner-adoption-strategy branch from f4f27c2 to 650c699 Compare August 31, 2026 19:47

rigel-mintaka marked this pull request as ready for review August 31, 2026 19:47

rigel-mintaka requested a review from mattwilkinsonn as a code owner August 31, 2026 19:47

rigel-mintaka marked this pull request as draft August 31, 2026 23:21

rigel-mintaka force-pushed the compass-obs/rig-3070-runner-adoption-strategy branch 2 times, most recently from 30a299d to 99722b5 Compare September 1, 2026 04:13

rigel-mintaka mentioned this pull request Sep 1, 2026

docs(product): design embedded-mode revival — dual-mode returns, finish macOS (RIG-3139) #833

Merged

rigel-mintaka force-pushed the compass-obs/rig-3070-runner-adoption-strategy branch from 99722b5 to 43fb66c Compare September 1, 2026 05:06

rigel-mintaka marked this pull request as ready for review September 1, 2026 05:07

rigel-mintaka marked this pull request as draft September 2, 2026 20:29

rigel-mintaka changed the base branch from main to compass-obs/managed-boundary-naming-rule September 2, 2026 21:27

rigel-mintaka force-pushed the compass-obs/rig-3070-runner-adoption-strategy branch from 43fb66c to d33fa75 Compare September 2, 2026 21:27

rigel-mintaka mentioned this pull request Sep 2, 2026

docs(concepts): tighten managed-boundary naming rule + capability-vs-product-end-state (RIG-3153) #839

Merged

Base automatically changed from compass-obs/managed-boundary-naming-rule to main September 3, 2026 01:15

rigel-mintaka force-pushed the compass-obs/rig-3070-runner-adoption-strategy branch from d33fa75 to 54895e9 Compare September 3, 2026 01:18

rigel-mintaka force-pushed the compass-obs/rig-3070-runner-adoption-strategy branch from 54895e9 to da36ec0 Compare September 3, 2026 02:28

Navigation Menu

Uh oh!

docs(infra): design Compass self-host runner + adoption strategy (RIG-3070) - #804

docs(infra): design Compass self-host runner + adoption strategy (RIG-3070)#804
rigel-mintaka wants to merge 1 commit into
mainfrom
compass-obs/rig-3070-runner-adoption-strategy

rigel-mintaka commented Aug 31, 2026 •

edited

Loading

Uh oh!

linear-code Bot commented Aug 31, 2026

Uh oh!

github-actions Bot commented Aug 31, 2026 •

edited

Loading

Uh oh!

trunk-io Bot commented Sep 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

rigel-mintaka commented Aug 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this record freezes

Relationship to the frozen corpus

Scope boundary

Tasks (filed at freeze)

Uh oh!

linear-code Bot commented Aug 31, 2026

Uh oh!

github-actions Bot commented Aug 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

trunk-io Bot commented Sep 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

rigel-mintaka commented Aug 31, 2026 •

edited

Loading

github-actions Bot commented Aug 31, 2026 •

edited

Loading