[Epic] Complete pre-work for the OpenShell 0.1.2 upgrade #12558

Problem

NemoClaw currently sends inference traffic through OpenShell's workspace-wide inference.local route. OpenShell 0.1.x removes that route. Sandboxes must instead attach providers and call their native endpoints.

The upgrade also requires explicit provider-profile imports and image references in place of Dockerfile paths at openshell sandbox create --from. NemoClaw can prepare these behaviors on its current OpenShell pin before combining them with SDK, gateway-schema, artifact, and packaging changes. The selected upgrade release may be newer than 0.1.2; its exact tag and dependency update are separate work.

Product decision and outcome

Decision: Accept.

• Reason: Move inference to native provider access before the selected OpenShell upgrade combines it with dependency and runtime changes.
• Placement: Core NemoClaw onboarding, inference selection, provider integration, agent configuration, health, and model compatibility.
• Accountable maintainer: @rsliter.
• Validation: Preserve current user commands and the repository-defined provider, agent, and platform matrix for the completed epic. Host-local delivery is tracked per agent below. Retained OpenClaw, Pi, Hermes, and Local NIM selections remain available on their current routes until their own accepted native slices are qualified. Prove each native provider class through existing test owners.

The ownership model is:

• NemoClaw defines its supported provider profiles, endpoints, model configuration, and safe defaults.
• OpenShell stores credentials, attaches providers to sandboxes, and enforces endpoint and executable restrictions.
• Each sandbox receives only its selected provider access.
• Each agent calls the provider's native endpoint and owns the model, request format, and timeout.

NemoClaw will not recreate OpenShell's retired workspace-wide inference route.

This decision governs the native-inference slices below. #12940 checks the existing provider-profile ownership contract against the import-only catalog. #12942 records its own Accept decision for the local Dockerfile-to-image build handoff. Neither child authorizes the OpenShell pin change.

Desired behavior

• Existing NemoClaw onboarding and inference-selection commands remain unchanged.
• NemoClaw installs and maintains only its own provider profiles.
• NemoClaw attaches the selected provider to the selected sandbox.
• Agent configuration uses the provider's native endpoint.
• Status and health checks test the same native path that the agent uses.
• Credential values remain inside OpenShell's credential boundary.
• A failed native path does not silently fall back to inference.local.
• Supported provider paths import and verify their NemoClaw-owned profiles before provider creation or attachment.
• Generated Dockerfile paths build an image with the selected local Docker or Podman gateway engine, then pass its reference to OpenShell. The user-supplied Dockerfile path follows Build Dockerfile sources into images before OpenShell sandbox creation #12942's scope gate: support the same flow if it stays simple, or deprecate it. Report build and creation failures, and report success only after readiness.

Scope

Included

• Add NemoClaw-owned, workspace-scoped profiles for current supported providers.
• Create or reuse NemoClaw-owned provider instances without exposing credential values.
• Attach providers to the selected sandbox and wait for applied state where required.
• Configure each current agent with the native endpoint, model, API format, and timeout.
• Preserve required model-specific compatibility outside the retired hostname contract.
• Replace route-specific health, status, repair, DNS, and policy behavior.
• Remove managed-route dependencies after every supported provider selection has a native path.
• Audit and close import-only provider-profile gaps through Verify provider profile imports for the OpenShell upgrade #12940.
• Build generated Dockerfile sources into images for local gateways through Build Dockerfile sources into images before OpenShell sandbox creation #12942. Attempt the same for user-supplied Dockerfiles within that issue's scope gate, with clear phase and failure messages.

Excluded

• Updating the OpenShell CLI, SDK, gateway, image, supervisor, or driver pin.
• SDK request changes or gateway schema changes for the selected OpenShell release.
• GPU ownership changes, lifecycle fallback removal, or legacy sandbox handling beyond Build Dockerfile sources into images before OpenShell sandbox creation #12942's Dockerfile build handoff.
• New providers, agents, platforms, models, or support commitments beyond Build Dockerfile sources into images before OpenShell sandbox creation #12942's scoped local Docker/Podman Dockerfile work.
• A generic provider-profile editor, routing framework, or compatibility layer.
• Automatic fallback between native and managed inference.
• Automated migration for existing beta sandboxes.
• Remote-gateway image publication or registry support.
• A new E2E framework or a second platform matrix.
• The gateway info transport cleanup owned by Isolate the OpenShell integration and migrate eligible CLI operations to the SDK or gRPC #9802.

Profile and security rules

• Use NemoClaw-specific profile IDs. Do not overwrite a built-in or user-owned profile.
• Scope profiles to the NemoClaw workspace unless an accepted follow-up requires wider scope.
• Treat a conflicting profile ID or ownership mismatch as an error.
• Restrict each profile to required endpoints and executable paths.
• Keep existing URL and SSRF validation for user-supplied endpoints.
• Never put credential values in command arguments, logs, state, artifacts, or model-visible output.
• After an ambiguous create or attach result, observe OpenShell state before another mutation.
• Detach or delete only resources with proven NemoClaw ownership and sandbox identity.

OpenShell stores credentials for the provider lifetime. The sandbox receives opaque placeholders. OpenShell removes access when NemoClaw detaches the provider or deletes the owned sandbox or provider.

Capability slices

Slice 1: Use native NVIDIA hosted inference

Implementation PR: #12562 (merged).

Outcome: Fresh sandboxes that use the default NVIDIA hosted provider call its native endpoint without inference.local.

• Add the minimum profile ensure, provider ensure, attachment, and observation behavior.
• Configure each supported agent for the native NVIDIA endpoint.
• Move onboarding, inference selection, status, and health for this provider to the native path.
• Prove profile collision denial and credential redaction.

Do not create a standalone provider framework. Later slices may extend only the mechanism this outcome requires.

Slice 2: Move remaining fixed hosted providers

Outcome: Every current provider with a fixed public endpoint uses native provider access.

• Map each current fixed hosted selection to one NemoClaw-owned profile.
• Preserve current OpenAI-compatible, Anthropic, Gemini, and other existing protocol behavior.
• Preserve model-specific compatibility only where the native provider requires it.
• Test each distinct protocol and credential shape. Do not test every provider on every platform in this slice.

This slice depends only on Slice 1's minimum mechanism.

Slice 3: Move user-supplied hosted endpoints

Outcome: Existing compatible-endpoint workflows create an endpoint-specific profile and use the native endpoint.

• Validate the endpoint before profile creation.
• Bind credentials only to the validated endpoint and API surface.
• Never repoint a public vendor profile to another host.
• Fail without partial activation for malformed endpoints, profile collisions, or unsupported protocols.

This slice depends on Slice 1. It does not depend on Slice 2.

Slice 4: Move host-local providers

Deliver the existing agent-specific work while preserving every unmigrated selection. #12975 owns the accepted outcome. See the current delivery and OpenClaw plan.

Local NVIDIA NIM retains its shared route under #13116; #13220 preserves that boundary for DCode. Do not infer native NIM approval from standalone vLLM support.

• Use the existing qualified host address and least-privilege authenticated or credentialless profile.
• Prove the actual agent's selected endpoint/model, scoped authentication, sibling denial, restart/rebuild, status, and owned cleanup.
• Preserve current runtime startup and GPU ownership.
• Fail visibly on a failed native operation. Do not fall back to the shared route.
• Keep manual backup and fresh recreation for legacy states that cannot safely resume or rebuild. Do not add automatic migration.

Earlier combined PRs #12777 and #12977 are closed without merge. Use merged main as the base; retain those PRs as historical references. Documentation catch-up is tracked in #13308.

This slice depends on Slice 1 and can proceed alongside hosted-provider work. A merged implementation is not a claim of completed runtime qualification.

Slice 5: Retire the managed inference route

Outcome: NemoClaw no longer calls OpenShell managed-inference commands or depends on inference.local.

• Remove production calls to openshell inference get and openshell inference set.
• Remove obsolete route-specific DNS, policy, health, repair, and compatibility code.
• Update current guidance without changing NemoClaw's user-facing commands.
• Disable the old route on the current OpenShell release and run existing inference qualification.

Do not start this slice until every current provider selection has a working native path. #12921 remains a dependency of Slice 5 and the pre-upgrade full-agent parity outcome. Completing the DCode or OpenClaw slice alone does not satisfy that dependency.

Other upgrade-readiness tracks

• #12940: Verify provider profile imports. Inventory supported profile IDs and import points. Verify import-before-use, repeat setup, and collision refusal. Check one representative path on the selected target release after the inference slices add their profiles.
• #12942: Build Dockerfile sources into images. Preserve generated Dockerfile workflows on local Docker and Podman gateways. Attempt the same for user-supplied Dockerfiles; deprecate that option if support needs broad edge-case handling or new recovery logic. Use the gateway's engine, pass an image reference to OpenShell, and report build and creation results. Remote gateways without image distribution fail before building.

These tracks may proceed alongside the inference slices. Each child issue owns its detailed acceptance and validation. The OpenShell pin, gateway schema, SDK, and other selected-release changes remain in the separate dependency update.

Acceptance evidence

• A supported selection installs or reuses the NemoClaw-owned profile and provider.
• OpenShell attaches that provider only to the selected sandbox.
• A fresh agent process completes a native request with the selected model.
• Status and health assess the endpoint used by the agent.
• A user-owned profile collision causes no mutation.
• A rejected endpoint creates no profile or provider.
• Credential values remain absent from arguments, logs, state, artifacts, and model-visible output.
• An ambiguous mutation triggers observation instead of a second mutation.
• A failed native request does not become success or trigger managed-route fallback.
• Production code has no managed-route command or hostname dependency after Slice 5.
• The existing repository-defined platform matrix passes on the current OpenShell pin.
• Verify provider profile imports for the OpenShell upgrade #12940 proves profile import ordering, repeat setup, collision refusal, and a representative selected-release smoke run.
• Build Dockerfile sources into images before OpenShell sandbox creation #12942 proves that generated and any supported user-supplied Dockerfile paths pass an image reference, report build failures before sandbox creation, and report success only after readiness. If the user-supplied path exceeds its scope gate, Build Dockerfile sources into images before OpenShell sandbox creation #12942 proves its deprecation warning and early rejection. A remote gateway without image distribution fails before build.

Related work

• Isolate the OpenShell integration and migrate eligible CLI operations to the SDK or gRPC #9802 owns migration away from unstable OpenShell CLI interfaces. Its structured gateway-discovery slice may proceed in parallel.
• [Epic] Prepare NemoClaw ownership boundaries for OpenShell 0.1.0 #11944 established the OpenShell and native-agent ownership boundary. It does not own this inference migration.
• PR refactor(lifecycle): retire NemoClaw-owned container orchestration #11909 moved standard Docker and native Podman lifecycle to OpenShell.
• PR refactor(lifecycle): return gateway ownership to native agents #11792 returned gateway and background-process lifecycle to native agents.
• [DGX Spark][Onboard] onboard --from accepts a Dockerfile path for OpenClaw but refuses the same path for Hermes and Deep Agents Code #11888 records agent-dependent custom-Dockerfile admission; Build Dockerfile sources into images before OpenShell sandbox creation #12942 retains its input-validation boundary.
• [Ubuntu 26.04][Onboard] --fresh cannot reclaim a pre-create route reservation after a custom image build failure #11415 separately owns the retry failure after a pre-create image build failure. Build Dockerfile sources into images before OpenShell sandbox creation #12942 reports the failed phase and stops; it does not add retry or reservation recovery behavior.

Delivery order

1. Deliver Slice 1 as the minimum vertical path.
2. Deliver Slices 2, 3, and 4 in parallel.
3. Confirm that every current provider selection belongs to one completed slice.
4. Deliver Slice 5 and prove that the old route can be disabled.
5. Complete Build Dockerfile sources into images before OpenShell sandbox creation #12942 alongside the inference slices. Complete Verify provider profile imports for the OpenShell upgrade #12940's inventory after the provider paths it audits exist.
6. Select the target OpenShell release. Run the target-release checks required by Verify provider profile imports for the OpenShell upgrade #12940 and Build Dockerfile sources into images before OpenShell sandbox creation #12942 before changing the pin.
7. Hand the exact target binary, schema, and remaining dependency changes to a separate update issue, then stop this pre-work epic.

Stop conditions

• Stop if current OpenShell cannot attach a provider without weakening credential protection.
• Stop if a profile requires wildcard endpoint or executable access.
• Stop if a slice requires a new provider, agent, platform, migration guarantee, or user workflow.
• Stop if compatibility requires automatic fallback between native and managed routes.
• Stop if a pre-work change requires the selected OpenShell release's SDK or gateway schema.
• Stop route retirement until every current provider selection passes native-path evidence.
• Stop extending Build Dockerfile sources into images before OpenShell sandbox creation #12942's user-supplied Dockerfile path if it needs broader build access, changed context or credential boundaries, remote image publication, multiple agent or runtime exceptions, or new recovery protocols. Deprecate that path under Build Dockerfile sources into images before OpenShell sandbox creation #12942's scope gate while keeping generated-Dockerfile onboarding functional.

Checklist

• Product decision records reason, placement, owner, and validation.
• Scope excludes the selected OpenShell dependency update.
• Scope excludes Isolate the OpenShell integration and migrate eligible CLI operations to the SDK or gRPC #9802 transport work.
• Capability slices deliver user or maintainer value.
• Security and failure boundaries are explicit.
• Verify provider profile imports for the OpenShell upgrade #12940 and Build Dockerfile sources into images before OpenShell sandbox creation #12942 track import-only profiles and local Dockerfile image builds as separate readiness outcomes.