docker-docs/data/sbx_cli/sbx_secret_set-custom.yaml

name: sbx secret set-custom
synopsis: Create or update a custom secret
experimental: true
description: |-
    Create or update a custom secret for a service not built into sbx.

    Custom secrets work via a placeholder: the sandbox sees the placeholder value
    instead of the real secret. When the sandbox makes an outbound request to the
    target host, the proxy replaces the placeholder with the real secret in the
    request headers — the secret never enters the sandbox directly.

    --host accepts an exact host, IP address, or wildcard pattern. Repeat --host
    to cover multiple unrelated domains with one secret. "*" matches a single label
    and "**" matches any number of labels. For example "*.example.com" covers
    "cli.example.com" and "ide.example.com" with one entry.

    Custom secrets apply globally by default. Use --sandbox to scope one to a
    specific sandbox.

    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.

    With --cloud, --host takes exact DNS names only (no IP addresses or wildcards)
    and the proxy sets --header on requests to those hosts instead of substituting
    the placeholder.
usage: sbx secret set-custom [flags]
options:
    - name: command
      usage: Use a command's standard output as the secret value
    - name: env
      usage: Set this env var in the sandbox to the placeholder value
    - name: format
      usage: |
        How the value fills the header, with one %s; default "Bearer %s" when --header is omitted (with --cloud)
    - name: header
      usage: |
        HTTP header the proxy sets to the secret on requests to --host; default Authorization (with --cloud)
    - name: help
      shorthand: h
      default_value: "false"
      usage: help for set-custom
    - name: host
      default_value: '[]'
      usage: |
        Host, IP, or wildcard pattern (e.g. *.example.com); repeatable; with --cloud, exact DNS names only
    - name: name
      usage: |
        Secret name; default derived from the first --host (with --cloud)
    - name: no-verify
      default_value: "false"
      usage: Skip checking the --ref or --command source when storing it
    - name: placeholder
      usage: |
        Placeholder value; use {rand} for a random suffix (e.g. sk-{rand})
    - 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 (default) or after a duration
    - name: sandbox
      usage: 'Scope the secret to one sandbox (default: all sandboxes)'
    - 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: value
      usage: 'Secret value (less secure: visible in shell history)'
    - name: value-stdin
      default_value: "false"
      usage: Read the secret value from stdin
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-
      # Create a global custom secret. A unique placeholder is generated automatically.
      # The sandbox env var API_KEY is set to the placeholder value; outbound requests
      # to the host have the placeholder replaced with the real secret.
      sbx secret set-custom --host api.example.com --env API_KEY --value secret123

      # Use a wildcard host to cover multiple subdomains that share one key.
      sbx secret set-custom --host '*.coderabbit.ai' --env CODERABBIT_API_KEY --value secret123

      # Use multiple --host flags to cover unrelated domains with the same key.
      sbx secret set-custom --host api.example.com --host api.other.io --env API_KEY --value secret123

      # Scope to a specific sandbox instead of globally.
      sbx secret set-custom --sandbox my-sandbox --host api.example.com --env API_KEY --value secret123

      # Custom placeholder with {rand} suffix; the CLI prints the generated value.
      sbx secret set-custom --host api.example.com --placeholder sk-{rand} --value secret123

      # Read the value from stdin to keep it out of shell history and the process list.
      printf '%s' "$API_KEY" | sbx secret set-custom --host api.example.com --env API_KEY --value-stdin
see_also:
    - sbx secret - Manage stored secrets