feat(sandbox): honor OCI image working directories

[matthewgrossman]

Summary

Docker and Podman now honor a usable OCI Config.WorkingDir as the sandbox workspace, with an OpenShell-created /sandbox fallback for empty or root declarations. The resolved workspace is used consistently by drivers, the supervisor, filesystem policy, SSH transfers, and editor launch while Kubernetes/OpenShift and VM retain /sandbox.

This is a stacked PR on top of #2509.

Related Issue

Closes #2526

Changes

• inspect WorkingDir with User from the same immutable Docker/Podman image and pass the resolved root through the existing supervisor workdir argument
• prepare and chown only the workspace root for the final local-container identity, without recursively changing image content or nested mounts
• mount Podman persistence at the resolved root and reserve that exact root from driver-config mounts
• use filesystem.include_workdir instead of automatically granting literal /sandbox
• discover the canonical remote workspace over SSH for upload defaults, download containment, and editor launch
• preserve fixed /sandbox behavior for Kubernetes/OpenShift and VM
• update architecture, driver, policy, CLI, and agent guidance

Testing

• mise run pre-commit passes
• mise run test passes
• Unit tests added/updated
• E2E tests added/updated (if applicable)
• Docker custom_image E2E passes (OCI WorkingDir, fallback, direct/SSH, transfers)
• Docker driver_config_volume E2E passes (nested volume ownership)
• Podman inspect/spec/copy-up behavior covered by unit tests; live Podman was unavailable locally

Checklist

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

[github-actions]

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

[drew]

gator-agent

Blocked

Gator is blocked because PR #2530 currently has merge conflicts (mergeStateStatus: DIRTY) against its base branch.

Next action: @matthewgrossman, please rebase or merge the base branch and resolve the conflicts, then push an updated head SHA so gator can run the independent review.

[drew]

gator-agent

PR Review Status

Validation: PR #2530 implements linked issue #2526, which is already marked state:agent-ready / state:pr-opened, and the current head is open, ready for review, and no longer conflict-blocked.
Head SHA: 493abe06869d41a5b161a1a97abc21c0c3ce6436

Review findings:

• Warning: Docker/Podman pass the resolved workspace to the supervisor, but the create specs still appear to inherit the image process cwd. For hand-crafted OCI images where Config.WorkingDir is missing on disk or is not a directory, the container runtime may fail before the supervisor can run the intended workspace validation/preparation path. Please consider starting the supervisor from a known-safe cwd such as / while passing --workdir <resolved-root> separately, and add coverage for missing/non-directory WorkingDir.
• See the inline warning about accepting whitespace/control-character OCI WorkingDir values before SSH discovery and shell-text flows consume the path.

Docs: Fern docs and relevant agent skill guidance were updated; no docs navigation change appears required because no new page was added.

Next state: gator:in-review

[github-actions]

Label test:e2e applied for 41b25a7. 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 and supervisor images once. The matching required CI gate status on this PR will flip green automatically once the run finishes.

[drew]

gator-agent

PR Review Status

Validation: PR #2530 implements linked issue #2526, which is already marked state:agent-ready / state:pr-opened. The PR is open, ready for review, and no longer conflict-blocked.
Head SHA: 41b25a7415a4b502412b5e92926ac9730deac14f

Review findings:

• No blocking findings remain from the independent review.
• The previous gator ledger item about whitespace/control-character OCI WorkingDir handling appears addressed in this head.

Docs: Fern docs and relevant agent skill guidance were updated; no docs navigation change appears required because no new page was added.

E2E: Applied test:e2e because this change affects sandbox lifecycle, policy behavior, Docker/Podman driver behavior, and SSH transfer/editor workspace behavior.

Checks: Required checks are not green yet. OpenShell / Branch Checks is still in progress; the Rust jobs are currently failing, but the run is still active and failed logs are not available until it completes, so gator will classify the failure on the next reconciliation cycle.

Next state: gator:watch-pipeline

[drew]

gator-agent

PR Review Status

Validation: PR #2530 implements maintainer-authored, agent-ready issue #2526 and remains open, non-draft, mergeable, and project-valid.
Head SHA: 6bafbb649530f60871f7b4a545a6c56bfde5ead0

Review findings:

• One warning remains about guaranteeing that an existing OCI workspace is writable after ownership preparation; see the inline comment.
• The prior whitespace/control-character OCI WorkingDir finding remains addressed and was not re-raised.

Docs: Fern docs and relevant agent skill guidance are updated; no navigation change is needed because no page was added.

E2E: test:e2e remains appropriate for the sandbox lifecycle, policy, Docker/Podman, and SSH workspace changes.

Next state: gator:in-review

[drew]

gator-agent

PR Review Status

Validation: PR #2530 implements maintainer-authored, agent-ready issue #2526 and remains open, non-draft, mergeable, and project-valid.
Head SHA: ad58a35413db4717d8d487b782d2f45465d9bd18

Review findings:

• One warning remains about guaranteeing that an existing OCI workspace is writable after ownership preparation; see the inline comment.
• The new head addresses the SSH connection-limit path, but it does not change the workspace ownership/preparation code behind the unresolved warning.
• The prior whitespace/control-character OCI WorkingDir finding remains addressed and was not re-raised.

Docs: Fern docs and relevant agent skill guidance are updated; no navigation change is needed because no page was added.

E2E: test:e2e remains appropriate for the sandbox lifecycle, policy, Docker/Podman, and SSH workspace changes.

Next state: gator:in-review

[drew]

gator-agent

PR Review Status

Validation: PR #2530 implements agent-ready issue #2526 and remains open, non-draft, mergeable, and project-valid.
Head SHA: ccba5bb168afa4d7b554bb1b42b121871c745fd0

Thanks @matthewgrossman. I checked your latest replies against the current diff: the whitespace/control-character validation and existing 0555 workspace permission findings are resolved and were not re-raised.

Review findings:

• Three distinct warnings remain; see the inline comments for the Docker pre-inspection mount check, inaccessible workspace ancestors, and incomplete protection of system paths selected through OCI WorkingDir.

Docs: Fern docs and the relevant generate-sandbox-policy / openshell-cli skill guidance are updated; no navigation change is needed because no page was added or moved.

E2E: test:e2e remains appropriate for the sandbox lifecycle, policy, Docker/Podman, and SSH workspace changes.

Next state: gator:in-review

[drew]

gator-agent

PR Review Status

Validation: PR #2530 implements agent-ready issue #2526 and remains open, non-draft, mergeable, and project-valid.
Head SHA: babd6ba679067f40eaacbf5bfad4a65283e4acaa

Thanks @matthewgrossman. I checked your current-head replies against the diff: the Docker placeholder-metadata mount collision, inaccessible 0700 ancestor case, and protected-system-tree coverage are addressed and were not re-raised.

Review findings:

• One distinct warning remains for workspace ancestors traversable only through a named user's supplementary groups; see the inline comment.
• One docs wording correction is suggested; see the inline comment.

Docs: Relevant Fern docs and agent skill guidance are updated, and no navigation change is needed because no page was added or moved. The baseline-filesystem wording should be qualified as noted inline.

E2E: test:e2e remains appropriate for the sandbox lifecycle, policy, Docker/Podman, SSH, transfer, and editor-workspace changes.

Next state: gator:in-review

[drew]

gator-agent

PR Review Status

Validation: PR #2530 implements agent-ready issue #2526 and remains open, non-draft, mergeable, and project-valid.
Head SHA: 7cd2bbc692e76363d6359e5cd9986dc98463272a

Thanks @matthewgrossman. I checked your current-head replies and changes for the supplementary-group-only workspace ancestor and the filesystem.include_workdir documentation wording. Both are addressed, and the durable earlier findings were not re-raised.

Review findings:

• No blocking findings remain from the independent code-only review.

Docs: Relevant Fern docs and agent skill guidance are updated; no navigation change is needed because no page was added or moved.

E2E: test:e2e remains appropriate for the sandbox lifecycle, policy, Docker/Podman, SSH, transfer, and editor-workspace changes.

Checks: OpenShell / Branch Checks, OpenShell / Helm Lint, and OpenShell / GPU E2E are green. OpenShell / E2E is still pending.

Next state: gator:watch-pipeline