Skip to content

feat(vm): run the supervisor outside the guest workload - #2945

Merged
drew merged 20 commits into
codex/1737-rfc12-supervisor-primitivesfrom
codex/vm-host-supervisor
Sep 14, 2026
Merged

drew merged 20 commits into
codex/1737-rfc12-supervisor-primitivesfrom
codex/vm-host-supervisor

Conversation

@drew

@drew drew commented Aug 26, 2026

Copy link
Copy Markdown
Collaborator

Summary

Adopt the RFC 0012 split in the VM driver. openshell-supervisor runs on the host, while openshell-sandbox runs as guest init and owns the agent process tree.

The private guest channel uses the same pinned TLS server identity and launch-scoped sandbox JWT as every other driver, carried over vsock or the hypervisor Unix-socket mapping.

Related Issue

Part of #1737.

Changes

  • Boot the guest with the sandbox runtime, TLS server material, and public JWT verification keys.
  • Keep both supervisor JWTs and the pinned sandbox CA on the host.
  • Run the external host supervisor with durable runtime state.
  • Remove the guest NIC, TAP, gvproxy, nftables, and direct guest egress path.
  • Carry lifecycle, process control, TCP, and DNS over the authenticated Sandbox Protocol.
  • Keep gateway, provider, and upstream network access outside the guest.

Testing

  • mise run pre-commit
  • Focused VM isolation tests
  • Full VM E2E validation delegated to remote CI

Checklist

  • Follows Conventional Commits
  • Authored commits are signed off (DCO)

Stack

  1. feat(isolation): implement the RFC 0012 sandbox architecture #2942 — RFC 0012 core architecture
  2. feat(vm): run the supervisor outside the guest workload #2945 — VM driver (this PR)
  3. feat(docker): isolate workloads behind a companion supervisor #2965 — Docker driver
  4. feat(kubernetes): isolate workloads behind a dedicated supervisor #3144 — Kubernetes driver
  5. feat(podman): isolate workloads behind a separate supervisor #3230 — Podman driver
  6. perf(isolation): add TCP and DNS benchmark harnesses #3229 — performance harnesses

@copy-pr-bot

copy-pr-bot Bot commented Aug 26, 2026

Copy link
Copy Markdown

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

@github-actions

Copy link
Copy Markdown

@drew
drew force-pushed the codex/vm-host-supervisor branch from 4a8f295 to 532fa1b Compare August 26, 2026 07:08
@drew
drew changed the base branch from codex/rfc-0012-impl-base to codex/1737-rfc12-supervisor-primitives August 26, 2026 07:09
@drew
drew force-pushed the codex/vm-host-supervisor branch from 532fa1b to 02e80eb Compare August 26, 2026 08:50
@drew drew changed the title feat(vm): move supervisor outside guest boundary feat(isolation): prototype host-supervised VM and Docker boundaries Aug 26, 2026
@drew
drew force-pushed the codex/vm-host-supervisor branch from 7e10ae3 to 02e80eb Compare August 26, 2026 19:41
@drew drew changed the title feat(isolation): prototype host-supervised VM and Docker boundaries feat(vm): move supervisor outside guest boundary Aug 26, 2026
@drew
drew force-pushed the codex/vm-host-supervisor branch from 02e80eb to be91699 Compare September 1, 2026 00:13
@copy-pr-bot

copy-pr-bot Bot commented Sep 1, 2026

Copy link
Copy Markdown

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

@drew
drew force-pushed the codex/vm-host-supervisor branch from be91699 to 273655b Compare September 1, 2026 08:00
@drew
drew force-pushed the codex/vm-host-supervisor branch from 273655b to f7c163d Compare September 1, 2026 08:06
@drew
drew force-pushed the codex/vm-host-supervisor branch from 0c5cd41 to 9291888 Compare September 3, 2026 01:45
@drew
drew marked this pull request as ready for review September 3, 2026 01:46
@drew
drew requested review from a team, derekwaynecarr, mrunalp and sjenning as code owners September 3, 2026 01:46
@drew
drew changed the base branch from codex/1737-rfc12-supervisor-primitives to codex/1737-rfc12-supervisor-modes September 3, 2026 01:46
@drew drew changed the title feat(vm): move supervisor outside guest boundary feat(vm): adopt shared supervisor boundary mode Sep 3, 2026
@drew
drew force-pushed the codex/vm-host-supervisor branch from fd784d6 to 36d8ef7 Compare September 3, 2026 14:34
@drew drew added the test:e2e Requires end-to-end coverage label Sep 3, 2026
@johntmyers

Copy link
Copy Markdown
Collaborator

gator-agent

Maintainer Convergence Decision

Thanks @drew. I checked current head 84f988612b61908e2b517f40cc2b555487162b23: the new delta adds the guest console tail when the host supervisor exits. The bounded critical-only review found no newly introduced Critical defect. This diagnostic improvement does not alter the VM restart authentication path, so one launch-contract obligation remains unresolved and a maintainer decision is still required before this VM layer and its four downstream stack layers can proceed.

Root-cause findings:

  • GATOR-d88b8843-01: the VM StartSandboxRequest handler still discards fresh launch_authentication and reprovisions from the create-time bundle in sandbox.pb; after that session is deactivated, a stopped VM cannot reliably return to Ready. Unresolved and unwaived.
  • GATOR-d88b8843-02: the VM boundary, guest reconciliation, and host supervisor use the persisted image/overlay owner identity. Resolved; its Gator thread remains resolved.

Scope growth:

Reviewer-quality signals:

  • The critical-only reviewer proposed no finding, including no duplicate, resolved/waived, or unchanged-code proposal. Ledger telemetry remains 3 finding-bearing rounds, 2 unique findings, and 16 duplicate finding-ID occurrences across historical dispositions.

Maintainer action: decide whether supported VM stop/start must consume fresh StartSandboxRequest.launch_authentication. If yes, direct @drew to replace persisted launch authentication before reprovisioning and cover session A → stop → session B → successful Ready. If restart is intentionally unsupported for this VM layer, explicitly waive GATOR-d88b8843-01 and record that boundary.

Gator metadata

@johntmyers

Copy link
Copy Markdown
Collaborator

gator-agent

Maintainer Convergence Decision

The bounded critical-only review of current head aa182e569c12aacfe81df3f8003dbe290ec27efe found no newly introduced Critical defect. The latest author delta confirms the isolation boundary before starting network mediation, preserving fail-closed ordering across the shared RFC 0012 supervisor contract used by this VM layer and downstream PRs #2965, #3144, #3230, and #3229. It does not change the VM restart authentication path, so one prior obligation remains unresolved and a maintainer decision is still required.

Root-cause findings:

  • GATOR-d88b8843-01: the VM StartSandboxRequest handler still discards fresh launch_authentication and reprovisions from the create-time bundle in sandbox.pb; after that session is deactivated, a stopped VM cannot reliably return to Ready. Unresolved and unwaived.
  • GATOR-d88b8843-02: the VM boundary, guest reconciliation, and host supervisor use the persisted image/overlay owner identity. Resolved; its Gator thread remains resolved.

Scope growth:

  • None. The current commit changes shared supervisor startup ordering but does not expand the public configuration, protocol surface, or RFC non-goals.

Reviewer-quality signals:

  • The reviewer proposed no finding, including no duplicate, resolved/waived, or unchanged-code proposal. Ledger telemetry remains 3 finding-bearing rounds, 2 unique findings, and 18 duplicate finding-ID occurrences across historical dispositions.

Maintainer action: decide whether supported VM stop/start must consume fresh StartSandboxRequest.launch_authentication. If yes, direct @drew to replace persisted launch authentication before reprovisioning and cover session A → stop → session B → successful Ready. If restart is intentionally unsupported for this VM layer, explicitly waive GATOR-d88b8843-01 and record that boundary.

Gator metadata

@johntmyers

Copy link
Copy Markdown
Collaborator

gator-agent

Maintainer Convergence Decision

The current head a8b780401e7e06273b1b32c4f5515957e344da08 is a force-rebase onto the updated #2942 base. Its author patch ID matches the already-reviewed aa182e569c12aacfe81df3f8003dbe290ec27efe patch, so there is no new effective delta to review. The resolved identity obligation remains fixed, but one launch-contract obligation is unchanged and unwaived, so a maintainer decision remains required before this VM layer and downstream PRs #2965, #3144, #3230, and #3229 can proceed.

Root-cause findings:

  • GATOR-d88b8843-01: the VM StartSandboxRequest handler still discards fresh launch_authentication and reprovisions from the create-time bundle in sandbox.pb; after that session is deactivated, a stopped VM cannot reliably return to Ready. Unresolved and unwaived.
  • GATOR-d88b8843-02: the VM boundary, guest reconciliation, and host supervisor use the persisted image/overlay owner identity. Resolved; its Gator thread remains resolved after the rebase.

Scope growth:

  • None. The effective VM-layer patch is unchanged, and the updated stacked base does not alter the outstanding restart-authentication obligation.

Reviewer-quality signals:

  • No reviewer run was needed for this patch-equivalent rebase. Ledger telemetry remains 3 finding-bearing rounds, 2 unique findings, and 20 duplicate finding-ID occurrences across historical dispositions.

Maintainer action: decide whether supported VM stop/start must consume fresh StartSandboxRequest.launch_authentication. If yes, direct @drew to replace persisted launch authentication before reprovisioning and cover session A → stop → session B → successful Ready. If restart is intentionally unsupported for this VM layer, explicitly waive GATOR-d88b8843-01 and record that boundary.

Gator metadata

@johntmyers

Copy link
Copy Markdown
Collaborator

gator-agent

Maintainer Convergence Decision

Current head 717f28327275987b788c0d86218b780f46a8afbf is another force-rebase onto the updated #2942 base. Its author patch ID still matches the already-reviewed a8b780401e7e06273b1b32c4f5515957e344da08 patch, so there is no new effective VM-layer delta to review. The resolved identity obligation remains fixed, but one launch-contract obligation is unchanged and unwaived, so a maintainer decision remains required before this layer and downstream PRs #2965, #3144, #3230, and #3229 can proceed.

Root-cause findings:

  • GATOR-d88b8843-01: the VM StartSandboxRequest handler still discards fresh launch_authentication and reprovisions from the create-time bundle in sandbox.pb; after that session is deactivated, a stopped VM cannot reliably return to Ready. Unresolved and unwaived.
  • GATOR-d88b8843-02: the VM boundary, guest reconciliation, and host supervisor use the persisted image/overlay owner identity. Resolved; its Gator thread remains resolved after the rebase.

Scope growth:

Reviewer-quality signals:

  • No reviewer run was needed for this patch-equivalent rebase. Ledger telemetry remains 3 finding-bearing rounds, 2 unique findings, and 22 duplicate finding-ID occurrences across historical dispositions.

Maintainer action: decide whether supported VM stop/start must consume fresh StartSandboxRequest.launch_authentication. If yes, direct @drew to replace persisted launch authentication before reprovisioning and cover session A → stop → session B → successful Ready. If restart is intentionally unsupported for this VM layer, explicitly waive GATOR-d88b8843-01 and record that boundary.

Gator metadata

@johntmyers

Copy link
Copy Markdown
Collaborator

gator-agent

Maintainer Convergence Decision

Current head f4deea5c3c475c194af2b4fcdf1d9ec9f48bf216 is another force-rebase onto the updated #2942 base. Its author patch ID still matches the already-reviewed 717f28327275987b788c0d86218b780f46a8afbf patch, so there is no new effective VM-layer delta to review. The resolved identity obligation remains fixed, but one launch-contract obligation is unchanged and unwaived, so a maintainer decision remains required before this layer and downstream PRs #2965, #3144, #3230, and #3229 can proceed.

Root-cause findings:

  • GATOR-d88b8843-01: the VM StartSandboxRequest handler still discards fresh launch_authentication and reprovisions from the create-time bundle in sandbox.pb; after that session is deactivated, a stopped VM cannot reliably return to Ready. Unresolved and unwaived.
  • GATOR-d88b8843-02: the VM boundary, guest reconciliation, and host supervisor use the persisted image/overlay owner identity. Resolved; its Gator thread remains resolved after the rebase.

Scope growth:

Reviewer-quality signals:

  • No reviewer run was needed for this patch-equivalent rebase. Ledger telemetry remains 3 finding-bearing rounds, 2 unique findings, and 24 duplicate finding-ID occurrences across historical dispositions.

Maintainer action: decide whether supported VM stop/start must consume fresh StartSandboxRequest.launch_authentication. If yes, direct @drew to replace persisted launch authentication before reprovisioning and cover session A → stop → session B → successful Ready. If restart is intentionally unsupported for this VM layer, explicitly waive GATOR-d88b8843-01 and record that boundary.

Gator metadata

@johntmyers

Copy link
Copy Markdown
Collaborator

gator-agent

PR Review Status

Thanks @drew. I checked the two new VM generation commits on current head 6b0457f8fbe755e6779fdba34e85c2cf9b17666d against the current #2942 stacked base and the contracts consumed by #2965, #3144, #3230, and #3229. Restart now validates the fresh start bundle, atomically replaces the persisted launch authentication before reprovisioning, and carries a stable start generation through VM boundary material. This resolves the remaining launch-authentication obligation, and the bounded critical-only review found no newly introduced Critical defect.

Blocking findings:

  • No blocking findings remain.

Carried findings:

  • None. GATOR-d88b8843-01 and GATOR-d88b8843-02 are resolved, and both Gator-owned threads are closed.
Gator metadata
  • Validation: Implements the VM driver layer of accepted RFC 0012 / feat: establish the Isolation Backend interface #1737, stacked directly on current feat(isolation): implement the RFC 0012 sandbox architecture #2942 and serving as the base for the remaining four stack layers.
  • Docs: Existing architecture and Fern reference updates cover the VM topology; the latest generation/authentication fix adds no separate direct UX contract.
  • Checks: Current-head Branch Checks, Helm Lint, and Trivy Changes are green; required E2E is running.
  • E2E: test:e2e is applied and current-head Branch E2E run 34814068077 is in progress. No current-head bot instruction requires /ok to test or a rerun.
  • Head SHA: 6b0457f8fbe755e6779fdba34e85c2cf9b17666d
  • Base SHA: 707cf0606bc18a1b38768c571810aaa1da320d2a
  • Merge base SHA: 707cf0606bc18a1b38768c571810aaa1da320d2a
  • Patch ID: f495d2941912d161f3f263fe7d3609c5be66d25c
  • Gator payload: 8
  • Review mode: critical_only
  • Previous reviewed SHA: b1bffcd38d3f4e04d68eeb9acd4d5e4acf9b79cc
  • Review budget exhausted: yes
  • Maintainer decision required: no — all prior findings are resolved, there is no qualifying scope growth, and no new Critical was found.
  • Next state: gator:watch-pipeline

@johntmyers

Copy link
Copy Markdown
Collaborator

gator-agent

PR Review Status

Thanks @drew. I checked the new restored-session rotation commit on current head 0caeda261ed0321a11662ab3fd4e066cf1540352 against the current #2942 stacked base and the shared generation/session contracts consumed by downstream PRs #2965, #3144, #3230, and #3229. The change restarts an already-running restored VM before installing freshly minted launch authentication, and the bounded critical-only review found no newly introduced Critical defect.

Blocking findings:

  • No blocking findings remain.

Carried findings:

  • None. GATOR-d88b8843-01 and GATOR-d88b8843-02 remain resolved, and both Gator-owned threads are closed.
Gator metadata
  • Validation: Implements the VM driver layer of accepted RFC 0012 / feat: establish the Isolation Backend interface #1737, stacked directly on current feat(isolation): implement the RFC 0012 sandbox architecture #2942 and serving as the base for the remaining four stack layers.
  • Docs: Existing architecture and Fern reference updates cover the VM topology; this restored-session rotation delta adds no separate direct UX contract.
  • Checks: Current-head Branch Checks and required E2E are in progress; Helm Lint and Trivy Changes are green.
  • E2E: test:e2e is applied and current-head Branch E2E run 34816518643 is in progress. No current-head bot instruction requires /ok to test or a rerun.
  • Head SHA: 0caeda261ed0321a11662ab3fd4e066cf1540352
  • Base SHA: e882ac017fc1555a29ef267d28f5d1facc947d29
  • Merge base SHA: e882ac017fc1555a29ef267d28f5d1facc947d29
  • Patch ID: 93f3a0de998cd5aa94e91bf2562e90600bd6e138
  • Gator payload: 8
  • Review mode: critical_only
  • Previous reviewed SHA: 6b0457f8fbe755e6779fdba34e85c2cf9b17666d
  • Review budget exhausted: yes
  • Maintainer decision required: no — all prior findings remain resolved, there is no qualifying scope growth, and no new Critical was found.
  • Next state: gator:watch-pipeline

@johntmyers

Copy link
Copy Markdown
Collaborator

gator-agent

PR Review Status

Thanks @drew. I checked the new shared-path extraction on current head 9ab52d2224a04e0b23c93ffdce3e46195936bf65 against the current #2942 stacked base and the contracts consumed by downstream PRs #2965, #3144, #3230, and #3229. The author-only delta centralizes three VM guest paths in openshell-core; the bounded critical-only review found no newly introduced Critical defect, and both prior launch-contract findings remain resolved.

Blocking findings:

  • No blocking findings remain.

Carried findings:

  • None. GATOR-d88b8843-01 and GATOR-d88b8843-02 remain resolved, and their Gator-owned threads remain closed.
Gator metadata
  • Validation: Implements the VM driver layer of accepted RFC 0012 / feat: establish the Isolation Backend interface #1737, stacked directly on current feat(isolation): implement the RFC 0012 sandbox architecture #2942 and serving as the base for the remaining four stack layers.
  • Docs: Existing architecture and Fern reference updates cover the VM topology; this shared-constant extraction adds no separate direct UX contract.
  • Checks: Current-head Branch Checks are in progress and required E2E is queued; Helm Lint and Trivy Changes are green.
  • E2E: test:e2e is applied and current-head Branch E2E run 34863906300 is queued. No current-head E2E Label Help instruction requires /ok to test or a rerun.
  • Head SHA: 9ab52d2224a04e0b23c93ffdce3e46195936bf65
  • Base SHA: 6143f24e2a8269403d1cbca108a722059b4e6b34
  • Merge base SHA: 6143f24e2a8269403d1cbca108a722059b4e6b34
  • Patch ID: b091599985ddea3cecbb545c5bab485a28dc65e9
  • Gator payload: 8
  • Review mode: critical_only
  • Previous reviewed SHA: 0caeda261ed0321a11662ab3fd4e066cf1540352
  • Review budget exhausted: yes
  • Maintainer decision required: no — all prior findings remain resolved, there is no qualifying scope growth, and no new Critical was found.
  • Next state: gator:watch-pipeline

drew added 20 commits September 14, 2026 09:29
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
@johntmyers

Copy link
Copy Markdown
Collaborator

gator-agent

PR Review Status

Thanks @drew. I checked the new session-lineage commit on current head 3be3fe3053291f5c48842d53475f183c92549b06 against the current #2942 stacked base and the contracts consumed by downstream PRs #2965, #3144, #3230, and #3229. The author-only delta binds the VM boundary generation and initial session rotation to the gateway-issued launch lineage; the bounded critical-only review found no newly introduced Critical defect, and both prior launch-contract findings remain resolved.

Blocking findings:

  • No blocking findings remain.

Carried findings:

  • None. GATOR-d88b8843-01 and GATOR-d88b8843-02 remain resolved, and their Gator-owned threads remain closed.
Gator metadata
  • Validation: Implements the VM driver layer of accepted RFC 0012 / feat: establish the Isolation Backend interface #1737, stacked directly on current feat(isolation): implement the RFC 0012 sandbox architecture #2942 and serving as the base for the remaining four stack layers.
  • Docs: Existing architecture and Fern reference updates cover the VM topology; this internal session-lineage delta adds no separate direct UX contract.
  • Checks: Current-head Branch Checks are running; Helm Lint and Trivy Changes are green. Required checks are not yet all green.
  • E2E: test:e2e is applied and current-head Branch E2E run 34869064629 is queued. No current-head E2E Label Help instruction requires /ok to test or a rerun.
  • Head SHA: 3be3fe3053291f5c48842d53475f183c92549b06
  • Base SHA: 0db1fcf68fb61b80288ca75dc0fb7a8526b6bcc5
  • Merge base SHA: 0db1fcf68fb61b80288ca75dc0fb7a8526b6bcc5
  • Patch ID: 2ecb7c83c7849b69b5614f3e9019c8ea7a572059
  • Gator payload: 8
  • Review mode: critical_only
  • Previous reviewed SHA: 9ab52d2224a04e0b23c93ffdce3e46195936bf65
  • Review budget exhausted: yes
  • Maintainer decision required: no — all prior findings remain resolved, there is no qualifying scope growth, and no new Critical was found.
  • Next state: gator:watch-pipeline

@johntmyers

Copy link
Copy Markdown
Collaborator

gator-agent

Monitoring Complete

Monitoring is complete because this PR has merged.

Final status: the VM driver layer was reviewed incrementally against its current #2942 stacked base with the downstream RFC 0012 layers in view. The prior launch-contract findings were resolved, required testing completed, and the PR reached maintainer handoff before merge.

I removed the active gator:* label because there is nothing left for gator to monitor on this PR.

Gator metadata
  • Head SHA: 3be3fe3053291f5c48842d53475f183c92549b06
  • Gator payload: 8
  • Previous state: gator:approval-needed
  • Final state: merged

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

test:e2e Requires end-to-end coverage

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants