docs(sandboxes): add sandbox environments section (sbx env, experimental)#25487
docs(sandboxes): add sandbox environments section (sbx env, experimental)#25487dvdksn wants to merge 5 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
left a comment
docker-agent
left a comment
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.
| $ sbx env run base.sbxenv.yaml local.sbxenv.yaml | ||
| ``` | ||
|
|
||
| A common pattern is to commit a `base.sbxenv.yaml` with shared configuration |
There was a problem hiding this comment.
[MEDIUM] Meta-commentary: 'A common pattern is to'
The phrase "A common pattern is to" is meta-commentary — it adds no informational value and should be replaced with a direct statement. The Docker style guide flags this alongside phrases like "It's worth noting that" and "Keep in mind that."
Suggested rewrite:
Commit a
base.sbxenv.yamlwith shared configuration and addlocal.sbxenv.yamlto.gitignorefor personal overrides — a different workspace path, additional secrets, or adjusted resource limits.
|
|
||
| > [!WARNING] | ||
| > Avoid `secrets.<name>.value` for real credentials. The value is plaintext | ||
| > and visible to anyone with read access to the file. Use `ref` (vault URI) |
There was a problem hiding this comment.
[MEDIUM] Parentheses in warning callout: '(vault URI)'
The Docker style guide says to avoid parentheses in technical documentation as they reduce readability. The phrase "ref (vault URI)" should be rewritten without parentheses.
Suggested rewrite:
Use
reffor vault URIs orcommandinstead.
| ### Multiple files | ||
|
|
||
| `sbx env run` accepts multiple paths and deep-merges them in order. Later | ||
| files override scalar values and lists concatenate, following the same |
There was a problem hiding this comment.
[MEDIUM] Verify merge semantics claim matches actual behavior
The text states "Later files override scalar values and lists concatenate, following the same semantics as Docker Compose's multiple -f files."
Docker Compose's list merge behavior is nuanced — for many keys, lists are overridden (not concatenated) depending on the key. If sbx env behavior differs from Compose in any way, this comparison could mislead users. Worth verifying the claim is accurate, and if the semantics differ from Compose's actual behavior, consider describing them directly rather than by analogy.
| A sandbox _environment file_ describes a sandbox configuration in code — | ||
| agent type, kits, workspace, secrets, ports, and resource limits. Check one | ||
| into your repository and every team member can launch an identical sandbox | ||
| with a single command, without repeating the same `sbx run` flags. Kits and |
There was a problem hiding this comment.
[MEDIUM] Borderline hedge phrase: 'with a single command'
"With a single command" is a mild ease-of-use claim, similar to "simply" or "easily," which the style guide discourages. While it's technically factual (one command is run), phrasing it this way emphasizes ease rather than describing the mechanism.
Suggested rewrite:
Check one into your repository and every team member can run
sbx env run, without repeating the samesbx runflags.
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>
2 participants
Summary
sbx envfeature.sbxenv.yamldeclarative config format, the three commands (run,create,rm), multiple-file merging, and variable interpolation[!NOTE]callout🤖 Generated with Claude Code