Repository navigation
Description
User Story
I use OpenShell with the Docker compute driver to run agent sandboxes declared from Kubernetes. I directly hit this when a sandbox using an image without a user database stayed blocked with IdentityResolutionFailed, so I want minimal images, such as FROM scratch builds, to run the same way they do on Podman and Kubernetes.
Problem Statement
The Docker driver reads /etc/passwd and /etc/group from the image before it resolves the workload identity, and fails the sandbox if either file is missing. It does this even when no lookup is needed: when the image declares no USER and the policy requests no identity, or when both the user and group are numeric.
The resolver already handles the first case. It synthesizes the default non-root identity "matching the Podman driver's USER-less default" (crates/openshell-driver-docker/src/lib.rs:716). That branch is unreachable for these images, because the file read fails first (crates/openshell-driver-docker/src/lib.rs:1477-1492).
A second check fails even earlier for the same images. The resolver creates a helper container from the image, and Docker rejects it when the image has no CMD or ENTRYPOINT ("no command specified"). OpenShell replaces the image's command with the supervisor anyway, so the image's CMD shouldn't matter.
The other drivers accept these images:
- Podman treats a missing file as empty (
crates/openshell-driver-podman/src/driver.rs:1700). - Kubernetes sets a numeric UID and GID and never reads the files.
Impact / Why This Matters
- The same image works on Podman and Kubernetes and fails on Docker. Docker is the default local gateway, so developers hit it first.
- Images without a user database, such as
FROM scratchstatic binaries, can't run on Docker. The workaround is to add/etc/passwdand/etc/groupfiles that the workload doesn't need. - The error doesn't explain the fix. The sandbox reports
IdentityResolutionFailedwith "read immutable image /etc/passwd for workload identity", and doesn't say that a numeric identity would need no lookup.
Acceptance Criteria
- On the Docker driver, an image with no
/etc/passwdand no/etc/group, noUSER, and no requested identity runs as the default non-root UID and GID. - An image with a numeric
USERand group, or a policy with numericrun_as_userandrun_as_group, runs without either file. - A named user or group that can't be resolved, because the file is missing or has no matching entry, still fails with a message that names the user or group and the missing file.
- An image with no
CMDorENTRYPOINTgets past identity resolution. - A driver test covers a
FROM scratchimage.
Reproduction Steps
-
Start a local gateway with the Docker compute driver.
-
Build a minimal image with no user database:
printf 'FROM busybox:1.36 AS b\nFROM scratch\nCOPY --from=b /bin/busybox /busybox\nCMD ["/busybox"]\n' > Dockerfile docker build -t openshell-scratch:test .
-
Create a sandbox from it:
openshell sandbox create --from openshell-scratch:test -- /busybox sleep 3600
-
The sandbox fails with
IdentityResolutionFailedbecause it can't read/etc/passwdfrom the image. -
Remove the
CMDline, rebuild, and create the sandbox again. It now fails earlier, with "create Docker identity resolver container: ... no command specified".
I first hit this with ghcr.io/nvidia/openshell/sandbox:0.1.6, which also has no /etc/passwd.
Environment
- OpenShell: CLI 0.1.5 with a local gateway on the Docker driver. The code paths above are unchanged on
mainat 38c4741. - OS: macOS (Darwin 25.6)
- Runtime, deployment, or integration: Docker compute driver
Suggested UX (if applicable)
No new configuration. Treat a missing /etc/passwd or /etc/group as empty, like the Podman driver, and fail only when a name must be resolved:
IdentityResolutionFailed: user "app" requires /etc/passwd in the image; set a numeric USER or process.run_as_user
Logs
With CMD:
IdentityResolutionFailed: ... Docker responded with status code 404: Could not find the file /etc/passwd in container openshell-supervisor-extract-95402-17-identity
Without CMD:
IdentityResolutionFailed: create Docker identity resolver container: Docker responded with status code 400: no command specified
Activity