NVIDIA · matthewgrossman · Jul 30, 2026 · Jul 30, 2026 · Jul 30, 2026 · Jul 30, 2026
@@ -149,6 +149,9 @@ Common findings:
 - Gateway process stopped: inspect exit status and logs.
 - Sandbox image missing or pull denied: verify image reference and registry credentials.
 - Sandbox fails before readiness with an identity-resolution error: inspect the image's OCI `USER` and matching `/etc/passwd` and `/etc/group` entries, or explicitly set both process identity fields in policy. Root and missing identities are rejected.
+- Sandbox fails before readiness with an OCI workspace validation error: inspect the image's `WorkingDir` using the immutable image ID reported by the gateway. Empty, `/`, and explicit `/sandbox` use the managed `/sandbox` compatibility workspace. Any other workdir must be an absolute normalized directory with no symlink components; the final policy UID, primary GID, and supplementary groups must pass the kernel's effective traverse/write checks, including POSIX ACL and LSM decisions. OpenShell does not create, chown, or chmod a non-default image workdir.
+- Docker also rejects an image `VOLUME` that covers the workdir or one of its parents because the runtime would mask the immutable path before validation. Move the `VOLUME` below the workspace or remove the declaration.
+- A workdir rejected as a special filesystem or OpenShell control-path collision cannot be made valid with permissions. Move the image workdir away from kernel-backed mounts and the concrete supervisor, TLS, token, runtime, and socket paths named in the error.
 - Docker driver cannot initialize because it cannot find `openshell-sandbox`: verify `OPENSHELL_DOCKER_SUPERVISOR_BIN`, the sibling binary next to `openshell-gateway`, or the configured supervisor image contains `/openshell-sandbox`.
 - Sandbox never registers: check gateway logs and supervisor callback endpoint.
 - Supervisor image exits before printing `openshell-sandbox --version`: the image should be the scratch supervisor image from `deploy/docker/Dockerfile.supervisor` and must contain a static executable at `/openshell-sandbox`.

@@ -466,7 +466,6 @@ filesystem_policy:
     - /etc
     - /var/log
   read_write:
-    - /sandbox
     - /tmp
     - /dev/null
 

@@ -823,7 +823,6 @@ filesystem_policy:
     - /etc
     - /var/log
   read_write:
-    - /sandbox
     - /tmp
     - /dev/null
 

@@ -223,17 +223,23 @@ openshell sandbox ssh-config my-sandbox >> ~/.ssh/config
 ### Upload and download files
 
 ```bash
-# Upload local files to sandbox
-openshell sandbox upload my-sandbox ./src /sandbox/src
+# Upload local files to the sandbox working directory
+openshell sandbox upload my-sandbox ./src
 
-# Download files from sandbox
-openshell sandbox download my-sandbox /sandbox/output ./local-output
+# Download a path relative to the sandbox working directory
+openshell sandbox download my-sandbox output ./local-output
 ```
 
 Uploads honor `.gitignore` by default. Add `--no-git-ignore` only when ignored files are intentionally in scope.
 
 Uploads preserve symlinks, including dangling symlinks, instead of dereferencing their targets. A symlink source bypasses Git-aware filtering so the link itself is archived.
 
+When the upload destination is omitted, the CLI discovers the remote working
+directory. Uploading a named directory merges it into an existing directory of
+the same name, overwriting matching entries without deleting unrelated entries.
+Downloads accept paths relative to that working directory or absolute paths
+within it.
+
 ### Execute a non-interactive command
 
 ```bash

@@ -268,11 +268,11 @@ Open an interactive SSH shell. The name defaults to the last-used sandbox. `--ed
 
 ### `openshell sandbox upload <name> <path> [dest]`
 
-Upload files using tar-over-SSH. The destination defaults to the container working directory. `.gitignore` filtering is enabled unless `--no-git-ignore` is passed.
+Upload files using tar-over-SSH. The CLI discovers the canonical remote working directory when the destination is omitted. A named directory merges into an existing directory of the same name, overwriting matching entries without deleting unrelated entries. `.gitignore` filtering is enabled unless `--no-git-ignore` is passed.
 
 ### `openshell sandbox download <name> <path> [dest]`
 
-Download files using tar-over-SSH. The local destination defaults to `.`.
+Download files using tar-over-SSH. The sandbox source may be relative to the canonical remote working directory or an absolute path within it. The local destination defaults to `.`.
 
 ### `openshell sandbox ssh-config [name]`
 

@@ -185,7 +185,8 @@ The gateway preserves whether each policy process field was omitted. The active
 driver then supplies one authoritative identity input to the supervisor:
 
 - Docker and Podman inspect the final sandbox image, pin container creation to
-  its immutable image ID, and pass its raw OCI `Config.User`.
+  its immutable image ID, and pass its raw OCI `Config.User`. Docker also
+  resolves the workspace from OCI `Config.WorkingDir` during that inspection.
 - Kubernetes passes its platform-resolved numeric UID/GID, including OpenShift
   SCC-derived values.
 - VM keeps its existing guest identity behavior.
@@ -198,6 +199,23 @@ and uses the same privilege-drop path for direct and SSH children. When a
 declaration omits the group, the supervisor fills it with the user's numeric
 primary GID. It does not rewrite the account files.
 
+Docker uses an absolute OCI working directory as the workspace. An
+empty, root (`/`), or explicit `/sandbox` declaration uses `/sandbox`, which
+OpenShell creates and owns as a compatibility workspace. Any other workdir must already
+exist in the immutable image without symlink components. The completed
+identity, including supplementary groups, must already be able to traverse
+every parent and write and enter the workdir; OpenShell does not change that
+directory's ownership or mode. A one-shot validator drops to that identity and
+uses kernel effective-access checks so POSIX ACL and LSM decisions are honored.
+Filesystem metadata identifies kernel-managed
+mounts, while collision checks are derived from actual OpenShell control paths.
+Docker performs the check in the final container before workload launch and
+rejects image `VOLUME` declarations that would mask the workdir ancestry. The
+resolved workspace is the child cwd and `HOME`; when
+`filesystem.include_workdir` is enabled, it becomes the automatic writable
+policy path. Podman, Kubernetes/OpenShift, and VM retain their existing
+`/sandbox` workspace behavior.
+
 Sandbox creation fails before the workload becomes ready when a required image
 identity is absent, malformed, unknown, ambiguous, or resolves to UID/GID 0.
 The supervisor itself remains root so it can establish isolation before