Skip to content

refactor(sandbox)!: retire community images and default to Alpine - #3386

Draft
akram wants to merge 8 commits into
NVIDIA:mainfrom
akram:refactor/retire-community-images-alpine
Draft

akram wants to merge 8 commits into
NVIDIA:mainfrom
akram:refactor/retire-community-images-alpine

Conversation

@akram

@akram akram commented Sep 16, 2026

Copy link
Copy Markdown
Contributor

Summary

Retire the OpenShell Community sandbox images and default to a generic, version-qualified official Alpine image, so a fresh install does not depend on the community image catalog. A bare Alpine base declares no OCI USER; the local container drivers now start such images as a synthesized non-root account instead of rejecting them.

This is rebased on the RFC-0012 sandbox architecture (#2942) and adapts the driver identity path accordingly.

Related Issue

Closes #3116.

Changes

  • Default sandbox image → Alpine. openshell-core::image now exposes DEFAULT_SANDBOX_BASE_IMAGE = "docker.io/library/alpine:3.22" and default_sandbox_image() returns it.
  • Remove community image resolution (breaking). Drop DEFAULT_COMMUNITY_REGISTRY, resolve_community_image, and the OPENSHELL_COMMUNITY_REGISTRY override. --from values are now explicit OCI references passed through unchanged by the CLI and TUI; bare shorthand names are no longer expanded.
  • Numeric non-root identity for USER-less images. When an image declares no OCI USER and the policy requests none, the Podman and Docker drivers supply a numeric non-root identity (DEFAULT_SANDBOX_UID/GID = 1000) instead of rejecting the image, matching the Kubernetes and VM drivers. Images that declare a USER keep the OCI resolution path unchanged.
  • Policy. Drop the community-image /app read path from the default policy.
  • Deploy. Default the Helm chart, gateway.toml, and dev gateway scripts to Alpine (preserving the RFC-0012 sandbox_runtime_image/SUPERVISOR_IMAGE keys), and add OpenShift in-cluster multi-stage build variants for the supervisor and gateway images.
  • Cleanup. Retire residual community-image references in RPM/Helm docs, SDK examples, and test fixtures.

Two references are intentionally left for separate follow-ups because they concern runtime/build inputs rather than the default: the VM runtime image pin (crates/openshell-driver-vm/runtime/pins.env) and the GPU e2e build base (tasks/scripts/e2e-gpu-build-images.sh).

Testing

  • cargo check --workspace is clean.
  • Unit tests pass, including the Docker and Podman driver identity tests (docker_identity_resolution_*) — explicit-root images are still rejected; USER-less images now resolve to the numeric default.
  • Both the gateway and supervisor images build musl-static in a release build.

Runtime end-to-end of a bare Alpine sandbox against a full RFC-0012 gateway is pending a suitable environment.

Checklist

… and gateway

Add multi-stage Dockerfiles that build the OpenShell supervisor and gateway
images entirely inside an OpenShift/Buildah cluster, for environments without
the upstream Nix CI pipeline that stages prebuilt binaries under
deploy/docker/.build/prebuilt-binaries.

Both reproduce the exact upstream artifacts by running the project's own Nix
devShells in a builder stage, then assembling a runtime stage identical to the
existing Dockerfile.supervisor / Dockerfile.gateway:

- Dockerfile.supervisor.multistage: builds the static musl openshell-sandbox
  binary via the musl devShell; runtime is alpine:3.22 with nftables/iptables
  and COPY --chmod=0555.
- Dockerfile.gateway.multistage: builds openshell-gateway via the glibc-2-28
  devShell, normalizes the ELF interpreter with patchelf and asserts z3 is
  statically embedded; runtime is distroless cc-debian13.

Each builder collapses build and cleanup into a single RUN so the Nix store
never enters the committed layer, keeping the intermediate commit small and
within the node's ephemeral-storage budget. The upstream Dockerfiles and CI
binary pipeline are unchanged.

Signed-off-by: Akram
Signed-off-by: Akram <akram.benaissi@gmail.com>
default_sandbox_image() now returns docker.io/library/alpine:3.22, a generic
version-qualified official image, so a fresh install no longer depends on the
community sandbox image catalog. All compute drivers (docker, podman,
kubernetes, vm) inherit this fallback.

Part of NVIDIA#3116.

Signed-off-by: Akram
Signed-off-by: Akram <akram.benaissi@gmail.com>
The restrictive default policy granted read-only access to /app, a directory
that only existed in the community base image. A generic Alpine default has no
/app, so remove it. Landlock best-effort already ignores absent paths; this
just stops advertising a community-specific layout in the default.

Part of NVIDIA#3116.

Signed-off-by: Akram
Signed-off-by: Akram <akram.benaissi@gmail.com>
…ox image

Update the shared gateway default_image, Helm chart values, the standalone
Kubernetes manifest, and the dev gateway task scripts to use
docker.io/library/alpine:3.22 instead of the community base image, consistent
with default_sandbox_image(). GPU e2e image-build base is left unchanged (CUDA
needs a glibc base).

Part of NVIDIA#3116.

Signed-off-by: Akram
Signed-off-by: Akram <akram.benaissi@gmail.com>
Remove DEFAULT_COMMUNITY_REGISTRY, resolve_community_image, and the
OPENSHELL_COMMUNITY_REGISTRY override. Bare --from values are no longer
expanded into the OpenShell Community registry; the CLI and TUI now pass
explicit OCI image references through to the gateway unchanged. The
openshell-core image module is reduced to default_sandbox_image().

BREAKING CHANGE: community sandbox shorthand names and OPENSHELL_COMMUNITY_REGISTRY
are no longer supported; pass a full OCI image reference to --from.

Part of NVIDIA#3116.

Signed-off-by: Akram <akram.benaissi@gmail.com>
With the default sandbox image now Alpine, images that declare no OCI USER
must start instead of being rejected. When the image declares no USER and
the policy requests none, the Podman and Docker drivers now supply a numeric
non-root identity (DEFAULT_SANDBOX_UID/GID = 1000) instead of rejecting,
matching the numeric-identity behavior of the Kubernetes and VM drivers. The
supervisor's resolved-identity path runs the sandbox as a synthesized
non-root account without the account existing in the image. Images that
declare a USER keep the OCI resolution path unchanged.

Part of NVIDIA#3116.

Signed-off-by: Akram <akram.benaissi@gmail.com>
Replace the remaining OpenShell Community sandbox image references (RPM/Helm
docs, SDK doc examples, and test fixtures) with the Alpine default, and update
the resolve_from test that asserted community-name expansion — bare values are
now passed through unchanged as explicit OCI references.

The VM runtime image pin (driver-vm/runtime/pins.env) and the GPU e2e build
base (tasks/scripts/e2e-gpu-build-images.sh) reference a community image for
their own runtime/build needs and are intentionally left for separate
follow-ups.

Part of NVIDIA#3116.

Signed-off-by: Akram <akram.benaissi@gmail.com>
@copy-pr-bot

copy-pr-bot Bot commented Sep 16, 2026

Copy link
Copy Markdown

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

…-image layout

RFC-0012 (NVIDIA#2942) split the runtime into three binaries. Match the in-cluster
(OpenShift/Buildah) multi-stage variants to the image set the Helm chart and
official Dockerfiles expect:

- Dockerfile.sandbox.multistage (new): static-musl openshell-sandbox on a
  scratch base (USER 65532), mirroring Dockerfile.sandbox.
- Dockerfile.supervisor.multistage: now builds the dynamically linked GNU
  openshell-supervisor on a debian base with ca-certificates, mirroring
  Dockerfile.supervisor (previously it built openshell-sandbox, which predated
  the RFC-0012 split).
- Dockerfile.gateway.multistage: unchanged (openshell-gateway).

Part of NVIDIA#3116.

Signed-off-by: Akram <akram.benaissi@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

refactor(sandbox)!: retire community images and default to Alpine

1 participant