Repository navigation
Description
Problem
No v1 image is published. Every agent, runtime and proxy image is built locally (docs/build.md), and the examples reference locally built digests (docs/models.md: "refers to a locally built artifact, not a published registry image"). The default agent pin in versions.json is a local name (nc-fabric-owner-20260924@sha256:…). Kubernetes users push agent images to their own registry.
#12638 requires that a user can follow the first-deployment guide without building from source, which needs published images, but it lists only the CLI bundle and the SDK and provider packages. #12016 covers only the agent base images that downstream blueprints derive from.
What changed recently:
- One build path: every image builds through
docker-bake.hcl(refactor: build runtime images with Bake under image/ #13507, test: build the live proxy images with Bake #13510). - Bake's output is the final image: agent images get their catalog label inside the Bake build (refactor: label agent images in the Bake build #13514), so
bake --pushpublishes exactly what deployments use. - Reproducible runtime images: they build only for the host's platform, with rewritten timestamps and no provenance attestation.
Proposal
Publish to ghcr.io/nvidia/nemoclaw/…, where NemoClaw v0 and OpenShell already publish, from a release workflow.
Scope:
| Image | Bake target | Platforms |
|---|---|---|
| Agent images | agents |
All ten harnesses on linux/arm64 and linux/amd64 (#13519) |
| vLLM and Ollama runtimes | vllm, ollama |
linux/arm64 and linux/amd64, each built natively |
| Ollama proxy | ollama-proxy |
linux/arm64 and linux/amd64 |
| Reference agent, if derived-image testing needs it | dummy |
linux/arm64 and linux/amd64 |
Build:
- one job per architecture on native runners (GitHub's arm64 and amd64 runners), running
cargo images buildfor agents anddocker buildx bake --pushfor the others, withpackages: writeand the workflow's token; - a final job joins each image's platform digests into one index with
docker buildx imagetools create; - only release tags push; pull requests keep building and qualifying without pushing, as
images.ymldoes.
Names: new names that don't collide with v0's (sandbox-base, openclaw-sandbox, …): for example agent-openclaw, vllm, ollama, ollama-proxy, or a v1/ prefix.
Supply chain:
- GitHub artifact attestations or cosign signatures, attached as OCI referrers so that runtime-image digests stay reproducible (v0's
llama-cpp-image-attestworkflow is a precedent); - an SBOM per image and a vulnerability scan of the published digests (the image half of ci(security): scan source dependencies and built images for known vulnerabilities #7272).
Distribution review: the images redistribute vLLM, Ollama, OpenClaw, Hermes, Fabric and their dependencies. Their notices are retained (image/NOTICE.md, image/fabric/HERMES-NOTICE.md, image/vllm/NOTICE.md, image/ollama/NOTICE.md), but publishing needs a license review. The AGPL recipe is gone (#13506).
Staging before release
Public v1 releases wait for the installer and onboarding, validated by QA and product (#12638). Until then, stage everything privately so the release itself is a final switch:
- Push privately. A manually triggered workflow builds each architecture natively, pushes to new
ghcr.io/nvidia/nemoclaw/…packages, and joins each image's platform digests into one index. A new container package is private by default. - Draft the release. The workflow creates a draft release listing every image digest, and later the bundle. Only users with push access see drafts.
- Test from the draft. Deployments pull the private images with a token through
spec.registrieson Docker andimagePullSecretson Kubernetes (Pull images from private registries #12709), locally and on kind. - Release. Publish the draft and make the packages public. Making a package public can't be undone, and the organization's package-creation policy may need an admin to allow public packages.
Checked on 2026-10-20 with a throwaway push from a personal token (ghcr.io/nvidia/nemoclaw/visibility-probe, labeled with org.opencontainers.image.source=https://github.com/NVIDIA/NemoClaw, deleted afterwards):
- Visibility: the new package was
internal, visible to members of NVIDIA's enterprise. Anonymous pulls were refused (403). - Repository link: the label didn't link it to the repository (
repository: null).
The v0 packages, which Actions workflows published, are linked to this repository and public. Whether a package published by the workflow's own token starts internal or inherits the repository's visibility is still unchecked. The first private dry run will show it, and the workflow should check the package's visibility after its first push.
Decisions
- Names (decided):
ghcr.io/nvidia/nemoclaw/v1/<image>, for examplev1/openclaw,v1/vllm,v1/ollama,v1/ollama-proxy. The reference agent isn't published: it exists for tests, and derived images buildFROMthe real agent images (Publish base agent images per v1 release for derived sandbox images #12016). - Tags (decided): semver release tags, starting at
v0.1.0-rc1: thev1branch ships 0.1.x releases (ci: tag v1-branch releases as v0.1.x #13559). Version tags are permanent, because a repository rule forbids deleting them;v1.0.0-rc1was staged under the earlier scheme and remains, though nothing reacts to it. Pushing a tag runs the staging workflow from the tagged commit; GitHub only runs manually triggered workflows from the default branch, which is v0'smain. - Still open: how a release references its images. Either digests listed in the release notes only, or also pinned in the bundle, as
versions.jsonpins OpenShell's images. This can wait for the installer.
Follow-ups: #13521 (provenance attestations), #13522 (SBOMs), #13523 (vulnerability scanning), #13524 (license review).
Done when
- Published: a release publishes each image above as a signed index for its platforms, with an SBOM, on
ghcr.io/nvidia/nemoclaw. - Documented: the release notes list every image digest;
docs/build.md,docs/derived-images.md(Publish base agent images per v1 release for derived sandbox images #12016) and the examples point to the published images, keeping local builds as the alternative. - Usable without building: a first deployment from the guide applies with published images only.
- Default: the default
agentpin inversions.jsonnames a published, registry-qualified digest instead of the localnc-fabric-owner-…name. - Derivable: a reference derived image built
FROMa published base agent image applies by digest (from Publish base agent images per v1 release for derived sandbox images #12016).
Activity
feat: build every agent harness for linux/amd64 (#13519)
ci: push checked v1 images to an internal per-commit namespace (#13533)
ci: stage v1 releases from semver tags (#13534)
ci(docs): never publish documentation for release candidates (#13543)
cv commentedon Oct 20, 2026
Tested
v1.0.0-rc1from the draft on a DGX Spark (linux/arm64), with a CLI bundle built at the tagged commit and the private images pulled fromghcr.iowith a token.Docker: works.
v1/ollamaas the model server andv1/hermesas the agent.spec.registriesand the host'sdocker login. An anonymous pull is refused.uname -mwith its terminal tool and repliedaarch64.Kubernetes (kind): works, with workarounds.
ImagePullBackOffuntilghcr-credentialsexisted in the namespace NemoClaw created, as documented. Then the cluster pulledv1/deepagentsand the sandbox ran.Gaps for publishing:
docker pullon the agent image. Guides built images locally until now, so this never showed. Either plan pulls or reads the remote config, or the docs say to pull first.image.metadatabundles come only fromcargo images export-metadata, which isn't in the CLI bundle. It also can't export from a pulled image:docker image saveof the pulled index omits the platform config and layers ("image archive lacks a metadata blob"). For the test I assembled the bundle from the registry's exact bytes. A release should publish a metadata bundle per image, or the CLI should build one from the registry.crates/nemoclaw-fabric/src/image_metadata.rsrequires an index to have exactly one Linux child, "until per-platform runtime contracts are modeled". The publishedv1/<image>indexes cover arm64 and amd64, so a Kubernetes sandbox must reference a platform manifest digest instead. Either the release lists per-platform digests too, or NemoClaw models per-platform contracts.Everything was cleaned up afterwards: the deployments, the kind cluster, the pulled images, and the registry login.
1 remaining item
feat: publish Kubernetes metadata bundles with each staged release (#…
feat: accept multi-platform agent image indexes on Kubernetes (#13565)
feat(release): attach per-platform SBOMs to v1 images (#13590)
fix(sdk): require image.ref on every runtime (#14564)
feat(onboarding): suggest a local agent image that installs the chose…
cv commentedon Nov 18, 2026
Status as of 2026-11-18, with updated acceptance criteria. Not ready to close.
Done
ghcr.io/nvidia/nemoclaw/v1/…(feat: build every agent harness for linux/amd64 #13519, ci: push checked v1 images to an internal per-commit namespace #13533, ci: stage v1 releases from semver tags #13534, feat: pull Docker sandbox images before reading their labels #13554, feat: accept multi-platform agent image indexes on Kubernetes #13565, feat: publish Kubernetes metadata bundles with each staged release #13566). Each candidate fromv0.1.0-rc1tov0.1.0-rc10was staged this way, with a draft release listing every digest.v1.0.0-rc1on a DGX Spark).No longer applies
agentpin" criterion: v1 no longer has a default agent image. Every sandbox names its image by digest (fix(sdk): require image.ref on every runtime #14564), and onboarding suggesting a published digest is tracked in Onboarding suggests an agent image that can't be pulled; match the harness to a published image #14235.Updated acceptance criteria
v1/…packages public (needs an org admin if the package policy requires it).docs/build-deploy/build.md,docs/build-deploy/derived-images.mdand the examples point to the published images, keeping local builds as the alternative.FROMa published agent image applies by digest.