feat: honor OCI WorkingDir for Docker and Podman workspaces
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 8.7k
- Forks
- 1.3k
- Avg merge
- 2d 11h
- Merged PRs (30d)
- 253
Description
Problem Statement
Follow-up to #2331 and stacked on #2509.
#2331 removes the requirement for Docker and Podman images to contain a
sandbox:sandbox account, but intentionally keeps /sandbox as OpenShell's
fixed workspace. OCI images can already declare their intended workspace with
Config.WorkingDir; ignoring it means off-the-shelf images may still require
OpenShell-specific /sandbox preparation, and direct sessions, SSH sessions,
filesystem policy, persistence, transfers, and editor launch can disagree about
the effective workspace.
Docker and Podman should honor the image-declared working directory without
changing Kubernetes/OpenShift or VM workspace behavior.
Proposed Design
Introduce one internal resolved workspace root and use it consistently across
the local container drivers, supervisor, policy runtime, and SSH-based CLI
operations.
Resolution
- Docker and Podman inspect OCI
Config.WorkingDiralongsideConfig.User
from the same immutable image inspected by #2331. - Use a normalized absolute
WorkingDirwhen it is non-empty and not/. - For an empty or
/declaration, use/sandboxas an OpenShell-created
fallback. The image does not need to contain or pre-own it. - Reject malformed non-empty declarations, including relative paths. Reject a
workspace root that resolves to a symlink, non-directory, or otherwise
cannot be safely created and owned. - Kubernetes/OpenShift and VM continue resolving their workspace root to
/sandbox.
This is an internal runtime decision, not a new public setting or gateway
configuration field.
Runtime behavior
- Pass the resolved root through the supervisor's existing workdir mechanism;
do not add a new supervisor flag or identity protocol. - Prepare the resolved directory for the final effective UID/GID before
readiness. - Use the same root as the cwd and workspace HOME for direct and SSH children.
- Feed the resolved root to Landlock when
filesystem.include_workdiris true. - Stop automatically injecting literal
/sandboxas a baseline filesystem
path. User-authored policy entries that explicitly name/sandboxremain
literal and are never rewritten.
Driver behavior
- Pin both identity and workspace resolution to the immutable image ID already
inspected by Docker and Podman. - Mount Podman's managed workspace volume at the resolved root instead of
unconditionally at/sandbox. - Reserve the resolved workspace root from Docker/Podman driver-config mounts
after image inspection. Preserve all other mount behavior. - Confirm and preserve Podman named-volume copy-up behavior when
WorkingDir
already contains image files.
CLI behavior
Use the existing SSH connection to discover the canonical remote workspace with
pwd -P; avoid adding a public workspace_root status field unless a
non-SSH consumer proves it necessary.
- Download containment and symlink checks use the discovered root rather than
a hardcoded/sandbox. - Upload without an explicit destination extracts into the discovered root
rather than relying on SSH~. - Editor launch opens the discovered remote root.
Alternatives Considered
- Recursively chown
/sandbox: rejected in #2509. It mutates image content,
risks crossing ownership boundaries, and treats the symptom rather than
honoring OCI workspace metadata. - Always use
/sandbox: retained only as the empty//fallback. It
preserves compatibility but should not override a usable OCIWorkingDir. - Use the OCI user's account home as fallback: rejected because Podman must
choose its managed-volume target before the supervisor can resolve
/etc/passwd. A driver-known fallback is simpler and deterministic. - Add a public gateway
workspace_rootfield: avoid initially because the
affected CLI operations already establish SSH sessions and can discover the
canonical cwd directly. - Rewrite user-authored
/sandboxpolicy paths: rejected. Explicit policy
paths must retain their literal meaning.
Definition of Done
- Docker and Podman use a valid OCI
WorkingDir, with driver-created
/sandboxfallback for empty or/. - Direct and SSH children share the resolved cwd/HOME and can write there.
-
include_workdirgrants the resolved root without rewriting explicit
policy paths. - Podman persistence mounts at the resolved root and preserves expected
image-content copy-up. - Driver-config mounts cannot replace the resolved workspace root.
- Upload defaults, download containment, and editor launch use the
SSH-discovered workspace root. - Kubernetes/OpenShift and VM retain their current
/sandboxbehavior. - No public workspace setting, gateway schema field, or new supervisor
launch flag is introduced.
Test Plan
- OCI
WorkingDir: absolute named path, absent,/, relative, malformed,
missing, pre-populated, symlink, non-directory, and read-only. - Driver-owned fallback works without image-prepared
/sandbox. - Direct and SSH identity, cwd, HOME, and write behavior agree.
- Landlock
include_workdirfollows the resolved root; explicit/sandbox
remains literal. - Podman persistence and copy-up target the resolved root.
- Nested/user mounts retain their ownership and existing behavior.
- Upload, download traversal/symlink protection, and editor launch use the
discovered root. - Kubernetes/OpenShift and VM regression coverage remains unchanged.
Agent Investigation
- Searched open and closed issues; found no duplicate OCI WorkingDir proposal.
- Docker's
DockerImageMetadataand Podman'sImageInspectalready bind OCI
Config.Userto immutable image launch, soConfig.WorkingDircan be read in
the same inspection. - The supervisor already accepts and threads a workdir through direct process
launch, SSH process launch, and Landlock preparation. - Podman's managed workspace volume is currently hardcoded to
/sandbox. - Mount validation currently reserves literal
/sandbox. - CLI download guards and editor launch currently hardcode
/sandbox; upload
without a destination currently relies on the SSH home directory.
Scope Boundaries
Do not redesign OCI identity from #2331, add a public workspace setting, change
Kubernetes PVC/fsGroup behavior, change VM guest initialization, or fold this
work back into #2509.
Checklist
- I've reviewed existing issues and the architecture docs
- This is a design proposal, not a "please build this" request
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by tracing DockerImageMetadata and Podman ImageInspect through the local drivers, then follow the supervisor's existing workdir path into direct launch, SSH launch, and Landlock preparation. Review the CLI download, upload, and editor entry points alongside mount validation. Done means Docker and Podman consistently honor a safe OCI WorkingDir while Kubernetes, OpenShift, and VM behavior remains unchanged.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker, rust
- Domain
- backend, cli, devops, security
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100