NVIDIA / NVIDIA/NemoClaw

onboard: accept a downstream-published prebuilt sandbox image (--from-image), per #6402's close note

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

Description

### Problem Statement

`nemoclaw onboard` has two image paths: the managed shipped-agent images (including the exact-digest buildless path from #9140 / PR #9323, locked to `MANAGED_IMAGE_REPOSITORIES`), and `--from `, which always builds locally with the Dockerfile's parent directory as the context. There is no supported way to onboard from a **downstream-published prebuilt image**.

When #6402 was closed as superseded for the Brev fast path, the close note said: *"If a current consumer requires an arbitrary user-supplied prebuilt artifact, scope that separately under the accepted #10904 configuration architecture with explicit provenance, ownership, compatibility, fallback, and validation requirements."* We are that consumer now. The VSS blueprint ([NVIDIA-AI-Blueprints/video-search-and-summarization](https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization)) builds OpenClaw and Hermes harness images from `.openclaw/Dockerfile` / `.hermes/Dockerfile` (NemoClaw's documented custom-image workflow, `FROM` the managed images at pinned digests), and is moving those builds into its GitHub CI (immutable `develop-` tags, multi-arch, nightly acceptance — its `.github/github-first.md` process; see VSS PR #2222). At deploy time, onboard must still rebuild locally from the Dockerfile; the only way to consume the CI-built image is a FROM-only Dockerfile that exists solely to satisfy the build path — and it must still carry the `ARG NEMOCLAW_TOOL_DISCLOSURE` → `ENV` pair to pass the Dockerfile tool-disclosure contract, plus a dedicated directory so the custom build-context staging has something to copy.

### Desired Behavior

`nemoclaw onboard --from-image @` (env: `NEMOCLAW_FROM_IMAGE`; or the equivalent field in the #10904 declarative configuration) creates a sandbox from an already-published image, going through the same provider, policy, registry, readiness, and lifecycle logic as a `--from` build:

- Reference is digest-pinned (reject bare mutable tags, mirroring the managed exact-digest posture).
- Compatibility is verified before sandbox creation: platform/architecture, the documented custom-image runtime invariants (non-root final user, workspace WORKDIR, a command that stays alive), and the tool-disclosure mode — readable from the image's `NEMOCLAW_TOOL_DISCLOSURE` ENV, which the existing Dockerfile contract already guarantees ends up baked into any conforming image, so image inspection can replace Dockerfile-text validation.
- Registry metadata is identical in shape to a built sandbox; the digest participates in stale-sandbox/upgrade detection.
- An incompatible or unpullable image is an explicit, actionable error — never a silent fallback build.

### Scope and Exclusions

In scope: an explicit, opt-in prebuilt-image input for the custom (non-managed) path. Out of scope: artifact discovery/caching (that was the #9140 fast path), any change to the managed shipped-agent flow, and building/publishing the downstream image (the consumer's CI owns provenance, as it already does for `--from` Dockerfile content).

### Ongoing Ownership

NemoClaw owns the onboarding surface; the VSS blueprint team volunteers as first consumer for design review and end-to-end validation against our published harness images.

### Placement and Support Expectations

`src/lib/onboard` beside the existing `--from` handling; supportable wherever `--from` is (Docker driver first is fine).

### Validation Plan

E2E: onboard from a published harness image by digest, verify sandbox creation, disclosure recording, and rebuild/recreate semantics. Negative: wrong platform, missing disclosure ENV, non-digest reference, unpullable image — each an actionable error.

### Compatibility Requirements

Purely additive: `--from ` unchanged; the FROM-only-Dockerfile workaround keeps working. Recorded sandbox metadata stays shape-compatible.

### Security or Privacy Impact

No new credential paths (registry auth = the existing container-runtime credentials). Digest pinning removes the mutable-tag substitution risk. Trust in image content is the consumer's, exactly as it is today for the Dockerfile and build context supplied to `--from`.

### Implementation Idea

The exact-digest buildless machinery from #9140/PR #9323 already covers most of this (pull by digest, skip build, record); the delta is allowing a non-managed repository behind the explicit flag and swapping the Dockerfile tool-disclosure text contract for an image-ENV inspection.

### Category

CLI / onboarding.

Contributor guide

Open the contributing guide

Research direction

Start in src/lib/onboard beside the existing --from handling, then read the exact-digest buildless machinery from #9140/PR #9323. Trace how provider, policy, registry, readiness, lifecycle, and sandbox metadata are handled, and validate the published image by digest. Done means supported Docker-driver onboarding, disclosure recording, recreate semantics, and actionable errors for wrong platform, missing disclosure, mutable references, and unpullable images.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, typescript
Domain
cli, devops
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.