feat(podman): honor OCI image working directories

[matthewgrossman]

Summary

Podman sandboxes now use a custom OCI image WORKDIR as the persistent workspace and as agent commands' cwd and HOME, bringing Podman into parity with Docker. Empty, /, and /sandbox values retain the managed /sandbox fallback. Docker behavior is unchanged.

What you can now do

On a Podman gateway host, build an image with a writable custom working directory:

FROM ubuntu:24.04
RUN mkdir -p /home/app/project && chown -R 1000:1000 /home/app
WORKDIR /home/app/project
USER 1000:1000

podman build -t localhost/agent:workdir .
openshell sandbox create --name workdir-demo --from localhost/agent:workdir --detach -- sleep infinity
openshell sandbox exec --name workdir-demo -- sh -c 'pwd; printf "HOME=%s\n" "$HOME"; touch session.txt'
openshell sandbox exec --name workdir-demo -- sh -c 'test -f session.txt && echo persisted'

Output from the local Podman gateway run:

STEP 1/4: FROM ubuntu:24.04
STEP 2/4: RUN mkdir -p /home/app/project && chown -R 1000:1000 /home/app
--> 0ba43d50a066
STEP 3/4: WORKDIR /home/app/project
--> 8b55b815876e
STEP 4/4: USER 1000:1000
COMMIT localhost/agent:workdir
--> d25eb32a1b61
Successfully tagged localhost/agent:workdir
d25eb32a1b61cbcb572626e3ec08f9cf75c26e80656303ba6d4d2006e3da45b0

Created sandbox: workdir-demo

  [0.0s] Requesting compute...

/home/app/project
HOME=/home/app/project
persisted

Previously Podman used /sandbox regardless of the image's WORKDIR.

Related Issue

Fixes #2526. Supersedes the Podman approach in #2715. That earlier approach needed complex directory checks to prevent a workload image from overwriting essential supervisor binaries, because the workload and supervisor shared a container. RFC 0012 now runs them in separate containers, so those supervisor-protection checks are no longer necessary. This PR still reuses Docker's existing shared path validation; relaxing it can happen in a follow-up.

Changes

• Resolve the Podman image ID, user, environment, working directory, and declared VOLUME targets from one immutable inspection.
• Mount the persistent workspace volume at the custom path, preserving Podman's first-use copy of image-directory contents and their permissions. Start custom-workspace workloads directly as the final non-root identity.
• Reuse the existing shared path validators: reject reserved system/OpenShell paths and image or driver mounts that cover the custom workspace. Relaxing those restrictions is deferred to a follow-up PR. The /sandbox fallback keeps its previous image-volume behavior.
• Admit Podman-created, local anonymous volumes declared by the pinned image beneath a custom workspace; still reject changed volume backends and externally attached volumes without operator approval.
• Pass the resolved path to agent children as cwd and HOME; retain the managed /sandbox setup for fallback images. Pin and pass the separate supervisor image ID.
• Update Podman documentation and focused coverage. Share driver-specific mount-target validation and the image-volume admission label through openshell-core; Docker uses the same helper and label with no intended behavior change. There are no sandbox-runtime diffs.

Testing

• mise run pre-commit
• Focused shared-helper, Docker, and Podman mount-validation unit tests
• Focused Podman unit tests for private image-volume admission, declared-volume paths, and isolated container specs
• Compile the focused Podman OCI identity E2E test
• Manual Podman gateway run of the example above
• Focused Podman OCI identity E2E: 1 passed, 0 failed on the shared-helper commit in Branch E2E; the later call-site and shared-constant cleanups do not change runtime behavior

Checklist

• Conventional Commit and DCO sign-off
• Architecture and user-facing docs updated

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-3801.docs.buildwithfern.com/openshell

[github-actions]

Label test:e2e applied, but pull-request/3801 does not exist yet. A maintainer needs to comment /ok to test 2405282a3822c2abb2b19ec1867b9fda1bf54bd6 to mirror this PR. Once the mirror exists, re-apply the label or re-run Branch E2E Checks from the Actions tab.

[matthewgrossman]

/ok to test 2405282

[matthewgrossman]

/ok to test fc4d8bd