NVIDIA / NVIDIA/NemoClaw

Support authenticated external components with the Podman runtime

Open
#11,611 0 comments 0 reactions 0 assignees View on GitHub
area: networking area: onboarding
Dominant language
TypeScript
Stars
22.5k
Forks
3.1k
Avg merge
1d 1h
Merged PRs (30d)
715

Description

## Problem Statement

NemoClaw has a Podman runtime provider, but authenticated external-component onboarding currently requires the Docker driver.

At commit `37261efb99c0dcbfcef6551efa0c59357e96fcbe`, [externalComponentGatewayNetwork](https://github.com/NVIDIA/NemoClaw/blob/37261efb99c0dcbfcef6551efa0c59357e96fcbe/src/lib/onboard/external-component/gateway-config.ts#L29) rejects non-Docker drivers with `endpoint_restricted`. This is a source-confirmed capability gap; this issue does not claim a live Podman reproduction.

The Docker network preparation work in #11606 and #11595 does not add this capability.

## Desired Behavior

A user selecting Podman can onboard OpenClaw or Hermes with an authenticated external component. NemoClaw prepares verified connections before gateway startup, then completes sandbox creation and bounded activation.

For example, a fresh supported Linux Podman environment can prepare the required networking and authenticated connections without first running ordinary onboarding or creating a temporary sandbox.

## Scope and Exclusions

- Support authenticated version 2 external-component declarations through the existing Podman runtime provider.
- Define Podman-specific network ownership, preparation, inspection, and host reachability. Do not copy Docker bridge assumptions without evidence.
- Use the same selected Podman service and existing socket, executable, and resource ownership checks throughout preparation and startup.
- Reuse compatible existing network state. Reject incompatible, ambiguous, replaced, or unreachable state safely.
- Distinguish confirmed absence from inspection failure. Bound operations and reconcile uncertain creation results before further action.
- Preserve network state after later preparation or authentication failures. Do not add automatic repair, deletion, recreation, or blind mutation retries.
- Preserve ordinary onboarding on both runtimes and authenticated Docker behavior.
- Do not require inference route configuration before sandbox creation.
- Keep runtime pin changes, component schema changes, credential custody changes, and unrelated agent image fixes outside this proposal.
- Do not add an installer or broaden host permissions.

## Ongoing Ownership

Implementation owner: unassigned.

Proposed ongoing ownership: maintainers of the Podman runtime provider and external-component onboarding. Confirm an accountable maintainer before implementation.

## Placement and Support Expectations

Requested placement: core NemoClaw, using the existing runtime provider and external-component paths.

This issue requests capability planning and implementation. It does not claim existing support or a release commitment. Record the accepted design, accountable maintainer, and supported runtime configurations before implementation.

## Validation Plan

- Add deterministic coverage for missing and existing compatible networks, inspection failures, incompatible state, ambiguous addresses, identity drift, and uncertain creation outcomes.
- Cover preparation refusal, invalid trust, authentication rejection, invalid callback manifests, and activation failure.
- Verify that Docker is never invoked when Podman is selected.
- Use generic authenticated fixtures with real NemoClaw-managed OpenShell and Podman on isolated Linux environments.
- For both OpenClaw and Hermes, verify fresh-host preparation, gateway startup, sandbox creation, activation, agent startup, managed inference, and allowed and denied workload requests.
- Verify ordinary Podman onboarding and the existing Docker paths.
- Follow repository test-selection guidance and the maintainer E2E workflow. Record exact revisions and distinguish deterministic results from live evidence.
- Report later agent or runtime blockers separately. Do not claim full onboarding when later stages remain untested.
- Update owning guidance and public compatibility documentation with verified support limits.

## Compatibility Requirements

Target the Linux Podman configurations supported by NemoClaw. Confirm the supported privilege mode, network backend, Podman version, and OpenShell version before implementation.

Do not assume Docker network inspection fields or gateway addresses apply to Podman. Remote Podman services and non-Linux hosts require an explicit scope decision.

## Security or Privacy Impact

NemoClaw must remain the sole writer of its generated OpenShell configuration and the gateway lifecycle owner. OpenShell must retain effective-policy validation and enforcement. The external component must retain policy and callback-manifest authority.

Preserve TLS verification, caller authentication, endpoint restrictions, protected trust files, failure policies, and bounded activation. Do not add permissive startup, broader listener exposure, or credentials in sandbox configuration, fixtures, logs, or issue text.

## Implementation Idea

Extend the existing runtime provider boundary with the smallest verified Podman-specific preparation and address-inspection behavior. Confirm network lifecycle ownership before introducing creation.

If implementation requires an OpenShell public interface or broader lifecycle changes, document the concrete gap here for a scope decision. Upstream issue creation is outside this request.

## Category

Platform

## Checklist

- [x] Searched existing issues and pull requests; no matching capability issue was found.
- [x] Described the problem, desired behavior, and validation requirements.

Contributor guide

Open the contributing guide

Research direction

Start with src/lib/onboard/external-component/gateway-config.ts and the existing runtime provider and external-component onboarding paths. Follow repository test-selection guidance and the maintainer E2E workflow, beginning with deterministic network and authentication cases before isolated Linux Podman validation. Done means an accepted design and accountable maintainer, verified Podman support without Docker invocation, preserved Docker behavior, and updated compatibility guidance.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
backend, infrastructure, security
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.