feat: complete Docker and Podman runtime identity injection

[matthewgrossman]

Problem Statement

OpenShell already accepts trusted driver-provided numeric sandbox identities in policy and the supervisor, and Kubernetes and VM use that path. Docker and Podman do not resolve or inject an identity, so they fall back to the policy’s named sandbox:sandbox account. A bring-your-own image with no baked sandbox user therefore fails on those local drivers.

This is the OpenShell runtime portion of umbrella issue #1959. It must be independently shippable before OpenShell-Community publishes images that omit the named account.

Proposed Design

Add operator-only sandbox_uid and sandbox_gid configuration to the Docker and Podman compute drivers. Each driver resolves a safe local default of 10001:10001 when unset, validates configured values against the existing policy range, and injects OPENSHELL_SANDBOX_UID and OPENSHELL_SANDBOX_GID after user-provided environment values. The supervisor remains root for setup, then launches the agent under the resolved numeric identity.

Normalize the agent child environment in the supervisor so primary commands and SSH sessions receive HOME=/sandbox plus deliberate USER and LOGNAME values after privilege drop. This avoids Docker’s supervisor HOME=/root leaking into the agent process.

Add a checked-in userless image fixture and validate it on Docker and rootless Podman. The test must prove the agent UID/GID, HOME=/sandbox, and workspace write behavior. Retain existing Kubernetes and VM tests as regression coverage.

Document the new Docker and Podman gateway configuration, operator override and rootless UID/GID mapping constraint, and update BYOC guidance to remove the named-user requirement for supported OpenShell versions.

Alternatives Considered

• Continue requiring images to create sandbox:sandbox: rejected because it prevents arbitrary numeric runtime identities and leaves Docker/Podman inconsistent with Kubernetes and VM.
• Let sandbox creators select the UID/GID: rejected because identity is an operator/platform concern, not an end-user sandbox API.
• Discover arbitrary remote Docker/Podman subordinate-ID mappings: deferred. Operators can override the default; remote map discovery is separate work.
• Migrate OpenShell-Community images in this change: deferred to a dependent issue so no-user images are not published before compatible runtime support is released.

Agent Investigation

• openshell-policy and the supervisor already accept numeric identities in [1000, 2_000_000_000], honor OPENSHELL_SANDBOX_UID / OPENSHELL_SANDBOX_GID, and drop child privileges numerically.
• Docker and Podman currently start a privileged supervisor but do not inject those values, so their default policy resolves the image-provided sandbox account.
• Docker’s primary command path can inherit HOME=/root; SSH has separate identity environment logic. Both need one shared child-environment contract.
• This supersedes the Docker/Podman follow-up noted in the canonical plan on feat: inject sandbox UID via compute driver instead of requiring it in container images #1959. It is blocked only by the human-reviewed implementation plan and should close independently of feat: inject sandbox UID via compute driver instead of requiring it in container images #1959.

[matthewgrossman]

🏗️ build-plan

Implementation Plan

Issue type: feat
Complexity: Medium
Confidence: High — policy and supervisor numeric-identity support already exists; the bounded work is completing driver injection, child environment handling, validation, and focused local-driver coverage.

Summary

Complete the Docker and Podman half of OpenShell’s runtime-identity contract. Gateway operators may configure a numeric sandbox UID/GID; otherwise the local drivers use 10001:10001. The drivers inject those protected values into the root supervisor, which launches the agent under that numeric identity without requiring a baked sandbox account in the image.

Scope

• crates/openshell-driver-docker/ — add operator-only UID/GID config, pure resolution/validation, and protected environment injection.
• crates/openshell-driver-podman/ — add equivalent config, standalone flags/environment, validation, and injection.
• crates/openshell-supervisor-process/ — normalize HOME, USER, and LOGNAME for primary and SSH agent processes after the privileged supervisor drops identity.
• e2e/ — add a portable userless fixture and Docker plus rootless-Podman coverage.
• docs/, driver READMEs, example gateway config, and architecture docs — document the operator-owned config and the userless BYOC contract.

Implementation Steps

1. Docker configuration and injection

   • Add optional sandbox_uid / sandbox_gid fields to DockerComputeConfig and resolved fields to its runtime config.
   • Resolve uid = configured uid or 10001; resolve gid = configured gid or resolved uid.
   • Validate both values with openshell_policy::{MIN_SANDBOX_UID, MAX_SANDBOX_UID} before connecting to Docker or performing runtime/image setup.
   • Add the resolved OPENSHELL_SANDBOX_UID and OPENSHELL_SANDBOX_GID after template/spec environment merging, so image, template, and sandbox-provided values cannot override the driver.
   • Keep the container supervisor as UID 0; only its agent child receives the resolved non-root identity.
   • Add unit coverage for defaults, partial and full configuration, range failures, and environment precedence.

2. Podman configuration and injection

   • Add the same fields, resolution, validation, and driver-owned environment values to PodmanComputeConfig and build_env.
   • Update Default and custom Debug; validate before Podman client connection.
   • Expose standalone-driver --sandbox-uid / --sandbox-gid flags and OPENSHELL_PODMAN_SANDBOX_UID / OPENSHELL_PODMAN_SANDBOX_GID environment variables.
   • Mirror Docker’s unit tests. Keep the root 0:0 supervisor bootstrap unchanged.

3. Child-process environment contract

   • Extract the SSH identity-to-environment calculation into shared supervisor-process logic.
   • Apply it to SSH and the primary ProcessHandle path after inherited environment assembly and before exec.
   • Numeric identities set USER and LOGNAME to the numeric UID and HOME=/sandbox; named identities preserve their passwd home; defaults remain sandbox and /sandbox.
   • Preserve privilege-drop verification and SSH environment isolation. Add focused helper and primary-process environment tests.

4. Userless-image coverage

   • Add e2e/fixtures/userless/Dockerfile: no useradd/groupadd, build-time assertions that the base has neither a sandbox account nor UID/GID 10001, a /sandbox directory, and deliberately conflicting image UID/GID environment values.
   • Update the custom-image Docker E2E and add the smallest Podman-equivalent path, building the fixture with the selected engine rather than sharing Docker-local image tags.
   • Assert a marker, the agent’s UID/GID (10001:10001 by default), HOME=/sandbox, and successful writes under $HOME.
   • Remove any remaining named-user requirement from the live-policy-update fixture. Run existing Kubernetes and VM suites as regressions rather than adding new topology fixtures.
   • Numeric injection activates existing recursive /sandbox ownership preparation. If the current supported writable-volume path regresses, treat it as a release blocker and fix it in this PR; do not claim read-only /sandbox support.

5. Documentation and configuration examples

   • Update docs/reference/gateway-config.mdx and compute-driver documentation for the two new TOML fields, defaults, valid range, operator ownership, and rootless Podman mapping caveat.
   • Update Docker/Podman READMEs, deploy/docker/gateway.toml, relevant architecture docs, and BYOC guidance to distinguish the root supervisor from the numeric agent process and remove the named-user requirement for supported versions.

Test Plan

• Unit: Docker and Podman resolver, validation, and environment-precedence tests; shared child-environment helper tests; primary-process environment test.
• Integration: Existing driver/config tests continue to cover construction and parsing; add standalone Podman argument/config coverage where an established seam exists.
• E2E: mise run e2e:docker runs the userless image. mise run e2e:podman:rootless runs the equivalent fixture. Run existing rootful Podman coverage when locally available; existing Kubernetes and VM suites are regression gates.

Risks & Open Questions

• 10001 is inside the policy range and normally fits typical rootless subordinate maps, but is not universally mapped. Operators can override it; this issue does not discover arbitrary remote maps.
• Recursive ownership repair changes Unix ownership, not SELinux labels. Do not promise arbitrary bind-mount compatibility; preserve current mount-label behavior.
• No API, proto, Kubernetes/OpenShift, VM, Community-image, or named-identity-compatibility changes are in scope.

Documentation Impact

• Required: docs/reference/gateway-config.mdx.
• Also update compute-driver documentation, driver READMEs, example gateway config, architecture docs, and BYOC guidance where they describe image users or driver configuration.

---

Revision 1 — initial plan for #2331; scoped from umbrella #1959 and the reviewed runtime-identity design.

[matthewgrossman]

🏗️ build-from-issue-agent

Implementation Complete

PR: #2335

What was built

Docker and Podman now choose a validated numeric sandbox UID/GID, inject it as protected supervisor configuration, and launch agent processes with consistent identity environment variables. A userless image fixture verifies that images no longer need a baked-in sandbox account.

Tests

• Unit: driver identity defaulting, overrides, range validation, and environment precedence; supervisor child identity environment behavior
• Integration: Docker and Podman custom_image feature variants compile
• E2E: Docker userless-image path passed locally; rootless Podman runtime validation is covered by CI because Podman is unavailable on the development host

Docs updated

• Runtime and sandbox architecture overviews
• Docker and Podman driver READMEs
• Gateway configuration reference and Docker sample
• Bring-your-own-container example

The issue will auto-close when the PR is merged.

[matthewgrossman]

🏗️ build-from-issue-agent

PR blocked by vouch workflow

PR #2335 was created successfully, but the Vouch Check workflow closed it twice while reporting matthewgrossman as unvouched. GitHub reports the author's repository association as member; the workflow's org-membership bypass did not take effect.

The implementation, signed-off commit, full pre-commit suite, and local Docker userless-image E2E are complete. To resume CI, add matthewgrossman to the dedicated vouched branch through the normal /vouch process (or repair the workflow's ORG_READ_TOKEN membership check), then reopen #2335.