bug: sandbox from a `USER root` image fails with an unexplained "UID or GID zero" error

[mpereira]

User Story

As someone creating a sandbox from an off-the-shelf image,
I want the error to say that the image runs as root and what I can do about it,
so that I can fix it without having to read OpenShell source code.

Problem Statement

OpenShell never runs a workload as root. When the policy doesn't set process.run_as_user, the Docker driver takes the identity from the image's USER, so an image that declares USER root is rejected. That's intended and documented in docs/how-it-works/policies/default-policy.mdx. The error message could be improved:

IdentityResolutionFailed: descriptor error: workload identity must not contain UID or GID zero

It doesn't say the zero came from the image's USER, it doesn't suggest a fix, and descriptor error is an internal name. The CLI also prints it twice.

From reading the code, a non-root user listed as a member of group 0 in the image's /etc/group gets the same error. Setting run_as_group alone doesn't fix it: the user still belongs to group 0 through the image's /etc/group.

Two related things I found:

• Docker defaults to root both when the image has no USER and when it explicitly declares USER root. OpenShell instead uses 1000:1000 for the first case and rejects the second.
• docs/how-it-works/sandboxes/runtimes.mdx says images without USER must set both policy fields. The code and default-policy.mdx say they fall back to 1000.

#3653 asks for regression tests on the same root rejection. This issue is about the error message.

Impact / Why This Matters

The error comes after the image pull, and it names neither the image nor a fix. Reading crates/openshell-driver-docker/src/lib.rs shows that the image's USER was the cause.

As an end user, the workaround is to build a derived image with a non-root USER, or to set run_as_user and run_as_group in a policy file. Neither is discoverable from the error.

For netshoot the policy route gets past identity resolution and then fails workspace validation: its WORKDIR is /root, which is drwxrwx--- root root in the image, so UID and GID 1000 can't enter it. That's a separate problem and not part of this issue.

Acceptance Criteria

• When the Docker or Podman driver resolves an identity that contains a 0, the error says which part is zero (user, group, or a supplementary group) and where it came from (the image's USER, its /etc/passwd or /etc/group, or the policy).
• When the zero comes from the image's USER, the error names the image and says to use a non-root image or set process.run_as_user and run_as_group.
• descriptor error doesn't appear in the message.
• The CLI prints the failure once.
• runtimes.mdx matches default-policy.mdx and the code for images with no USER.
• Root is still rejected, and an image with no USER and no policy identity still gets 1000:1000.

Reproduction Steps

1. openshell sandbox create --name test-sandbox --detach --from nicolaka/netshoot:latest
2. It fails with "IdentityResolutionFailed".
3. docker image inspect nicolaka/netshoot:latest --format '{{.Config.User}}' shows root.

Environment

• OpenShell 0.1.2 (Homebrew) on macOS 26.2 arm64, local Docker gateway. The identity code and both docs pages are the same on main at 021400be8.
• Docker Engine 29.4.0 (linux/arm64)

Logs

$ openshell sandbox create --name test-sandbox --detach --from nicolaka/netshoot

Created sandbox: test-sandbox

✗ Error: IdentityResolutionFailed: descriptor error: workload identity must not contain UID or GID zero
✓ Sandbox allocated (0s)
✓ Image pulled (0s)                                                                                                           Error:   × sandbox entered error phase while provisioning: IdentityResolutionFailed: descriptor error: workload identity must not
  │ contain UID or GID zero

[shrxyas-246]

Reproduced on 0.1.2 (deb), Ubuntu 24.04 on WSL2, kernel 6.18.33.1 x86_64,
Docker 29.8.2, local Docker gateway.

On the CLI printing it twice: on a TTY the message body actually appears three
times, from three separate paths in crates/openshell-cli/src/run.rs.

˙ Starting sandbox... Docker sandbox provisioning failed: descriptor error: workload identity must not contain UID or GID zero (0s)
✗ Error: IdentityResolutionFailed: descriptor error: workload identity must not contain UID or GID zero
Error:   × sandbox entered error phase while provisioning: IdentityResolutionFailed: descriptor error: workload identity must not contain UID or GID zero

• run.rs:993, d.set_active_detail(&ev.message) renders the condition
  message into the spinner detail.
• run.rs:1028, d.finish_error() prints the ✗ Error: line from
  last_error_reason, assembled at run.rs:940 as
  format!("{}: {}", condition.reason, condition.message).
• run.rs:1248 wraps that same string in a miette! which the outer handler
  prints again.

The first two are gated on let interactive = std::io::stdout().is_terminal()
at run.rs:725, so the count depends on whether stdout is a TTY. Piping the
command collapses it. Worth knowing for whoever writes the test, since a piped
assertion won't catch a regression here. I captured the above under script to
keep a real PTY.

The descriptor error prefix isn't in the identity code. It comes from the
Display impl on BackendError at
crates/openshell-isolation-interface/src/contract.rs:118:

Self::Descriptor(m) => write!(f, "descriptor error: {m}"),

and the guard is at contract.rs:219, where uid == 0, gid == 0 and
supplementary_gids.contains(&0) all produce the same string. So that bullet
needs a different error variant or a mapping at the driver, not a reworded
message.

On the docs conflict, runtimes.mdx:298 is the incorrect page. An image with
no USER and no policy identity resolves to 1000:1000 and comes up fine:

$ docker image inspect alpine:latest --format '[{{.Config.User}}]'
[]

$ openshell sandbox create --name nouser-uid --detach --from alpine:latest
[0.0s] Sandbox allocated
[0.0s] Image already present
[0.2s] Starting sandbox Container created
  Name: nouser-uid
  Phase: Ready

$ for c in $(docker ps --format '{{.Names}}' | grep nouser-uid); do \
    echo "$c => $(docker inspect "$c" --format '{{.Config.User}}')"; done
openshell-default--nouser-uid-0f777dd8-3e45-4a97-a8ad-8e8cc33ced4f-supervisor => 65534:65534
openshell-default--nouser-uid-0f777dd8-3e45-4a97-a8ad-8e8cc33ced4f => 1000:1000

The effective policy had no process block, so images without USER plainly do
not "must set both fields in policy". The code at
crates/openshell-driver-docker/src/lib.rs:655 and default-policy.mdx:52
agree on the 1000 fallback.

One scoping question. ResolvedWorkloadIdentity::new has 7 non-test callers:
openshell-driver-docker/src/lib.rs:655 and :694,
openshell-driver-podman/src/isolation.rs:137 and :181,
openshell-driver-kubernetes/src/driver.rs:2481 and :2738, and
openshell-driver-vm/src/isolation/mod.rs:87. The acceptance criteria name only
Docker and Podman, so Kubernetes and VM would keep the current message. Is that
deliberate for now, or should the constructor return a structured reason so
every backend improves together? Happy either way, I just don't want to pick the
wrong one and redo it.

Minor: the source doc comment on ResolvedWorkloadIdentity lists policy,
template, image, but the no-USER branch at lib.rs:655 passes "default".

I'd like to pick this up if it gets accepted.

[elezar]

📋 triage-agent

Triage Assessment

Classification: validated-bug — identity diagnostics, CLI error presentation, and documentation. Rejecting a root workload is intended behavior and must remain enforced.

Summary

The report provides sufficient reproduction and environment details. The original macOS/Docker report and the subsequent Linux/WSL2 reproduction agree with the active code paths. The diagnostic omits which identity component is zero, its origin, the image name, and remediation; interactive CLI output repeats the failure; the runtime documentation incorrectly requires policy identity fields for images without USER.

Investigation

• Current code: checked local revision 021400be8 and the relevant files on current main, b3e92013163ade4856d96f5857f5969d9a7bb4fc. The reported paths remain present. This assessment used source inspection and the two supplied runtime reproductions; I did not run a new sandbox or PTY reproduction.
• Error construction: ResolvedWorkloadIdentity::new combines UID zero, primary GID zero, and supplementary GID zero into one message. BackendError::Display adds descriptor error:. Both Docker and Podman expose that constructor error.
• Identity provenance: the Docker resolver and Podman resolver select policy/image fields, resolve account names, and collect supplementary memberships before validating the numeric identity. A non-root account explicitly listed in image group 0 remains invalid even after overriding its primary group. The existing coarse source value becomes policy when either field is overridden, so it is insufficient to attribute every rejected component accurately. Diagnostics should distinguish the field's selector origin from the account file that supplied its numeric value.
• CLI repetition: run.rs chooses interactive progress from stdout's TTY status. It renders event detail at line 994, finishes with the condition error at line 1030, and returns a diagnostic containing that error at line 1248. This supports the comment's report of up to three appearances on a TTY; the first two paths are absent from plain output. The spinner detail is transient, while the progress error and returned diagnostic produce two persistent reports. Clarify whether “once” covers final visible output or every terminal write, including transient spinner frames. A piped assertion alone would not validate the interactive acceptance criterion.
• No-USER behavior: both drivers synthesize UID/GID 1000:1000 when neither the image nor policy supplies an identity. Existing resolver tests cover that fallback. runtimes.mdx:298 contradicts it; default-policy.mdx correctly describes it. An explicit root USER follows account resolution and is rejected instead. These cases must stay distinct.
• Releases: the latest stable release is v0.1.2, which both reporters used. No concrete released fix was identified, and the affected code remains on current main.

Related Work

This is related to matthewgrossman's OCI image work, but the reviewed changes do not resolve this issue:

• Merged feat(sandbox): use policy-first OCI image identity #2509 established policy-first OCI image identity selection.
• Open fix(podman): create managed workspace volumes owned by the workload identity #3981 fixes Podman managed workspace volume ownership; open feat(podman): honor OCI image working directories #3982 adds Podman OCI WORKDIR handling and WorkspaceValidationFailed reporting. The /root working-directory failure described here belongs to that workspace concern, separate from identity resolution.
• Open test(oci): share OCI USER and WORKDIR checks across Docker and Podman #3931 adds shared Docker/Podman OCI image tests. Its four scenarios cover valid image identities and workspace behavior, not actionable root-identity errors or their repetition under a PTY.
• feat(podman): honor OCI image working directories #3982 edits the same runtime documentation's WORKDIR paragraph, but leaves the incorrect no-USER identity table entry unchanged. Coordinate edits in that file if both changes proceed.
• test(drivers): pin root rejection for image-mapped policy identities in Docker and Podman #3653 requests resolver-level regression tests for policy names mapped by image accounts to zero. It overlaps the root-rejection invariant but tracks a different outcome from this issue's diagnostics and CLI presentation. No canonical duplicate was identified.

Impact Signals

• Affected users/scope: Docker and Podman users selecting images with root UID, primary GID, or supplementary GID; repeated CLI diagnostics affect interactive provisioning failures. Runtime reproductions were supplied for Docker on macOS and Linux/WSL2; Podman behavior is supported by source inspection.
• Regression: diagnostic regression status is unknown; no previously actionable message or single-render behavior was established.
• Workaround: derive an image with a suitable non-root identity or provide appropriate policy user/group selectors. Overriding the primary group does not remove supplementary group 0. Workspace permissions can still fail independently after identity resolution succeeds.
• Evidence quality: high for the code paths and documentation conflict, supported by two supplied reproductions; no fresh runtime reproduction or Podman reproduction was performed for this assessment.

Human Decision Required

Decide whether to accept this diagnostics/docs work and whether it remains human-owned. Acceptance is recorded by state:accepted, roadmap association, or both; sequencing remains a maintainer decision. The contributor's question about extending improved errors to Kubernetes/VM is a scope decision: the current acceptance criteria explicitly cover Docker/Podman, and a shared constructor change may affect other drivers. The diagnostics request is technically feasible without relaxing root rejection.

If deeper investigation or planning should enter the unattended queue, a maintainer can apply agent:plan-requested; a direct request can also authorize that phase. If declining, close as not planned with a rationale. Technical validation alone does not record acceptance or assign implementation ownership.