NVIDIA / NVIDIA/NemoClaw

[Epic] Prepare NemoClaw ownership boundaries for OpenShell 0.1.0

Open
#11,944 0 comments 0 reactions 1 assignee Claimed by @rsliter View on GitHub
area: architecture area: sandbox enhancement needs: triage platform: container
Dominant language
TypeScript
Stars
22.5k
Forks
3.1k
Avg merge
1d 1h
Merged PRs (30d)
715

Description

## Problem Statement

OpenShell 0.1.0 changes the ownership boundary between the sandbox supervisor and the agent workload. NemoClaw currently reaches into OpenShell-managed sandboxes for some lifecycle, recovery, privileged repair, and GPU operations.

This creates two risks for the upgrade:

- NemoClaw and OpenShell can both mutate the same runtime state.
- The final upgrade can mix architectural changes with API and packaging changes.

NemoClaw should move work to existing OpenShell and native-agent owners before the release where current contracts support that move. The remaining upgrade should use the final 0.1.0 contracts and delete obsolete reach-in.

This workstream is separate from #9802. That epic owns how NemoClaw calls public OpenShell capabilities. This issue owns the product and runtime ownership changes required by OpenShell 0.1.0.

## Product Decision and Outcome

**Decision: Accept.**

- **Reason:** make OpenShell the mutation authority for OpenShell-managed sandbox infrastructure and reduce the 0.1.0 upgrade to final contract adoption.
- **Placement:** core NemoClaw onboarding, sandbox lifecycle, recovery, and GPU integration.
- **Accountable maintainer:** @rsliter.
- **Validation:** preserve current user workflows and the repository-defined platform matrix before the release. Validate the final integration against one matching OpenShell 0.1.0 release bundle.

The ownership model is:

- OpenShell owns sandbox lifecycle, containment, infrastructure state, GPU attachment, and the supervisor outside the agent workload.
- The native agent owns its configuration and background processes.
- NemoClaw selects supported inputs, evaluates health, requests supported operations, and reports the result.
- NemoClaw retains privileged host operations only for host setup, image construction, and exact-target cleanup.

## Desired Behavior

Before OpenShell 0.1.0:

- Standard Docker and native Podman sandboxes use OpenShell lifecycle operations.
- NemoClaw preserves its current health outcomes behind one agent-lifecycle request path.
- Code touched by this work does not add privileged repair of OpenShell-owned or image-owned state.
- User workflows and supported platforms do not change.
- GPU behavior does not change.

After OpenShell 0.1.0:

- NemoClaw binds the lifecycle request path to the final OpenShell process and sandbox contracts.
- NemoClaw removes direct PID signaling, root-based agent repair, runtime restart, and GPU workload patching that OpenShell replaces.
- NemoClaw preserves its current health definition unless the released OpenShell contract requires a reviewed change.

## Scope and Exclusions

### Included

- Depend on #11905 and PR #11909 for the standard Docker and native Podman sandbox-lifecycle handoff.
- Route agent restart requests through one existing or minimal internal owner while preserving current behavior.
- Keep health evaluation separate from lifecycle mutation.
- Run known agent-owned writes as the sandbox user in code changed by this work.
- Adopt the final OpenShell process, lifecycle, and GPU contracts after the release.
- Delete superseded PID, root-repair, runtime-mutation, and GPU-patching paths after parity is proven.
- Preserve the complete repository-defined platform matrix.

### Excluded

- CLI, SDK, or gRPC transport migration owned by #9802.
- A repository-wide file ownership or permission inventory.
- Broad removal work already owned by #11763 or #11764.
- A new service manager, health model, lifecycle framework, compatibility mode, or retry controller.
- Changes to agent configuration workflows.
- Automated migration for pre-0.1.0 beta sandboxes.
- GPU implementation before a matching OpenShell 0.1.0 contract is available.
- New platforms, agents, providers, or support commitments.

## Related Work and Delivery Constraints

- #11255 establishes the accepted OpenShell and native-agent ownership direction.
- #11905 and PR #11909 own removal of NemoClaw-managed standard Docker and Podman lifecycle orchestration. This issue does not duplicate that implementation.
- PR #11792 returned gateway and background-process lifecycle to native agents. Do not rebuild the removed supervisor or authorization layer.
- #11763 and #11764 own broader restriction and configuration-ownership cleanup. Apply their boundary only to code touched here.
- #9802 may supply typed public-operation adapters. This issue may reuse them but does not depend on completion of that epic.
- NVIDIA/OpenShell#2942 describes the planned 0.1.0 architecture. Final implementation must use the released migration guide and matching release contracts.

## Current State and Decisions

Current `main` still routes status, connect, onboarding finalization, rebuild, inference changes, configuration changes, and MCP flows through shared process-recovery and gateway-restart owners. Those owners combine health observation, native agent restart, recovery, and command execution.

The change belongs to the agent-health and lifecycle-mutation operation. Its failure classes are wrong target, stale identity, command failure, transport ambiguity, failed health verification, and unsupported operation.

Sibling paths checked:

- onboarding finalization;
- status and connect recovery;
- configuration and inference restart;
- restore and rebuild recovery;
- MCP-triggered restart;
- standard Docker, native Podman, and Portable lifecycle.

Portable remains a separate retained path. Ordinary sandbox command transport remains owned by #9802 and #11263.

## Implementation Plan

### Slice 1: Preserve current behavior behind one lifecycle request boundary

**Outcome:** NemoClaw has one internal path for a decision to restart or recover an agent. Callers no longer choose the mutation mechanism.

Before OpenShell 0.1.0:

- Complete #11905 through PR #11909.
- Select the current lifecycle owner to extend. Do not add a parallel framework.
- Route only lifecycle requests through that owner. Do not migrate every sandbox command.
- Preserve the current health probes, `nemoclaw-start`, native agent restart commands, exit codes, and user-visible workflows.
- Keep existing PID or privileged recovery only where current OpenShell cannot replace it.
- In touched paths, run agent-owned configuration and startup writes as the sandbox user.

Acceptance evidence:

- A healthy agent causes no mutation.
- A safe non-root repair preserves current behavior.
- A restart-required result makes one lifecycle request through the selected owner.
- Failed or inconclusive restart reports failure and does not claim health.
- No standard Docker or native Podman path performs direct lifecycle mutation after PR #11909.

### Slice 2: Adopt the released OpenShell process boundary

**Outcome:** OpenShell performs the requested lifecycle operation. NemoClaw evaluates health and reports the result.

After OpenShell 0.1.0:

- Bind the lifecycle request boundary to the final released OpenShell operations.
- Remove direct PID inspection and signaling used for agent recovery.
- Remove root-based repair of OpenShell security state, NemoClaw host-control state, trusted startup code, and image-owned security files.
- Preserve agent-owned configuration changes and current NemoClaw health decisions.
- Do not retry an ambiguous mutation through another transport.

Acceptance evidence:

- OpenShell receives the authorized request for the selected sandbox.
- Wrong or stale sandbox identity causes no mutation.
- An ambiguous result triggers observation, not a second mutation.
- Failed health verification remains a failure after a successful lifecycle response.
- Removed direct recovery paths have no production consumers.

### Slice 3: Adopt OpenShell GPU ownership

**Outcome:** NemoClaw requests GPU access through OpenShell and no longer patches an OpenShell-managed workload to attach GPUs.

Before OpenShell 0.1.0: do nothing.

After OpenShell 0.1.0:

- Use the released GPU request and observation contract.
- Remove workload cloning, patching, or replacement used only for GPU attachment.
- Preserve the repository-defined GPU platform matrix.

Acceptance evidence:

- Supported GPU requests succeed through OpenShell.
- Unsupported or unavailable GPU requests fail without direct workload mutation.
- CPU-only behavior remains unchanged.
- Existing platform qualification passes against the matching release bundle.

## Security and Failure Boundaries

- OpenShell remains authoritative for sandbox identity, containment, lifecycle, and GPU attachment.
- Native agents remain authoritative for their configuration and background processes.
- NemoClaw must verify the selected sandbox before it requests a mutation.
- A same-name resource does not establish ownership.
- A timeout or transport failure can hide a completed mutation. NemoClaw must observe current state before another mutation.
- A failed or inconclusive health check must not become success.
- Credential location, access, lifetime, projection, and removal remain unchanged. Credentials stay in the existing OpenShell-owned boundary and remain absent from logs, arguments, artifacts, and model-visible output.
- Cleanup remains limited to a resource with proven identity.

## Validation Plan

Use existing test owners. Do not create a second lifecycle or platform matrix.

- Extend focused unit and integration tests for healthy, safe-repair, restart-required, failed, and ambiguous outcomes.
- Preserve negative tests for wrong identity, stale state, duplicate mutation, privilege escalation, and credential disclosure.
- Run existing standard Docker, native Podman, and Portable qualification for lifecycle changes.
- Run existing CPU and GPU qualification after the released GPU contract is adopted.
- Validate final 0.1.0 behavior with a matching CLI, SDK, gateway, and image bundle.
- Record each deleted recovery or GPU workaround and prove that it has no remaining production consumer.

## Compatibility Requirements

- Preserve all repository-declared supported agents, operating systems, architectures, container profiles, and GPU variants.
- Preserve standard Docker, qualified native Podman, and Portable behavior.
- Preserve current commands, exit codes, machine-readable output, and agent configuration workflows before 0.1.0.
- Do not combine mismatched OpenShell prerelease components for release evidence.

## Delivery Order

1. Land PR #11909 and its matching Docker, Podman, and Portable evidence.
2. Deliver Slice 1 as one narrow follow-on unless PR #11909 already provides the required boundary.
3. Stop pre-release implementation. Do not start the GPU or final process migration against an unreleased contract.
4. Deliver Slice 2 against the released OpenShell process and lifecycle contract.
5. Deliver Slice 3 against the released OpenShell GPU contract.

## Stop Conditions

- Stop if OpenShell lacks a required public operation. Record the upstream gap instead of adding reach-in.
- Stop if the change requires a new service manager, health definition, compatibility mode, or platform decision.
- Stop if parity requires changing a user workflow or narrowing the platform matrix.
- Stop release qualification if the CLI, SDK, gateway, or image comes from a different OpenShell release bundle.

## Ongoing Ownership

@rsliter owns workstream coordination and the final scope decisions. Existing component maintainers own implementation in their current source areas. PR #11909 remains owned by its current assignee.

## Placement and Support Expectations

Placement: core NemoClaw.

This work changes internal ownership. It does not add support or intentionally change successful user behavior. NemoClaw remains beta, and this issue does not add automated migration guarantees for older sandboxes.

## Category

Platform

## Checklist

- [x] I searched existing issues and found no duplicate OpenShell 0.1.0 ownership workstream.
- [x] I described the problem and desired behavior.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.