Skip to content

feat(onboard): preserve Jetson GPU device groups - #8910

Draft
cjagwani wants to merge 5 commits into
mainfrom
codex/jetson-gpu-followup-7610
Draft

feat(onboard): preserve Jetson GPU device groups#8910
cjagwani wants to merge 5 commits into
mainfrom
codex/jetson-gpu-followup-7610

Conversation

@cjagwani

@cjagwani cjagwani commented Aug 12, 2026

Copy link
Copy Markdown
Collaborator

Summary

This draft preserves Jetson GPU policy, device-group, container-lifecycle, and validation changes after #8875 merged the CPU-only E2E path. Issue #7610 still blocks the non-root OpenShell CUDA acceptance test and the product-scope decision. Maintainers must keep this PR as a draft until those conditions are resolved.

Related Issue

Related to #7610. This PR does not resolve or close that issue.

Changes

  • Detect existing, non-symbolic-link Jetson GPU character devices before adding filesystem policy entries.
  • Add read-only access to injected NVIDIA libraries and read-write access to detected Jetson GPU devices.
  • Preserve detected device-group IDs during compatibility and managed container recreation.
  • Add a root-owned bootstrap helper that validates group IDs, updates the sandbox account, verifies memberships, and starts only the OpenShell supervisor.
  • Add unit, integration, image-layout, workflow, and source-watch coverage for the new behavior.
  • Document the proposed controls and the CUDA claim that they do not establish.

Draft Exit Conditions

Maintainers must keep this PR as a draft until all of these conditions are true:

  1. Maintainers accept the Jetson GPU product scope and define ownership, lifecycle, compatibility, security, and validation requirements.
  2. Issue [Jetson][Sandbox] Sandbox GPU passthrough proof fails for the non-root sandbox user on JetPack 6.2 IGX Orin — onboarding aborts #7610 no longer blocks the non-root OpenShell CUDA acceptance test.
  3. A Jetson hardware run verifies successful cuInit(0) through the supported OpenShell sandbox path.
  4. Documentation review, sensitive-path review, and applicable GitHub checks pass for the commit under review.

Type of Change

  • Code change (feature, bug fix, or refactor)
  • Code change with doc updates
  • Doc only (prose changes, no code sample modifications)
  • Doc only (includes code sample changes)

Quality Gates

  • Tests added or updated for changed behavior
  • Existing tests cover changed behavior — justification:
  • Tests not applicable — justification:
  • Docs updated for user-facing behavior changes
  • Docs not applicable — justification:
  • Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
  • Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: Required before this draft can leave draft status.
  • Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

  • Documentation writer subagent reviewed the completed changes
  • Result: blocked
  • Evidence: docs/reference/troubleshooting.mdx, test/e2e/README.md, and test/e2e/docs/README.md. The changed documentation passes writing, terminology, claim-accuracy, and agent-variant review. The managed-bootstrap conflict resolution preserves the bounded supervisor reconnect timeout and the exact Jetson helper command boundary. Maintainer product-scope acceptance and IGX Orin OpenShell cuInit(0)=0 evidence remain required.
  • Agent: Codex Desktop

DGX Station Hardware Evidence

  • Tested on DGX Station
  • Tested commit:
  • Station profile/scenario:
  • Result:
  • Supporting evidence:

Verification

  • PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
  • Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run validate:pr passed after refreshing origin/main when hooks were skipped or unavailable
  • Targeted behavior tests pass for the current change set, or tests are marked not applicable above — 180 tests passed and 2 tests skipped across 14 affected test files.
  • Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — deferred while issue [Jetson][Sandbox] Sandbox GPU passthrough proof fails for the non-root sandbox user on JetPack 6.2 IGX Orin — onboarding aborts #7610 blocks the acceptance contract.
  • Quality Gates section completed with required justifications or waivers
  • No secrets, API keys, or credentials committed
  • npm run docs builds without warnings (doc changes only) — build passed with 0 errors and 2 existing Fern warnings.
  • Doc pages follow the style guide (doc changes only)
  • New doc pages include SPDX header and frontmatter (new pages only) — no new documentation pages.

Signed-off-by: Charan Jagwani cjagwani@nvidia.com
Signed-off-by: San Dang sdang@nvidia.com

Carry the deferred Jetson GPU policy, bootstrap, lifecycle, and validation work in a stacked draft.

The OpenShell execution boundary tracked by #7610 remains unresolved.

Co-authored-by: San Dang <sdang@nvidia.com>

Signed-off-by: Charan Jagwani <cjagwani@nvidia.com>

Signed-off-by: San Dang <sdang@nvidia.com>
@cjagwani cjagwani self-assigned this Aug 12, 2026
@copy-pr-bot

copy-pr-bot Bot commented Aug 12, 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.

@coderabbitai

coderabbitai Bot commented Aug 12, 2026

Copy link
Copy Markdown
Contributor

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: d4f2ac79-1ec1-459b-aa96-a6fb47b991df

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review

Comment @coderabbitai help to get the list of available commands.

@github-actions

Copy link
Copy Markdown
Contributor

@github-code-quality

github-code-quality Bot commented Aug 12, 2026

Copy link
Copy Markdown
Contributor

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit fff5a76 in the codex/jetson-gpu-fol... branch remains at 96%, unchanged from commit 2677154 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit fff5a76 in the codex/jetson-gpu-fol... branch remains at 82%, unchanged from commit 0810a95 in the main branch.

Show a code coverage summary of the most impacted files.
File main 0810a95 codex/jetson-gpu-fol... fff5a76 +/-
src/lib/policy/...ne-exclusion.ts 97% 91% -6%
src/lib/onboard...eway-service.ts 83% 83% 0%
src/lib/onboard...strap/docker.ts 64% 65% +1%
src/lib/state/registry.ts 87% 89% +2%
src/lib/onboard...tch-recreate.ts 93% 95% +2%
src/lib/onboard...-transaction.ts 92% 94% +2%
src/lib/platform.ts 95% 97% +2%
src/lib/securit...ate-endpoint.ts 94% 97% +3%
src/lib/actions...e-classifier.ts 69% 75% +6%
src/lib/state/registry/lock.ts 39% 48% +9%

Updated August 13, 2026 22:42 UTC

@github-actions

github-actions Bot commented Aug 12, 2026

Copy link
Copy Markdown
Contributor

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

Model lanes

  • GPT-5.6 Terra (primary): Completed · medium confidence · 0 blockers · 0 warnings · 0 suggestions
  • Nemotron 3 Ultra (second opinion): Completed · medium confidence · 0 blockers · 2 warnings · 0 suggestions
  • Model comparison: normalized findings differ; normalized terminology decisions differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 2 more warnings, the same number of suggestions.
5 terminology differences from the second opinion

Advisory only. These are normalized differences from the primary terminology receipt.

  • native route at docs/reference/troubleshooting.mdx:3015: selected only by the second-opinion lane as established.
  • device group at scripts/jetson-device-group-bootstrap.sh:16: selected only by the second-opinion lane as established.
  • Jetson compatibility path at docs/reference/troubleshooting.mdx:3030: selected only by the second-opinion lane as define.
  • sandbox-user handoff at scripts/jetson-device-group-bootstrap.sh:6: selected only by the second-opinion lane as define.
  • Jetson device-group bootstrap at scripts/jetson-device-group-bootstrap.sh:11: selected only by the second-opinion lane as define.
3 additional E2E selections from the second opinion

Advisory only. The primary lane did not select these E2E jobs or targets.

  • gpu-e2e: The completed second-opinion lane identified E2E coverage that the primary lane omitted.
  • ubuntu-repo-cloud-openclaw: The completed second-opinion lane identified E2E coverage that the primary lane omitted.
  • openclaw-inference-switch: The completed second-opinion lane identified E2E coverage that the primary lane omitted.

Second-opinion terminology and E2E selections are advisory. Live E2E does not run automatically for pull requests.

3 semantic terminology decisions

Terminology decisions are advisory. They affect the assessment only when a separate finding identifies concrete semantic impact.

  • established — device-group preservation at src/lib/onboard/managed-bootstrap/docker.ts:668: Keep device-group preservation for the supplementary-membership behavior.
  • established — managed-bootstrap replacement at docs/reference/troubleshooting.mdx:3015: Keep managed-bootstrap replacement for the transactional native-route replacement.
  • define — Jetson GPU device paths at src/lib/onboard/docker-gpu-jetson-groups.ts:61: Keep the term with the existing /dev/nvmap-anchor definition in the code comment.

E2E guidance

Advisory only. A maintainer can dispatch the default E2E suite for the commit under review.

Recommended E2E: managed-image-protected-runtime

Manual-only E2E: cloud-onboard, managed-image-multiarch-startup, onboard-repair, onboard-resume, ubuntu-repo-docker-post-reboot-recovery, full-e2e
The manual PR workflow does not run these selectors for the commit under review. Run them from reviewed code on main.

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

@wscurran wscurran added area: onboarding Onboarding FSM, provider setup, sandbox launch, or first-run flow area: sandbox OpenShell sandbox lifecycle, runtime, config, or recovery feature PR adds or expands user-visible functionality platform: jetson Affects Jetson AGX Thor or Orin labels Aug 13, 2026

@prekshivyas prekshivyas left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed exact draft head fff5a76.

The proposed implementation is appropriately fail-closed for its draft purpose: it derives supplementary groups only from existing non-symlink Jetson character devices, validates numeric group IDs, keeps the helper root-owned, limits the root action to group setup plus the OpenShell supervisor handoff, and adds focused policy/recreation/bootstrap tests. The documentation correctly avoids claiming CUDA success.

This cannot be approved or leave draft state. The repository product-scope gate is still unmet, #7610 remains open, and the only reproduced IGX Orin result is that non-root cuInit(0) fails even with the existing groups. The PR therefore has no evidence that these broader preserved groups establish the supported sandbox-user CUDA contract. GitHub also reports the branch CONFLICTING/DIRTY against current main, and the documentation review is explicitly blocked. Resolve the product decision first, reconcile with current main, then obtain exact-head Jetson hardware evidence through the supported OpenShell path proving cuInit(0)=0, lifecycle/recreation behavior, and the least-privilege device/group set; rerun docs and sensitive-path review afterward.

Security review:

  • Input validation: PASS — device paths, symlink state, character-device type, and numeric group IDs are bounded and validated.
  • Authentication and authorization: WARNING — supplementary group membership expands device authority and still lacks accepted least-privilege hardware proof.
  • Secrets and sensitive data: PASS — no credentials or sensitive payloads are introduced.
  • Injection risks: PASS — group identifiers are numeric and the root helper does not evaluate caller-supplied shell fragments.
  • Data exposure and privacy: PASS — no new data egress or logging surface.
  • Cryptography: PASS — no cryptographic behavior changes.
  • Dependencies and supply chain: PASS — no dependency or artifact-source changes.
  • System security: FAIL for approval — the core non-root CUDA security/compatibility postcondition remains unproven and product ownership is undefined.
  • Testing and verification: FAIL for approval — #7610 is unresolved, exact-head Jetson hardware evidence is absent, docs review is blocked, and the branch conflicts with current main.

Files reviewed: all 40 changed Jetson device/group policy, clone/recreate/create, startup/bootstrap, managed-runtime, Dockerfile/build-context, workflow, documentation, and test files; linked issue #7610 and automated review evidence.

@github-actions github-actions Bot added v0.0.110 Release target and removed v0.0.109 labels Aug 14, 2026

@prekshivyas prekshivyas left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed commit fff5a76e22c1c3c57731a82c09d9a2bd7155a0eb as a security-critical Jetson policy and root-helper change.

I did not find an additional correctness or security defect in the current diff. The helper validates the complete bounded GID set before mutation, requires root, accepts only the fixed OpenShell supervisor handoff, verifies the resulting membership, and fails closed. The policy path is anchored on a real non-symlink /dev/nvmap character device and grants only the enumerated device paths.

Security review: secrets PASS; input validation PASS; authentication/authorization PASS; dependencies PASS; error handling PASS; cryptography N/A; configuration/environment PASS; security tests PASS for the implemented boundary; system security BLOCKED for merge.

This is not an approval. The PR is correctly still draft and currently conflicts with the base branch. Its stated merge gates remain material: maintainer product-scope acceptance, resolution of #7610, real supported-path Jetson evidence showing cuInit(0), and completion of the sensitive-path/broad verification gates.

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

Labels

area: onboarding Onboarding FSM, provider setup, sandbox launch, or first-run flow area: sandbox OpenShell sandbox lifecycle, runtime, config, or recovery feature PR adds or expands user-visible functionality platform: jetson Affects Jetson AGX Thor or Orin v0.0.110 Release target

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants