Docker Sandboxes Network Credentials

Service secrets: how injection works

• sbx secret set [SERVICE] stores a credential the proxy uses to authenticate outbound requests on behalf of the agent. In the normal proxy-managed flow, the sandbox sees a sentinel rather than the raw secret; the proxy substitutes the real value on requests to the domains the matching kit/binding declares.

  sbx secret set github                       # interactive
  printf '%s' "$ANTHROPIC_API_KEY" | sbx secret set anthropic

  Storing a secret does not grant network access. Egress is governed separately by sbx policy; check the target domain in the intended scope before debugging authentication:

  sbx policy check network --sandbox my-sandbox api.anthropic.com

• OAuth passthrough is an exception, not a no-secret-exposure guarantee. When a kit sets oauth.passthrough: true without a refresh sentinel, the proxy forwards the real token response to the sandbox. The built-in devin kit uses this mode. Review the agent's credential configuration before promising that it cannot read a token; do not enable passthrough merely to bypass an authentication failure. Even with sentinels, the agent can exercise the credential's permissions on allowed services — restrict token privileges as well as network access.
• Service secrets are global by default; --sandbox NAME scopes one to a single sandbox.
• Dynamic secrets resolve the value on the host at use time instead of storing it directly: --ref (1Password op://... or an AWS Secrets Manager ARN — requires an authenticated op/aws CLI) or --command (runs a shell command and uses its stdout). --refresh controls the resolution/cache policy (default 55m, or on-demand).

  sbx secret set anthropic --ref 'op://Private/Anthropic/api-key'
  sbx secret set github --command 'gh auth token'

  --command and --ref are resolved on the host, with your own privileges, and treated as trusted execution — never point --command at anything an untrusted file or an agent's own output could influence.
• Never pass a secret as a plain --env value or as a --kit-arg / --env-arg value. Both land as literal, unmasked text — in the sandbox's environment, in sbx env plan's state file, and potentially in shell history — defeating the entire point of the credential store. Use sbx secret set (or sbxenv.yaml's secrets:/registries: blocks, which route through the same store) instead.
• sbx secret set-custom (experimental) covers a service sbx has no built-in support for: the sandbox sees a placeholder value in an env var you name (--env), and the proxy swaps in the real secret only on requests to the --host pattern(s) you declare.
• sbx secret ls [--global|--sandbox NAME] [--service NAME] [--json] lists what is stored, without revealing values. sbx secret rm [SERVICE] [--sandbox NAME] [--all|--registry HOST] [--force] removes it.
• sbx secret import [SERVICE] [--all] [--dry-run] [--force] offers to import secrets already sitting in host environment variables (e.g. OPENAI_API_KEY, GH_TOKEN) into the global store, prompting per entry unless --all/--force. A service with an OAuth token already configured is skipped — OAuth takes precedence at runtime over an imported API key.

Registry credentials: host-pulls-only by default, two distinct injection scopes

• sbx secret set --registry HOST --password-stdin (optionally --username) stores pull credentials for a container registry, used to pull private template images and kit artifacts. Unlike service secrets, registry credentials are host-only by default: they authenticate pulls on the host and are never injected into any sandbox.

  gh auth token | sbx secret set --registry ghcr.io --password-stdin

• --all-sandboxes and --sandbox widen this differently — do not confuse them:
  • --all-sandboxes: credentials are used for host pulls and injected by the proxy into every new sandbox's registry login (the credential itself never enters the sandbox filesystem).
  • --sandbox NAME: credentials are injected into that one sandbox only.
  • Neither flag: host-pulls-only, injected nowhere.

  gh auth token | sbx secret set --all-sandboxes --registry ghcr.io --password-stdin
  gh auth token | sbx secret set --sandbox my-sandbox --registry ghcr.io --password-stdin

• For a registry whose Bearer auth endpoint lives on a different hostname than the registry itself, pass --registry-auth-endpoint naming the exact trusted HTTPS URL — otherwise the cross-host token exchange is rejected.
• sbx secret rm --registry HOST --sandbox NAME removes only that sandbox's registry credential; host-only and global (all-sandboxes) entries are untouched. This does not revoke the upstream token or prevent use of another applicable credential.

  sbx secret rm --registry ghcr.io --sandbox my-sandbox

• Without --sandbox, sbx secret rm --registry HOST removes both the host-only and global entries. Add --all-sandboxes to remove only the global entry instead.

Related skills

• For docker agent run --sandbox and docker agent sandbox commands, use docker-agent-run.

• For creating, reattaching to, and removing the sandboxes these policies and secrets apply to, use docker-sandboxes-lifecycle.

• For declaring secrets:/registries:/bindings: inside a checked-in sbxenv.yaml file that provisions them at environment-create time, use docker-sandboxes-env.

• For a kit's own credentials: and permissions.network: declarations (what a kit asks for, as opposed to what the user has approved), use docker-sandboxes-kits.

References

• references/sources.md — provenance for every rule above (help captures, source paths, docs URLs).

Assets

• None.

Checks

• checks/verification.md — Verification runbook for network policy and secret commands (unexecuted runbook; run manually with an isolated --app-name, no real secret values).