Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 59 additions & 4 deletions content/manuals/ai/sandboxes/configuration/credentials.md
Original file line number Diff line number Diff line change
Expand Up @@ -440,7 +440,9 @@ the kit handles the wiring; you only provide the value.
### Set a custom secret

Custom secrets are global by default. Pass `--sandbox` to scope one to a
specific sandbox.
specific sandbox. Values must be at least eight characters long, including
values returned by dynamic sources. Existing shorter values aren't substituted
and must be replaced with longer values.

To read the value from standard input, set `API_KEY` in your host environment
and pipe it with `--value-stdin`:
Expand All @@ -449,6 +451,7 @@ and pipe it with `--value-stdin`:
$ printf '%s' "$API_KEY" | sbx secret set-custom \
--host api.example.com \
--env API_KEY \
--header X-Api-Key \
--value-stdin
```

Expand All @@ -464,9 +467,58 @@ to enter the value at a prompt instead. `--value-stdin` can't be combined with

Inside the sandbox, `API_KEY` is set to a generated placeholder (for example,
`sbx-cs-<rand>`). When a sandboxed process sends a request to any of the
configured hosts and the placeholder appears in an HTTP request header, the
proxy replaces it with the real value. Replacement applies only to HTTP request
headers, not request bodies. The agent never sees the real secret.
configured hosts over HTTPS and the placeholder appears in a request header
configured for that secret, the proxy replaces it with the real value.
Replacement applies only to those request headers, not request bodies.

### Choose request headers

Use `--header` to name the header your service reads. Repeat the flag to bind
the secret to more than one header. In other headers, the placeholder is sent
unchanged.

Without `--header`, local custom secrets, including existing secrets without
header bindings, use the headers listed in
[`secret.custom.defaultHeaders`](settings.md#secretcustomdefaultheaders).
If your service uses another header, bind it explicitly.

Cloud custom secrets use `Authorization` by default instead; see
[cloud credentials](../cloud/credentials.md).

To change a secret's header bindings, find its placeholder with
`sbx secret ls`, then update only its headers:

```console
$ sbx secret set-custom --placeholder <PLACEHOLDER> --header X-Custom-Key
```

For a sandbox-scoped secret, include `--sandbox <SANDBOX_NAME>`. This keeps
the value, hosts, environment variable, and dynamic source unchanged. Setting
the secret again without `--header` preserves its existing header bindings.
Alternatively, change the default-header setting for all secrets that follow it.

Header names are case-insensitive. The CLI rejects invalid names and headers
controlled by the proxy, such as `Host` and `Content-Length`.

### When a service returns a secret

A service might include a secret in its response, for example in an error
message that repeats the request headers. When the proxy inserts a custom
secret into a request, it checks the response headers and body and masks
matching secret values before returning the response to the sandbox. It
recognizes the original value and JSON-escaped, percent-encoded, and base64
forms.

This filtering cannot guarantee that a secret stays hidden. It doesn't inspect
WebSocket messages or recognize every way a service could transform a secret,
such as splitting it across separate fields. Filtering applies only when the
proxy inserted a custom secret into the request.

Masking a secret can change the response format and make it unreadable by the
client.

For these requests, the proxy returns `502 Bad Gateway` instead of forwarding
partial responses (`206`) or responses with unsupported content encodings.

### List custom secrets

Expand All @@ -488,6 +540,9 @@ Add `--sandbox` to list only matching secrets stored for a specific sandbox:
$ sbx secret ls --host api.example.com --sandbox my-sandbox
```

The header column shows explicit bindings or `(default)` for secrets that
follow the default-header setting.

### Target multiple hosts

Repeat `--host` to cover multiple domains with the same secret — useful when
Expand Down
25 changes: 25 additions & 0 deletions content/manuals/ai/sandboxes/configuration/settings.md
Original file line number Diff line number Diff line change
Expand Up @@ -469,6 +469,31 @@ timestamp from a timestamp authority instead of a transparency log timestamp.
Leave this at `false` when your signing workflow uses the public transparency
log. It has no effect on signatures verified with a public key.

### Custom secrets

#### secret.custom.defaultHeaders {.wrap-anywhere}

{{< setting-metadata type="JSON"
default="[\"Authorization\",\"X-Api-Key\",\"Api-Key\",\"X-Auth-Token\",\"Private-Token\",\"X-Goog-Api-Key\",\"DD-API-KEY\"]" >}}

Choose the request headers into which the proxy substitutes local custom
secrets stored without explicit header bindings. The value is a JSON array of
HTTP header names. For example, restrict these secrets to `Authorization`:

```console
$ sbx settings set secret.custom.defaultHeaders '["Authorization"]'
```

The array replaces the whole list. Set it to `[]` to require explicit
`sbx secret set-custom --header` bindings: secrets that follow the defaults
aren't substituted into any header. Explicit bindings and cloud custom secrets
aren't affected. See [choose request headers](credentials.md#choose-request-headers)
for binding commands and headers the proxy rejects.

Changes apply to existing local sandboxes without a restart. If the setting
can't be read or contains an invalid list, secrets that depend on it aren't
substituted until a valid setting can be read again.

### Model server

#### model.server.enabled {.wrap-anywhere}
Expand Down