docs(sandboxes): add sandbox environments section (sbx env, experimental) - #25487
Open
dvdksn wants to merge 19 commits into
Open
docs(sandboxes): add sandbox environments section (sbx env, experimental)#25487dvdksn wants to merge 19 commits into
dvdksn wants to merge 19 commits into
Conversation
Adds a new "Sandbox environments" section documenting the declarative `.sbxenv.yaml` configuration format and `sbx env` commands (run, create, rm). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
✅ Deploy Preview for docsdocker ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
docker-agent
reviewed
Jul 3, 2026
docker-agent
left a comment
docker-agent
left a comment
Contributor
There was a problem hiding this comment.
Assessment: 🟡 NEEDS ATTENTION
This PR adds a new Sandbox environments section (~158 lines) to workflows.md documenting the experimental sbx env feature. The structure is clear and the YAML examples look correct. A few style-guide issues were found in the newly added content.
Moves sbx env content from workflows.md into its own page (sandbox-environments.md) with a proper per-field YAML reference. Leaves a one-line pointer in workflows.md. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- agent: mark as required (Validate() enforces non-empty) - pullPolicy: correct default to "always" (pullPolicyOrDefault helper) - registries: clarify secret required, username optional; note token-only support Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Remove undocumented docker-credential-desktop registry example - Improve plaintext secret warning to suggest variable interpolation - Remove prose em dashes Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ts page Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…v-v039 # Conflicts: # content/manuals/ai/sandboxes/workflows.md
The draft reference omitted supported commands and schema fields and misstated interpolation and cleanup behavior. Update it against docker/sandboxes release/v0.39 and resolve the workflows conflict with current main.\n\nCo-Authored-By: Codex <noreply@openai.com>
Clarify the lifecycle, cleanup, MCP, and local-only behavior of declarative sandbox environments. Vendor the generated v0.39 sbx env CLI reference and link the guide to it. Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
The experimental environment-file workflow was only discoverable from the workflow guide. Add a concise link in the get-started next steps with its v0.39 availability requirement. Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
The page opened with an ancillary workspace-location case before showing the feature's primary workflow. Lead with a project-local web application example, explain the problem it solves, and remove the redundant local-sandbox qualifier. Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
The environment file page moved from one example directly into command and schema reference material. Add four task-oriented recipes for shared project setup, personal overrides, multi-repository work, and automation, then separate update and cleanup behavior into dedicated sections. Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Variable interpolation is scheduled to be superseded after v0.39 and should not be promoted as a lasting workflow. Remove its authored guide section and the interpolation suggestion from the secret warning while preserving generated v0.39 CLI reference data. Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Introduce the minimum valid configuration before the workflow gallery, explain the command and update lifecycle earlier, and separate resource-scope and failed-create cleanup guidance. Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
The minimum schema example did not demonstrate why a project would share an environment file. Use a Playwright kit and shared environment variable, and move detailed exec syntax into the automation workflow where it becomes relevant. Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
The exec delimiter explanation interrupted a use-case-oriented workflow with command parsing details. Remove the duplicate explanation because the generated exec reference already documents the syntax and examples. Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
The update lifecycle section interrupted the introductory path from basic usage to motivating examples. Move the full explanation after the workflow gallery and retain a concise linked warning in the run command description. Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
The complete-project workflow repeated the introductory Playwright example without adding a distinct use case. Remove it and preserve its kit source, allowlist, and pinning guidance in a dedicated kits reference section. Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
The starter example showed shared tools and environment variables but omitted how a development service reaches the host. Add an explicit port mapping and describe its effect without implying that sbx starts the service. Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
dvdksn
marked this pull request as ready for review
August 14, 2026 12:05
docker-agent
left a comment
docker-agent
left a comment
Contributor
There was a problem hiding this comment.
Assessment: 🟡 NEEDS ATTENTION
Vendored files: The data/sbx_cli/*.yaml files are generated CLI reference data — no inline comments on those.
Hand-authored docs: One medium-severity clarity issue found in the new sandbox-environments.md page. See inline comment.
docker-agent
left a comment
docker-agent
left a comment
Contributor
There was a problem hiding this comment.
Assessment: 🟡 NEEDS ATTENTION
This PR adds a well-structured Sandbox environment files page along with updates to the get-started and workflows docs. The content is detailed and technically accurate. Two items flagged for attention:
- Vendored YAML files — the five
data/sbx_cli/sbx_env*.yamlfiles follow the generated CLI reference pattern; per project conventions these should come from an upstream sync rather than hand-authoring. - Ambiguous field description —
noVerify's description uses once in a way that may confuse readers about whether the field skips a single attempt or the entire provisioning-time resolution.
docker-agent
left a comment
docker-agent
left a comment
Contributor
There was a problem hiding this comment.
Assessment: 🟡 NEEDS ATTENTION
This PR adds a well-structured sandbox environments page, updates get-started and workflows cross-references, and vendors five CLI reference YAML files under data/sbx_cli/.
Note on vendored files: The five data/sbx_cli/*.yaml files (sbx_env.yaml, sbx_env_create.yaml, sbx_env_exec.yaml, sbx_env_rm.yaml, sbx_env_run.yaml) are generated CLI reference data synced from upstream. Per project policy, content edits to these files should be made upstream and synced back — they are not reviewed here for wording or content quality.
Two clarity issues were found in the hand-authored sandbox-environments.md:
- Re-run behavior wording (line 66) — the table cell "apply only
envand MCP changes" may not clearly signal that other changes are silently skipped (not queued) and requiresbx env rm+ recreate. cpus: 0description (line 267) — "automatic value" does not tell users whether0means no limit, a platform default, or a dynamic choice.
See inline comments for details.
Review feedback identified ambiguous descriptions for re-run updates, noVerify, and the zero CPU value. State the recreation requirement, provisioning-time resolution behavior, and host CPU allocation explicitly. Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
cdupuis
approved these changes
Aug 14, 2026
akristen
approved these changes
Aug 14, 2026
akristen
left a comment
akristen
left a comment
Contributor
There was a problem hiding this comment.
i might consider separating reference from crud procedures, but that's personal preference. otherwise lgtm!
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
4 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
.sbxenv.yamlschema and all foursbx envcommands (run,create,exec, andrm)sbx envCLI reference and links each command from the guide🤖 Updated with Codex