feat(podman): honor OCI image working directories

[matthewgrossman]

Summary

Podman sandboxes now use an image's custom WORKDIR as the agent workspace, as Docker already does. Images without a custom working directory still use the managed /sandbox volume. Docker behavior does not change.

This is the last of three stacked PRs split out of #3801 (#3931 ← #3932 ← this PR), and it supersedes #3801.

Why this matters

An image can set WORKDIR /home/app/project and prepare that directory with files and permissions for its user. Today, a Podman sandbox ignores that choice and puts the agent in /sandbox instead. Files the image placed in its working directory are not in the agent's workspace, so commands and uploads can go to the wrong place. Docker already works from the image's chosen directory.

With this change, Podman keeps a custom workspace in the image's own filesystem rather than mounting a new volume over it. That preserves the image's files and ownership; OpenShell does not create the directory or grant the user new access. If the image leaves WORKDIR unset, sets it to /, or chooses /sandbox, the existing managed-volume behavior remains, with the ownership fix from #3932.

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; touch session.txt'
openshell sandbox exec --name workdir-demo -- sh -c 'test -f session.txt && echo persisted'

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

Related Issue

Fixes #2526. Supersedes #3801 and the Podman approach in #2715, which needed extra directory checks because the workload and supervisor shared a container. RFC 0012 runs them in separate containers, so those checks are no longer needed.

Follow-ups kept out of this PR:

• feat: define cross-runtime agent HOME behavior #3873: cross-runtime HOME contract.
• bug(podman): resource admission rejects image-declared VOLUMEs; lacks Docker parity #3890: Podman resource admission for image-declared VOLUMEs, with Docker parity.

Changes

• Resolve the Podman image ID, user, environment, and working directory from one pinned image inspection (ResolvedPodmanImage).
• Keep a custom workspace in the image's container filesystem: no workspace volume, no archive upload, and no root setup step. The workload starts as the final non-root user, and the existing sandbox-runtime check still requires that user to be able to traverse and write the directory.
• Validate a custom workdir with the shared OCI rules, and reject Podman control-path overlaps (/.openshell, supervisor CA runtime root). Reject image VOLUMEs or driver mounts that cover the workspace; mounts nested below it remain valid.
• Pass the resolved path to agent commands via --workdir. Start the runtime from / so Podman neither creates a missing WORKDIR nor fails to chdir into it before OpenShell validates it.
• Run the oci-image suite on fedora-podman-rootful and fedora-podman-rootless in branch E2E and both release workflows (Docker was added by the base PR). Add podman_oci_identity to the Podman CI test list, and give its image a custom WORKDIR with no workspace mounts.
• Trim podman_oci_identity to the checks only Podman can make: the pinned image ID and the isolated workload/supervisor container pair (users, capabilities, networking, mounts). The identity seen by the main process and sandbox exec is covered by the shared suite on both runtimes.
• Update the Podman README, runtime docs, debug skill, and TESTING.md.

Testing

All checks ran against a local rootful Podman machine (macOS, libkrun). Rootless coverage comes from the fedora-podman-rootless CI lane that this PR adds.

• mise run pre-commit passes
• Unit tests: cargo test -p openshell-driver-podman --lib (230 passed), covering the workspace spec, custom vs. managed launch, and image volumes and driver mounts that cover the workdir. cargo clippy -p openshell-driver-podman --all-targets -- -D warnings is clean.
• Feature tests: the full oci-image suite passes 4/4 through e2e/with-podman-gateway.sh, including the WorkspaceValidationFailed reason for an unwritable WORKDIR.
• E2E: the trimmed podman_oci_identity passes.

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (if applicable)

[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-3933.docs.buildwithfern.com/openshell

[matthewgrossman]

/ok to test b9ab37e

[github-actions]

Label test:e2e applied for b9ab37e. Open the existing run and click Re-run all jobs to execute with the label set. The run will execute the standard E2E suite after building the required gateway, sandbox, and supervisor images once. The matching required CI gate status on this PR will flip green automatically once the run finishes.

[elezar]

Custom-workdir sandboxes now skip workspace-volume creation, but the provisioning cleanup and delete paths still remove the deterministic workspace-volume name unconditionally. This can delete a volume that was never created or ownership-verified by this sandbox. Guard failure cleanup with managed_workspace, and make deletion inspect and verify the OpenShell sandbox ownership labels before removing a workspace volume; label verification also preserves cleanup for volumes created by older gateways.

[matthewgrossman]

GitHub automatically marked this PR merged when its reordered head became an ancestor of its old base during stack maintenance. The change has not landed on main. Replacement draft PR: #3982, in the new stack #3983.