/docker-sandboxes-network-credentials

name: docker-sandboxes-network-credentials
description: Use this skill when configuring what a Docker Sandboxes (`sbx`) sandbox can reach on the network or which credentials it authenticates with, even if the user just says they want to "let the agent call an internal API", "block all network access", "give the agent a GitHub token", or "use a private registry image for a sandbox". Covers `sbx policy init/allow/deny/ls/inspect/log/check/rm network` (global and per-sandbox egress rules, deny-over-allow precedence) and `sbx secret set/set-custom/ls/rm/import` (service secrets, dynamic secrets via --ref/--command, and registry pull credentials with their host-pulls-only-by-default injection scope).
license: Apache-2.0
compatibility: Standalone `sbx` CLI (not the legacy `docker sandbox` plugin wrapper). Source-verified against repository docker/sandboxes (github.com/docker/sandboxes) @ commit df5c96ba60484fa2c375469dbac912c205da6c37. Cross-checked against an installed sbx v0.42.0-503-g951b7f6d7 (commit 951b7f6d7f6bb260fac15077b607109ffe8ae012, older than the pinned source); no source-only differences were found for the commands this skill covers. `docker_help` does not cover standalone `sbx` syntax.

Docker Sandboxes: Network Policy & Credentials

Overview

This skill owns `sbx policy` (network egress) and `sbx secret` (service secrets and registry credentials). The proxy enforces egress policy and injects stored credentials on matching domains. Proxy-managed sentinels are not usable upstream credentials, but OAuth passthrough can expose real tokens to the sandbox. Egress policy does not protect a real credential once leaked outside the sandbox; revoke or rotate a leaked credential.

When to use this skill

Activate this skill when:

• The user wants to allow, deny, or inspect which hosts a sandbox (or all

sandboxes) can reach.

• The user wants to give an agent an API key, OAuth token, or other service

credential without exposing the raw value inside the sandbox.

• The user wants to pull a private template image or kit from a registry

that requires authentication.

• The user is debugging a blocked network request or a credential that

isn't being injected.

Do not use this skill when

Do not use this skill when:

• The task is running `docker agent run --sandbox` or managing its

`docker agent sandbox` allowlist — use `docker-agent-run`. If the CLI is unclear, establish whether the user runs Docker Agent or standalone `sbx` before choosing commands.

• The task is creating, reattaching to, or removing a sandbox itself — use

`docker-sandboxes-lifecycle`.

• The task is declaring secrets/registries/bindings inside a checked-in

`sbxenv.yaml` file — use `docker-sandboxes-env` for the file format (this skill's rules on precedence and injection scope still apply to what that file provisions).

• The task is declaring a kit's own `credentials:`/`permissions.network:`

block in a `spec.yaml` — use `docker-sandboxes-kits` for the schema (this skill's model of what those declarations mean at runtime still applies).

Core guidance

Network policy: global, per-sandbox, and precedence

• The global network policy must be initialized once before creating the

first sandbox: `sbx policy init <allow-all|balanced|deny-all>`. `balanced` is the recommended starting point (typical dev traffic — AI services, package registries — allowed). This is a one-time setup.

• **`sbx policy reset` is destructive: it deletes the entire local policy

store and stops the daemon and every currently running sandbox.** The daemon restarts on the next daemon-backed command. It is not a lightweight way to "start over" or a routine diagnostic step — never propose it as a first troubleshooting move for a single misbehaving rule. Use targeted `sbx policy rm network` (by `--id` or `--resource`) to remove one rule instead; reserve `sbx policy reset` for when the policy store itself needs to be rebuilt from scratch, and warn the user that it will stop running sandboxes before running it.

• Add rules with `sbx policy allow network RESOURCES` /

`sbx policy deny network RESOURCES`. `RESOURCES` is a comma-separated list of exact hosts, `*.example.com` single-label wildcards, `**.example.com` multi-label wildcards, optional `:port` suffixes, CIDR prefixes, or `**` for "all hosts".

  sbx policy init balanced
  sbx policy allow network "api.example.com,cdn.example.com"
  sbx policy deny network ads.example.com

• **Deny always wins over allow** for the same hostname/CIDR when both

match. An allowed hostname is not checked against CIDR deny rules for its resolved IP.

• A rule applies globally by default. Pass `--sandbox NAME` to scope it to

one sandbox's local policy instead:

  sbx policy allow network --sandbox my-sandbox api.example.com

• At **creation time only**, `sbx create`/`sbx run` accept

`--deny-network RESOURCE` (repeatable) to add a per-sandbox deny rule. This is safe to expose even under centralized (org) governance because a local deny can only narrow, never widen, egress — it can never override an org-level allow into a broader grant.

• Use `sbx policy check network [--sandbox NAME] TARGET` to test what the

**current** policy would do for a host/URL before it matters, and `sbx policy log [SANDBOX]` to see what was actually allowed or blocked historically, with the matching rule.

  sbx policy check network --sandbox my-sandbox api.example.com:443
  sbx policy log my-sandbox --json

• `sbx policy ls [SANDBOX] [--wide]` lists active policies/rules; `--wide`

adds rule IDs (needed for `sbx policy rm network --id`) and per-resource status. `sbx policy inspect <policy-or-rule>` gives full detail including each rule's exact removal command or the reason it is read-only (e.g. org-managed). To remove a sandbox-scoped rule, retain `--sandbox NAME`; omitting it targets the global policy instead: