docs: document mountless sandbox workspaces - #25902
Merged
Merged
Conversation
✅ Deploy Preview for docsdocker ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
aevesdocker
reviewed
Aug 28, 2026
aevesdocker
approved these changes
Aug 28, 2026
dvdksn
added a commit
that referenced
this pull request
Sep 7, 2026
## Summary Document the v0.42 sandbox-kit positional for `sbx run` and `sbx create`, reserve `--kit` for mixins, and add the kit argument declaration, scoping, precedence, and validation rules. Correct the `extends:` inheritance details and `sbx kit push` registry authentication behavior. This touches separate sections of files also changed by #25833, #25895, and #25902, but has no merge dependency on those PRs. @netlify /ai/sandboxes/customize/kits/ Preview: [Kits](https://deploy-preview-25951--docsdocker.netlify.app/ai/sandboxes/customize/kits/) · [Kit spec reference](https://deploy-preview-25951--docsdocker.netlify.app/ai/sandboxes/customize/kit-reference/) Generated by Codex --------- Co-authored-by: Codex <noreply@openai.com>
Starting with sbx 0.40.0, omitting the workspace path creates a sandbox without a host workspace bind mount instead of mounting the current directory. Explain mountless, direct, and clone workspace behavior, and update project-oriented examples to pass an explicit path. This addresses docker/sbx-releases#466.
Agent-argument examples used workspace-based creation syntax even though they continue an existing sandbox session. Use sbx run --name for continuation examples and retain explicit workspace paths only where the command creates a sandbox.
Users upgrading to sbx 0.40.0 may create a mountless sandbox through the previous bare run syntax and expect to see their host project. Explain the mountless default, show how to mount the current directory, and describe safe recreation of an existing named sandbox.
Document that sbx run retains its implicit current-directory mount, while sbx create without workspace paths creates a mountless sandbox. Restore pathless run examples where the mount is not load-bearing.
Link agent pages directly to the mountless workspace explanation and use sbx run for direct-mounted troubleshooting examples.
Rely on the sbx run current-directory default in direct-mode examples while retaining explicit paths for clone mode.
Explain that built-in agent images declare /home/agent/workspace as WORKDIR and that the daemon uses the same path as a fallback when image config has no usable absolute WORKDIR.
Kit install commands do not choose /home/agent/workspace themselves; they inherit the template image working directory. Clarify that the Docker-provided built-in agent images configure that path.
dvdksn
force-pushed
the
codex/document-mountless-workspaces
branch
from
September 7, 2026 10:55
f188a07 to
8b3e6ec
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents the v0.42.0 workspace behavior for Docker Sandboxes:
sbx runcontinues to mount the current directory when no path is provided, whilesbx createaccepts zero workspace paths and creates a mountless sandbox when they are omitted.Explains the mountless working directory and persistence model, keeps explicit paths where a project workspace is load-bearing, uses named attachment for existing sandboxes, and adds troubleshooting for sandboxes created without project files.
The generated CLI reference will receive the matching upstream help text when v0.42.0 is vendored.
Closes docker/sbx-releases#466
Generated by Codex