onboard: accept a downstream-published prebuilt sandbox image (--from-image), per #6402's close note
- 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
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