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.

    Secrets can be scoped globally (shared across all sandboxes) or to a specific sandbox.
usage: sbx secret set-custom [-g | sandbox] [flags]
options:
    - name: env
      usage: Set this env var in the sandbox to the placeholder value
    - name: global
      shorthand: g
      default_value: "false"
      usage: Use global secret scope
    - 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
    - name: placeholder
      usage: |
        Placeholder value; use {rand} for a random suffix (e.g. sk-{rand})
    - name: token
      shorthand: t
      usage: 'Secret value (less secure: visible in shell history)'
    - name: value
      usage: 'Secret value (less secure: visible in shell history)'
inherited_options:
    - name: debug
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
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 -g --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 -g --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 -g --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 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 -g --host api.example.com --placeholder sk-{rand} --value secret123
see_also:
    - sbx secret - Manage stored secrets
