User Story
As a user building a custom sandbox image, I want the documented image requirements to match what OpenShell actually needs, so that I don't add packages or configuration the runtime no longer uses.
Problem Statement
Since the RFC 0012 sandbox architecture (#2942), plus #3386 and #3214, the workload image requirements in the docs no longer match the code:
| Doc |
Says |
Code on main (5acaaba19) |
examples/bring-your-own-container/README.md:79 and Dockerfile:11-14 |
Install iproute2 for network namespace isolation; nftables enables bypass detection |
#2942 removed crates/openshell-supervisor-process/src/netns/. No crate outside tests runs ip, nft, nsenter, or dmesg. The workload runs with networking off (crates/openshell-driver-podman/README.md: "No nftables or nested network namespace setup runs in the sandbox"), and raw or kernel sockets are blocked by seccomp (crates/openshell-sandbox/src/sandbox/linux/seccomp.rs) |
examples/bring-your-own-container/README.md:72-75, docs/how-it-works/sandboxes/runtimes.mdx:291 |
Docker and Podman images without USER must set run_as_user/run_as_group in policy |
Both drivers fall back to UID/GID 1000 (crates/openshell-driver-docker/src/lib.rs:650, crates/openshell-driver-podman/src/container.rs:628, from #3386) |
docs/how-it-works/sandboxes/runtimes.mdx:85 |
"Docker is also required to build sandbox images from local directories or Dockerfiles" |
The CLI no longer builds images (#3214) |
examples/bring-your-own-container/README.md:76-77 |
Create /sandbox "until OCI working-directory support is added" |
Docker now uses the image WORKDIR (runtimes.mdx:295); Podman, Kubernetes, and VM use /sandbox |
Related: #3280 and #2382 describe the supervisor running ip/nft/dmesg from the workload image. That code was removed in #2942, so both issues may now be obsolete.
Impact / Why This Matters
The BYOC example is the reference for building custom sandbox images. Users following it:
- add
iproute2 and nftables to every image for no benefit;
- believe USER-less base images need policy changes;
- expect Dockerfile builds that the CLI no longer does.
Downstream distributions that copy these requirements into their own docs spread the same errors. The workaround is reading the driver and sandbox source, which most image authors won't do.
Acceptance Criteria
Reproduction Steps
- Read
examples/bring-your-own-container/README.md ("Running your own app") and docs/how-it-works/sandboxes/runtimes.mdx ("Sandbox User Identity").
- Compare with the code references in the table above.
Verified by code inspection on main at 5acaaba19 and in release v0.1.2. I have not run an end-to-end test with an image that lacks iproute2, nftables, and USER. It would be worth confirming on each in-tree driver, and checking that no extension driver still needs these tools.
Environment
- OpenShell:
main at 5acaaba19, v0.1.2
- Runtime: Docker, Podman, Kubernetes, VM (docs issue, driver-independent)
User Story
As a user building a custom sandbox image, I want the documented image requirements to match what OpenShell actually needs, so that I don't add packages or configuration the runtime no longer uses.
Problem Statement
Since the RFC 0012 sandbox architecture (#2942), plus #3386 and #3214, the workload image requirements in the docs no longer match the code:
main(5acaaba19)examples/bring-your-own-container/README.md:79andDockerfile:11-14iproute2for network namespace isolation;nftablesenables bypass detectioncrates/openshell-supervisor-process/src/netns/. No crate outside tests runsip,nft,nsenter, ordmesg. The workload runs with networking off (crates/openshell-driver-podman/README.md: "No nftables or nested network namespace setup runs in the sandbox"), and raw or kernel sockets are blocked by seccomp (crates/openshell-sandbox/src/sandbox/linux/seccomp.rs)examples/bring-your-own-container/README.md:72-75,docs/how-it-works/sandboxes/runtimes.mdx:291USERmust setrun_as_user/run_as_groupin policycrates/openshell-driver-docker/src/lib.rs:650,crates/openshell-driver-podman/src/container.rs:628, from #3386)docs/how-it-works/sandboxes/runtimes.mdx:85examples/bring-your-own-container/README.md:76-77/sandbox"until OCI working-directory support is added"WORKDIR(runtimes.mdx:295); Podman, Kubernetes, and VM use/sandboxRelated: #3280 and #2382 describe the supervisor running
ip/nft/dmesgfrom the workload image. That code was removed in #2942, so both issues may now be obsolete.Impact / Why This Matters
The BYOC example is the reference for building custom sandbox images. Users following it:
iproute2andnftablesto every image for no benefit;Downstream distributions that copy these requirements into their own docs spread the same errors. The workaround is reading the driver and sandbox source, which most image authors won't do.
Acceptance Criteria
iproute2ornftablesas requirements.runtimes.mdxdescribe the UID/GID 1000 fallback for images withoutUSERon Docker and Podman.runtimes.mdxno longer says Docker is needed to build images from Dockerfiles./sandboxguidance matches the DockerWORKDIRbehavior described inruntimes.mdx.Reproduction Steps
examples/bring-your-own-container/README.md("Running your own app") anddocs/how-it-works/sandboxes/runtimes.mdx("Sandbox User Identity").Verified by code inspection on
mainat5acaaba19and in release v0.1.2. I have not run an end-to-end test with an image that lacksiproute2,nftables, andUSER. It would be worth confirming on each in-tree driver, and checking that no extension driver still needs these tools.Environment
mainat5acaaba19, v0.1.2