docker-docs/data/sbx_cli/sbx_secret_set.yaml

name: sbx secret set
synopsis: Create or update a secret
description: |-
    Create or update a service secret or registry credential.

    ### Service secrets

    Available services: anthropic, copilot, cursor, devin, droid, github, google, groq, mistral, nebius, openai, openrouter, xai

    Service secrets apply globally by default. Use --sandbox to scope a secret to
    one sandbox. When SERVICE is omitted, an interactive prompt selects it.

    ### Dynamic secrets

    Use --ref or --command to store a secret source instead of the secret value.
    sbx resolves the source on the host when needed and caches the value according
    to the --refresh policy.

    --ref supports 1Password op:// references and AWS Secrets Manager ARNs. The
    corresponding op or aws CLI must be installed and authenticated. --command
    runs a shell command and uses its standard output as the secret value.

    Command secrets run from a fresh temporary directory on the host during
    verification and refresh. The host temporary directory must be absolute and must
    remain outside writable sandbox mounts. Relative references such as ./helper or
    cat token no longer resolve against the project or daemon working directory. Use an absolute
    helper path outside shared workspaces. sbx does not copy helpers, inspect their
    dependencies, or confine their execution. Helpers and any code or configuration
    they load must remain outside writable sandbox mounts. Explicit paths into shared
    workspaces and broad mounts exposing host configuration or the host temporary
    directory remain unsafe, including mounts added to a running sandbox later.

    ### Registry credentials

    Use --registry to store pull credentials for a container registry. Unlike
    service secrets, registry credentials are host-only by default:

    - By default, credentials are used for template and kit pulls on the host.
      They are never injected into a sandbox.
    - With --all-sandboxes, credentials are used for host pulls and injected by
      the proxy into every new sandbox's registry login. The credentials never
      enter the sandbox.
    - With --sandbox, credentials are injected into the specified sandbox only.

    For a registry whose Bearer authentication endpoint uses a different hostname,
    use --registry-auth-endpoint to trust its exact HTTPS URL.
usage: sbx secret set [SERVICE] [flags]
options:
    - name: all-sandboxes
      default_value: "false"
      usage: |
        Inject registry credentials into every sandbox (requires --registry)
    - name: command
      usage: Use a command's standard output as the secret value
    - name: force
      shorthand: f
      default_value: "false"
      usage: |
        Overwrite existing API-key, OAuth, or registry credentials without confirmation
    - name: help
      shorthand: h
      default_value: "false"
      usage: help for set
    - name: no-verify
      default_value: "false"
      usage: Skip checking the --ref or --command source when storing it
    - name: oauth
      default_value: "false"
      usage: |
        Start OAuth flow and store OAuth tokens (openai/global only) With --cloud: openai or anthropic, stored only in the cloud (never the local secrets-engine)
    - name: password-stdin
      default_value: "false"
      usage: |
        Read registry password or token from stdin (use with --registry)
    - name: ref
      usage: |
        Use a 1Password op:// reference or AWS Secrets Manager ARN as the secret source
    - name: refresh
      usage: |
        Secret refresh policy: on-demand or after a duration (default: 55m)
    - name: registry
      usage: Registry hostname for pull credentials (e.g. ghcr.io)
    - name: registry-auth-endpoint
      usage: Trusted HTTPS auth endpoint for a cross-host registry realm
    - name: sandbox
      usage: Scope the secret to one sandbox instead of its default scope
    - name: show-error
      default_value: "false"
      usage: |
        Show resolver standard error if the initial check fails (may contain secrets)
    - name: token
      shorthand: t
      usage: 'Secret value (less secure: visible in shell history)'
    - name: username
      usage: |
        Registry username (use with --registry; omit for token-only auth)
inherited_options:
    - name: cloud
      default_value: "false"
      usage: |
        Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list)
    - name: debug
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
    - name: no-input
      default_value: "false"
      usage: |
        Never prompt; commands that need an answer fail with the command to run instead
example: |4-
      # Store a GitHub token globally (available to all sandboxes)
      sbx secret set github

      # Store an OpenAI key for a specific sandbox
      sbx secret set openai --sandbox my-sandbox

      # Non-interactive via stdin (e.g., from a secret manager or env var)
      echo "$ANTHROPIC_API_KEY" | sbx secret set anthropic

      # Start OpenAI OAuth flow and store global OAuth tokens
      sbx secret set openai --oauth

      # Resolve a 1Password reference at use time (requires an authenticated op CLI)
      sbx secret set anthropic --ref 'op://Private/Anthropic/api-key'

      # Resolve an AWS Secrets Manager ARN at use time (requires an authenticated aws CLI)
      sbx secret set anthropic --ref 'arn:aws:secretsmanager:us-west-2:123456789012:secret:anthropic-api-key'

      # Resolve a secret using an arbitrary command
      sbx secret set github --command 'gh auth token'

      # Registry: host-only (template/kit pulls, not injected into sandboxes)
      gh auth token | sbx secret set --registry ghcr.io --password-stdin

      # Registry: host pulls + injected into every new sandbox
      gh auth token | sbx secret set --all-sandboxes --registry ghcr.io --password-stdin

      # Registry: specific sandbox only
      gh auth token | sbx secret set --sandbox my-sandbox --registry ghcr.io --password-stdin

      # Self-hosted registry with a cross-host authentication endpoint
      echo "$GITLAB_PAT" | sbx secret set --all-sandboxes \
        --registry registry.example.com --username "$GITLAB_USER" \
        --registry-auth-endpoint https://gitlab.example.com/jwt/auth \
        --password-stdin
see_also:
    - sbx secret - Manage stored secrets