sandboxes: clarify --kit scope, private images, and aws credentials#24958
Merged
dvdksn merged 10 commits intodocker:mainfrom May 6, 2026
Merged
sandboxes: clarify --kit scope, private images, and aws credentials#24958dvdksn merged 10 commits intodocker:mainfrom
dvdksn merged 10 commits intodocker:mainfrom
Conversation
The mixin example uses `sbx run --kit` first. The note that --kit only applies on create lives further down, so users were trying to apply mixins to existing sandboxes and bouncing off the CLI error. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
✅ Deploy Preview for docsdocker ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
The image-pull credential resolver authenticates with the user's sbx login session for Docker Hub references and falls back to anonymous for everything else. So private templates and kits on ghcr.io, ECR, Nexus, and similar fail to pull silently. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ices The aws credential source in the sandbox kit specs only reads AWS_ACCESS_KEY_ID; AWS_SECRET_ACCESS_KEY is not recognized today. Listing it in the table misled users who tried to authenticate Bedrock with key/secret pairs or STS tokens and silently got only the access key id. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This reverts commit 8a652d0.
Per-session /permissions only works for Claude Code and resets every session. Document the agent-kit override pattern so users who want approval prompts as the default have a recipe that survives sandbox recreation and works regardless of agent. Closes docker/sbx-releases#47. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
First-time users repeatedly bounce off one question: what's the relationship between templates and kits, and when do I use which? The existing "When to use which" table on the customize landing page gives goal-to-option mapping but doesn't define each, name the connection point (a kit's agent.image is a template), or say that they compose. Add a "Templates and kits, side by side" section that does. Refs docker/sbx-releases#103 (the templates-vs-kits part). The same issue calls out confusion about how kit credentials wire to sbx secret set vs host env vars vs sbx secret set-custom. That's a broader rewrite of the kits credentials section and is being deferred to a separate change. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…-custom The kits page split authenticated-service wiring across two adjacent subsections — "Control network access" carried the serviceDomains/serviceAuth example, and "Declare credential sources" carried the credentials.sources example — but the two only make sense together. New kit authors couldn't tell which block tied which (the service identifier is the join key) or where the value actually comes from. The wider question — does sbx secret set work for custom kit services? — has no answer in the docs today. Restructure: - Strip "Control network access" down to allowedDomains, the only block that's independent of credentials. Cross-link to the new authentication section. - Replace "Declare credential sources" with a new "Authenticate to external services" section that shows the full three-block chain in one example, walks through what the proxy does at request time, and spells out resolution order: stored secret keyed on the service identifier first, host env var fallback. Confirmed end-to-end against sbx v0.28.3 with a custom kit (kit-named keychain entries do flow through to the proxy). - Add a "Custom secrets" section to security/credentials.md documenting sbx secret set-custom with the EXPERIMENTAL caveat, so the kits page has a real cross-reference target. The build-an-agent tutorial already uses set-custom but the credentials page didn't acknowledge it existed. Closes docker/sbx-releases#103. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
dvdksn
force-pushed
the
sbx-user-feedback
branch
6 times, most recently
from
1b8853d to
adc4fd3
Compare
The "Authenticate to external services" section in customize/kits.md
had grown into a deep treatise inside what's otherwise a tour of kit
capabilities. Most of the conceptual model belongs on the credentials
page, not in a capability tour. The credentials page in turn was
implicitly framed around built-in agents only — kit-declared service
identifiers (which work end-to-end with sbx secret set) weren't
acknowledged anywhere.
Restructure:
- customize/kits.md: cut "Authenticate to external services" to a
show-then-link entry. Four-block YAML with brief inline comments,
one paragraph on runtime behavior, two cross-links to the
credentials page. The conceptual depth lives there now.
- security/credentials.md:
* Add a "How credential injection works" section after the intro
that names the three host-side mechanisms (service-based,
custom by host+env, host shell env) and links to each.
* Rename the "Supported services" subsection to "Built-in services"
and add a sibling "Services declared by kits" subsection
documenting the kit-declared identifier path for the first time.
* Tighten the "Custom secrets" framing — it's no longer
positioned as the catch-all for things kits can't do; it's
specifically for cases where the service-identifier model
doesn't fit (format-validating SDKs, request-body secrets).
- Update the FAQ cross-link to credentials#built-in-services.
Net effect: each page does one job. Kit authors get a tour entry
that points to the canonical model; credential consumers get a
single page that covers all three mechanisms with the missing
kit-declared services pattern documented.
Closes docker/sbx-releases#103.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
Author
|
/review |
![docker-agent[bot]](https://avatars.githubusercontent.com/in/2787757?s=60&v=4){kind=small}
- Drop bold on "template" / "kit" definitions and replace the ambiguous "The two compose." opener. - Reformat the credential-injection bullet list to plain prose instead of the marketing-style `**Term.** Description` pattern. - Add a warning callout on `sbx secret set-custom --value <secret>` about shell history and process visibility. - Replace "subcommand" and "env var" with full forms to clear Vale.Spelling errors in the CI run. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Vale.Spelling flags bare "repo" in prose. The Docker style guide also prefers the full word per Docker.RecommendedWords. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
craig-osterhout
approved these changes
May 5, 2026
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
2 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
Seven small docs fixes prompted by questions/conversations in slack and
recurring confusion in docker/sbx-releases issues:
--kitonly takes effect on sandbox creation at the firstsbx run --kitexample incustomize/kits.md, with a pointer tosbx kit addfor running sandboxes.sbxreuses the user'ssbx loginsession to pull private images from Docker Hub but fallsback to anonymous for other registries. Add IMPORTANT callouts on
customize/templates.mdand the OCI section ofcustomize/kits.md.Also document the
docker image save->sbx template loadworkaroundfor locally-built images and private images on registries
sbxcan'tauthenticate against (closes Support local image templates and authenticated pulls from private registries in sbx sbx-releases#29).
security/credentials.md: dropAWS_SECRET_ACCESS_KEYbecause the source only readsAWS_ACCESS_KEY_ID.docker/sbx-kits-contribreferencesin
build-an-agent.md,kit-examples.md, and the kits Git-sourceexample, now that the contrib repo is public.
that drops the permission-skipping flag — survives sandbox recreation
and works regardless of agent (closes opt out of yolo mode default sbx-releases#47).
customizelandingpage.
customize/kits.mdandsecurity/credentials.md(closes Confusion points from first-time user sbx-releases#103):capability-tour entry — show the four-block YAML and one runtime
paragraph, then cross-link out for depth.
credentials page that names the three host-side mechanisms
(service-based, custom by target domain + env var, host shell
fallback) and links to each.
("Services declared by kits") — confirmed end-to-end with a live
trial that
sbx secret set -g <kit-service>flows through to theproxy.
cases where the service-identifier model doesn't fit
(format-validating SDKs, request-body secrets), not the catch-all
for anything kits can't do. Document
sbx secret set-customwiththe EXPERIMENTAL caveat.
Generated by Claude Code