docs(sandboxes): kit spec schemaVersion 2 and credential bindings#25467
Draft
dvdksn wants to merge 6 commits into
Draft
docs(sandboxes): kit spec schemaVersion 2 and credential bindings#25467dvdksn wants to merge 6 commits into
dvdksn wants to merge 6 commits into
Conversation
✅ Deploy Preview for docsdocker ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
This was referenced Jun 30, 2026
docker-agent
left a comment
docker-agent
left a comment
Contributor
There was a problem hiding this comment.
Assessment: 🟡 NEEDS ATTENTION
dvdksn
force-pushed
the
sandboxes-kit-spec-v2
branch
2 times, most recently
from
a53f6ce to
1abdd3d
Compare
dvdksn
changed the title
dvdksn
force-pushed
the
sandboxes-kit-spec-v2
branch
3 times, most recently
from
de6aad0 to
ea5c18d
Compare
- Remove the environment variables section. Exporting API keys in your host shell is no longer a supported authentication path. - Document `sbx secret import` for moving API keys from environment variables into the keychain, with flags for non-interactive use (`--all`), overwriting (`--force`), and dry-run preview. - Lead the get-started authentication section with OAuth as the primary path for Claude Code, pointing to the credentials page for API keys. - Move CI credential setup to the workflows page, using `sbx secret import --all` and cross-referencing the built-in services table. - Revert agent-page language describing a first-run credential prompt that no longer applies to built-in agents. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add schemaVersion 2 kit spec reference, update kits.md and kit-examples.md for the v2 credential declaration model. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Document the credential bindings model for third-party schemaVersion 2 kits: credentials.yaml format, first-run approval flow, which kits require a binding, and fail-closed mode. Built-in agents are authorized by provenance and never need a binding. Stacked on top of the credentials base changes in docker#25468. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Rewrite the credential bindings section to match the shipped v0.9.0 binding schema. Bindings are store-only, per-mechanism approval records: each service entry approves apiKey and/or oauth, each with a domains list. Remove the obsolete discovery/env/file/allowedDomains model and the fail-closed setting, which don't exist. Correct the non-interactive behavior (warning + withheld credential, not a blocking error) and the first-run source choices (stored or entered, not env/file). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Remove the "known providers auto-expand their injection config" claim. In v0.9.0 the service name alone supplies no apiKey.name/inject; every service must declare an apiKey (name + inject) or oauth block. The worked examples already do this. - Delete the file.parser section: its two cited entry points (a binding file source and credentials.sources) are both removed/legacy in v2. - Drop the "or provider default" injection-domain aside in the network section for the same reason. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Verified each field against runtime wiring in docker/sandboxes, not just
the sbx-kits-contrib struct.
- apiKey: document proxyManaged (controls the in-container sentinel env
var); the proxy injects on the inject domains regardless.
- oauth: add the wired resourceHosts, skipIfEnv, responseFields, and
passthrough fields; add {{.Scopes}} to the template vars. Omit
credentialFile.structure, which the engine ignores.
- required: correct to advisory-only — it logs a warning but doesn't
block sandbox creation (the struct doc's fail-fast claim is stale).
- Schema versions table: map environment.proxyManaged to apiKey.name +
proxyManaged: true, and add the publishedPorts and volumes-form renames.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
dvdksn
force-pushed
the
sandboxes-kit-spec-v2
branch
from
ea5c18d to
ffb3931
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
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
Documents the Docker Sandboxes kit-authoring schema for
schemaVersion: "2"and the credential bindings feature for third-party kits.What's in this PR
customize/kit-reference.md— schema versions section with the v1→v2 field mapping; credentials/network/environment reference rewritten to thecaps.network+credentials[](apiKey/oauth) modelcustomize/kits.md,customize/kit-examples.md— examples updated toschemaVersion: "2"and the newcaps.network/credentials[]shapesecurity/credentials.md— adds the "Credential bindings" section (credentials.yamlformat, first-run approval, which kits require a binding, fail-closed mode) and updates "Services declared by kits" to the schemaVersion 2 declaration syntaxWhy combined
Credential bindings are only required for third-party
schemaVersion: "2"kits. Built-in agents are authorized by provenance and never trigger the binding consent flow, so documenting bindings only makes sense alongside the schemaVersion 2 kit context.Dependency
Stacked on #25468, which owns the base credentials documentation. Merge #25468 first, then rebase this branch onto main — the
credentials.mdchange here is only the additive bindings content on top of that base.