NVIDIA / NVIDIA/NemoClaw

[Kubernetes] Run NemoClaw in-cluster against an externally managed OpenShell gateway

Open
#9,816 1 comment 0 reactions 1 assignee Claimed by @apurvvkumaria View on GitHub
area: e2e area: networking area: onboarding area: sandbox area: security enhancement NCE platform: k8s
Dominant language
TypeScript
Stars
22.5k
Forks
3.1k
Avg merge
1d 1h
Merged PRs (30d)
715

Description

Parent Epic: #9802

## Outcome

NemoClaw can validate one explicit remote OpenShell target without owning the gateway lifecycle or relying on local gateway state.

This Epic covers reusable external-target foundation work. It does not establish Kubernetes runtime support, authenticated lifecycle support, or production support.

## Terminology

### Local externally-supervised gateway authority

The existing `NEMOCLAW_GATEWAY_MANAGEMENT` contract describes a gateway on the same host as NemoClaw.

It requires:

- A loopback endpoint.
- A local state directory.
- A systemd unit and gateway executable.
- Listener process, executable, and cgroup verification.

NemoClaw attaches to and validates this gateway. The declared supervisor retains lifecycle authority.

This contract remains unchanged.

### Remote external OpenShell target

A remote external target describes:

- A non-loopback HTTPS origin.
- One explicit OpenShell workspace.
- Explicit TLS trust material.
- An accepted machine-authentication provider.
- One exact OpenShell release.
- External gateway lifecycle ownership.

A remote target must not use the local gateway-management declaration. It must not weaken the local systemd ownership checks.

## Current accepted scope

- Keep the existing platform-neutral, plan-only external-target contract.
- Continue read-only readiness, inventory, release, and status work under #9872 after its authentication decisions are accepted.
- Use the official OpenShell TypeScript SDK for remote calls.
- Keep every remote operation bound to the explicit endpoint and workspace.
- Do not use an ambient OpenShell CLI profile or selected gateway.
- Do not install, start, stop, restart, upgrade, or remove the remote gateway.
- Do not add sandbox, provider, policy, or inference mutation in the current slice.

PR #10368 completed the reviewed SDK package-access prerequisite.

The proposed next dependency slice will evaluate and pin OpenShell and `@nvidia/openshell-sdk` `v0.0.115` for future authenticated external-target work. That slice belongs under #9872 and requires its own accepted decision.

## Dependencies and sequencing

- #10613 owns the supported headless NemoClaw plan, apply, and observe package API for the in-cluster runner; it does not block the read-only work in #9872.
- This issue depends on the typed, asynchronous OpenShell interface and the applicable SDK transport work from #9802.
- #9803 owns the sandbox inventory and readiness adapter slice. PR #10537 migrates the `debug` consumer under #9803; it is not a delivery PR for this issue.
- This issue does not depend on all OpenShell operation migrations in #9802. Each delivery slice must name the specific #9802 dependency that it requires.

## Design constraints

- Validate the explicit HTTPS endpoint, CA, workspace, and exact release before authenticated calls.
- Call public gateway health before requesting an authentication token.
- Stop on a release mismatch before requesting a token or starting an authenticated call.
- Use an accepted renewable OIDC token provider for authenticated work. Define issuer, audience, scope, renewal, revocation, and workspace authorization before implementation.
- Keep credential values out of command arguments, logs, plans, receipts, and retained artifacts.
- Return redacted errors for TLS, transport, authentication, authorization, and release failures.
- Do not add a CLI fallback or a local gateway fallback.
- Do not add an SDK client framework without a current production consumer.
- Keep the local externally-supervised gateway behavior and its tests unchanged.

## Acceptance evidence

- [ ] A valid explicit target produces a credential-free plan without network, subprocess, or mutation effects.
- [ ] A non-loopback HTTPS target with trusted CA material can verify public health and the exact accepted OpenShell release.
- [ ] A release mismatch stops before the token provider or an authenticated call is used.
- [ ] Invalid endpoint, CA, workspace, release, or authentication configuration fails with redacted diagnostics.
- [ ] Package tests verify the exact SDK version, package source, lockfile identity, and integrity value.
- [ ] Tests prove zero Docker, Podman, local gateway lifecycle, ambient CLI profile, and selected-gateway calls.
- [ ] Tests prove that a remote target cannot enter the local externally-supervised path.
- [ ] Existing local externally-supervised gateway tests continue to pass without behavior changes.

Authenticated workspace and inventory evidence requires a separately accepted authentication contract. Sandbox mutation and cluster qualification require separate product decisions.

## Delivery slices

1. #9872 — explicit remote target, exact release, public health, and read-only workspace operations.
2. A child of #9872 — semantic upgrade of the remote target and official SDK to `v0.0.115`.
3. #9873 — sandbox lifecycle work only after its product, authentication, ownership, and recovery contracts are accepted.
4. #9874 — Kubernetes qualification only after the required runtime capabilities and qualification scope are accepted.

## Stop conditions

Stop before implementation if any of these conditions apply:

- No accepted production consumer exists for a proposed SDK client.
- The machine-authentication contract is not accepted.
- The selected OpenShell release does not provide the required operation.
- The change would weaken TLS, workspace authorization, image provenance, ownership verification, or cleanup checks.
- The change would route a remote target through the local externally-supervised mode.

## Out of scope

- Extending `NEMOCLAW_GATEWAY_MANAGEMENT` to remote hosts.
- Installing or managing the remote OpenShell gateway.
- A fixed Kubernetes packaging or runtime shape.
- Sandbox mutation in the current read-only slice.
- In-cluster image builds or arbitrary custom image support.
- Agent-specific workflow selection until that workflow has accepted scope and evidence.
- Multi-tenancy, high availability, broad platform coverage, or production support.

## Ownership

The existing assignee owns #9816 and #9872 implementation. NemoClaw maintainers retain ownership of the public integration boundary and product-scope decisions.

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.