From 18a27156b28ff430709822d7c7ca56ab27d11109 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 20 Nov 2026 09:33:16 +0000 Subject: [PATCH 1/7] docs: explain custom secret header bindings Custom secret guidance did not explain which headers receive credentials. Document explicit and default header bindings, migration steps, and the limits of response redaction. --- .../ai/sandboxes/configuration/credentials.md | 69 +++++++++++++++++-- .../ai/sandboxes/configuration/settings.md | 25 +++++++ 2 files changed, 90 insertions(+), 4 deletions(-) diff --git a/content/manuals/ai/sandboxes/configuration/credentials.md b/content/manuals/ai/sandboxes/configuration/credentials.md index 3ab366955e1..8f94a0ff3da 100644 --- a/content/manuals/ai/sandboxes/configuration/credentials.md +++ b/content/manuals/ai/sandboxes/configuration/credentials.md @@ -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. Older stored secrets with shorter values +aren't substituted; set them again with a longer value. To read the value from standard input, set `API_KEY` in your host environment and pipe it with `--value-stdin`: @@ -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 ``` @@ -464,9 +467,63 @@ 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-`). 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 and the placeholder appears in a bound HTTP request header, +the proxy replaces it with the real value. Replacement applies only to bound +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`, a local custom secret follows +[`secret.custom.defaultHeaders`](settings.md#secretcustomdefaultheaders). +The default list is `Authorization`, `X-Api-Key`, `Api-Key`, `X-Auth-Token`, +`Private-Token`, `X-Goog-Api-Key`, and `DD-API-KEY`. Secrets stored without +headers by an older CLI also follow this setting. Cloud custom secrets use +`Authorization` by default instead; see [cloud credentials](../cloud/credentials.md). + +If an existing secret uses another header, bind it explicitly. Find its +placeholder with `sbx secret ls`, then update only its headers: + +```console +$ sbx secret set-custom --placeholder --header X-Custom-Key +``` + +For a sandbox-scoped secret, include `--sandbox `. 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 HTTP header names +and headers the proxy handles itself: `Host`, `Content-Length`, +`Transfer-Encoding`, `Trailer`, `Accept-Encoding`, `Proxy-Authorization`, +`Proxy-Authenticate`, `Proxy-Connection`, `Connection`, `Keep-Alive`, `Upgrade`, +and `Te`. + +If the CLI reports that secrets without headers weren't sent to the daemon, +restart the daemon after upgrading Docker Sandboxes: + +```console +$ sbx daemon restart +``` + +Default headers require daemon API `0.53.0` or later. When syncing to an older +daemon, the CLI leaves out secrets without explicit headers, so those secrets +stop working in running sandboxes until the daemon is upgraded and restarted. + +### Responses that echo secrets + +When a request substitutes a custom secret, the proxy replaces matching secrets +in response headers and bodies with placeholders. Matching covers literal, +JSON-escaped, percent-encoded, and base64 forms. + +This redaction is best effort. It doesn't cover other transformations, such as +hashing or splitting a value across fields, WebSocket frames after an upgrade, +or responses to requests that substituted no secret. Rewriting a match can +leave a response body invalid. Partial responses (`206`) and responses with +unsupported content encodings are withheld with a `502` response. ### List custom secrets @@ -488,6 +545,10 @@ 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. Older secrets without explicit bindings +also produce a warning with a command to bind their headers. + ### Target multiple hosts Repeat `--host` to cover multiple domains with the same secret — useful when diff --git a/content/manuals/ai/sandboxes/configuration/settings.md b/content/manuals/ai/sandboxes/configuration/settings.md index 83be65bba68..6332212317b 100644 --- a/content/manuals/ai/sandboxes/configuration/settings.md +++ b/content/manuals/ai/sandboxes/configuration/settings.md @@ -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} From 82b83dd6abb527c6917b12411380a780bc0eeabc Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 20 Nov 2026 12:53:38 +0000 Subject: [PATCH 2/7] docs: clarify custom secret header guidance Describe custom secrets in terms of current behavior and link to the settings reference for default headers. Remove migration details and format rejected headers as a list. --- .../ai/sandboxes/configuration/credentials.md | 47 +++++++++---------- 1 file changed, 21 insertions(+), 26 deletions(-) diff --git a/content/manuals/ai/sandboxes/configuration/credentials.md b/content/manuals/ai/sandboxes/configuration/credentials.md index 8f94a0ff3da..781c799e2f2 100644 --- a/content/manuals/ai/sandboxes/configuration/credentials.md +++ b/content/manuals/ai/sandboxes/configuration/credentials.md @@ -441,8 +441,7 @@ the kit handles the wiring; you only provide the value. Custom secrets are global by default. Pass `--sandbox` to scope one to a specific sandbox. Values must be at least eight characters long, including -values returned by dynamic sources. Older stored secrets with shorter values -aren't substituted; set them again with a longer value. +values returned by dynamic sources. To read the value from standard input, set `API_KEY` in your host environment and pipe it with `--value-stdin`: @@ -477,15 +476,13 @@ 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`, a local custom secret follows +Without `--header`, a local custom secret uses the headers listed in [`secret.custom.defaultHeaders`](settings.md#secretcustomdefaultheaders). -The default list is `Authorization`, `X-Api-Key`, `Api-Key`, `X-Auth-Token`, -`Private-Token`, `X-Goog-Api-Key`, and `DD-API-KEY`. Secrets stored without -headers by an older CLI also follow this setting. Cloud custom secrets use -`Authorization` by default instead; see [cloud credentials](../cloud/credentials.md). +Cloud custom secrets use `Authorization` by default instead; see +[cloud credentials](../cloud/credentials.md). -If an existing secret uses another header, bind it explicitly. Find its -placeholder with `sbx secret ls`, then update only its headers: +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 --header X-Custom-Key @@ -497,21 +494,20 @@ 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 HTTP header names -and headers the proxy handles itself: `Host`, `Content-Length`, -`Transfer-Encoding`, `Trailer`, `Accept-Encoding`, `Proxy-Authorization`, -`Proxy-Authenticate`, `Proxy-Connection`, `Connection`, `Keep-Alive`, `Upgrade`, -and `Te`. - -If the CLI reports that secrets without headers weren't sent to the daemon, -restart the daemon after upgrading Docker Sandboxes: - -```console -$ sbx daemon restart -``` - -Default headers require daemon API `0.53.0` or later. When syncing to an older -daemon, the CLI leaves out secrets without explicit headers, so those secrets -stop working in running sandboxes until the daemon is upgraded and restarted. +and the following headers, which the proxy handles itself: + +- `Host` +- `Content-Length` +- `Transfer-Encoding` +- `Trailer` +- `Accept-Encoding` +- `Proxy-Authorization` +- `Proxy-Authenticate` +- `Proxy-Connection` +- `Connection` +- `Keep-Alive` +- `Upgrade` +- `Te` ### Responses that echo secrets @@ -546,8 +542,7 @@ $ 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. Older secrets without explicit bindings -also produce a warning with a command to bind their headers. +follow the default-header setting. ### Target multiple hosts From d775335504e9e9c1b1085782df135b92d3d9446b Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 20 Nov 2026 13:17:31 +0000 Subject: [PATCH 3/7] docs: explain daemon restart for custom secret defaults An older running daemon cannot apply default headers to custom secrets. Document the API requirement, the effect of credential synchronization, and the restart needed after an upgrade. --- .../ai/sandboxes/configuration/credentials.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/content/manuals/ai/sandboxes/configuration/credentials.md b/content/manuals/ai/sandboxes/configuration/credentials.md index 781c799e2f2..a6fbfd60c4a 100644 --- a/content/manuals/ai/sandboxes/configuration/credentials.md +++ b/content/manuals/ai/sandboxes/configuration/credentials.md @@ -481,6 +481,18 @@ Without `--header`, a local custom secret uses the headers listed in Cloud custom secrets use `Authorization` by default instead; see [cloud credentials](../cloud/credentials.md). +Default headers require daemon API 0.53.0 or later. If an older daemon is +still running after you upgrade Docker Sandboxes, restart it: + +```console +$ sbx daemon restart +``` + +Until you restart, credential synchronization omits custom secrets without +explicit headers, including previously stored secrets. This can stop those +secrets from working in running sandboxes. Changing +`secret.custom.defaultHeaders` doesn't restore them on the older daemon. + To change a secret's header bindings, find its placeholder with `sbx secret ls`, then update only its headers: From fdd4b5a0216bd00c2effc9b90d9337204fb1aad8 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 20 Nov 2026 13:34:00 +0000 Subject: [PATCH 4/7] docs: move custom secret upgrade recovery to troubleshooting The header configuration guide interrupted normal usage with daemon compatibility details. Move recovery steps to troubleshooting, anchored to the reported error, and omit internal API versions. --- .../ai/sandboxes/configuration/credentials.md | 12 ------------ content/manuals/ai/sandboxes/troubleshooting.md | 17 +++++++++++++++++ 2 files changed, 17 insertions(+), 12 deletions(-) diff --git a/content/manuals/ai/sandboxes/configuration/credentials.md b/content/manuals/ai/sandboxes/configuration/credentials.md index a6fbfd60c4a..781c799e2f2 100644 --- a/content/manuals/ai/sandboxes/configuration/credentials.md +++ b/content/manuals/ai/sandboxes/configuration/credentials.md @@ -481,18 +481,6 @@ Without `--header`, a local custom secret uses the headers listed in Cloud custom secrets use `Authorization` by default instead; see [cloud credentials](../cloud/credentials.md). -Default headers require daemon API 0.53.0 or later. If an older daemon is -still running after you upgrade Docker Sandboxes, restart it: - -```console -$ sbx daemon restart -``` - -Until you restart, credential synchronization omits custom secrets without -explicit headers, including previously stored secrets. This can stop those -secrets from working in running sandboxes. Changing -`secret.custom.defaultHeaders` doesn't restore them on the older daemon. - To change a secret's header bindings, find its placeholder with `sbx secret ls`, then update only its headers: diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index d354114de74..a1cce241113 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -276,6 +276,23 @@ connections to this server. The flag requires `--url` and can't be used with `--command` or `--local`. For registration options, see [Register an MCP server](mcp-gateway.md#register-an-mcp-server). +## Custom secrets are not sent to the daemon + +If a command reports `custom secrets with no headers were not sent to the daemon` +after you upgrade Docker Sandboxes, an older daemon is still running. Custom +secrets that use default headers are withheld from that daemon, so they can +stop working in running sandboxes. The secrets remain stored on the host. + +Restart the daemon, then retry the command that reported the error: + +```console +$ sbx daemon restart +``` + +Changing `secret.custom.defaultHeaders` doesn't resolve this error. For normal +header configuration, see +[Choose request headers](configuration/credentials.md#choose-request-headers). + ## API calls fail with a certificate error If your organization uses a proxy that inspects HTTPS traffic, agent requests From 15197acfc4dcf1022c9985d1c003ec2a8c998606 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 20 Nov 2026 13:42:16 +0000 Subject: [PATCH 5/7] docs: Clarify custom secret response filtering The response filtering guidance leaves readers to interpret its limits and the meaning of a WebSocket upgrade. Explain when filtering applies, what it recognizes, and how its limits affect clients. --- .../ai/sandboxes/configuration/credentials.md | 32 ++++++++++++------- 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/content/manuals/ai/sandboxes/configuration/credentials.md b/content/manuals/ai/sandboxes/configuration/credentials.md index 781c799e2f2..b90de679023 100644 --- a/content/manuals/ai/sandboxes/configuration/credentials.md +++ b/content/manuals/ai/sandboxes/configuration/credentials.md @@ -466,9 +466,9 @@ 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-`). When a sandboxed process sends a request to any of the -configured hosts and the placeholder appears in a bound HTTP request header, -the proxy replaces it with the real value. Replacement applies only to bound -request headers, not request bodies. +configured hosts 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 @@ -509,17 +509,25 @@ and the following headers, which the proxy handles itself: - `Upgrade` - `Te` -### Responses that echo secrets +### When a service returns a secret -When a request substitutes a custom secret, the proxy replaces matching secrets -in response headers and bodies with placeholders. Matching covers literal, -JSON-escaped, percent-encoded, and base64 forms. +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 redaction is best effort. It doesn't cover other transformations, such as -hashing or splitting a value across fields, WebSocket frames after an upgrade, -or responses to requests that substituted no secret. Rewriting a match can -leave a response body invalid. Partial responses (`206`) and responses with -unsupported content encodings are withheld with a `502` response. +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 From 6e0a83f7c498ce7f451a04723e5bc9898674fcb0 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 20 Nov 2026 14:55:15 +0000 Subject: [PATCH 6/7] docs: Remove custom secret daemon mismatch troubleshooting The custom secret troubleshooting section describes a client and daemon version mismatch after an upgrade. Remove this recovery scenario from the guide because upgrades restart the daemon. --- content/manuals/ai/sandboxes/troubleshooting.md | 17 ----------------- 1 file changed, 17 deletions(-) diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index a1cce241113..d354114de74 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -276,23 +276,6 @@ connections to this server. The flag requires `--url` and can't be used with `--command` or `--local`. For registration options, see [Register an MCP server](mcp-gateway.md#register-an-mcp-server). -## Custom secrets are not sent to the daemon - -If a command reports `custom secrets with no headers were not sent to the daemon` -after you upgrade Docker Sandboxes, an older daemon is still running. Custom -secrets that use default headers are withheld from that daemon, so they can -stop working in running sandboxes. The secrets remain stored on the host. - -Restart the daemon, then retry the command that reported the error: - -```console -$ sbx daemon restart -``` - -Changing `secret.custom.defaultHeaders` doesn't resolve this error. For normal -header configuration, see -[Choose request headers](configuration/credentials.md#choose-request-headers). - ## API calls fail with a certificate error If your organization uses a proxy that inspects HTTPS traffic, agent requests From 6094b7f8d921e4f4e78582d976efb7e96a377a80 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 20 Nov 2026 16:31:25 +0000 Subject: [PATCH 7/7] docs: clarify custom secret migration requirements Explain how header defaults and minimum length affect existing secrets, align HTTPS substitution wording, and shorten the proxy-controlled header reference. --- .../ai/sandboxes/configuration/credentials.md | 31 +++++++------------ 1 file changed, 11 insertions(+), 20 deletions(-) diff --git a/content/manuals/ai/sandboxes/configuration/credentials.md b/content/manuals/ai/sandboxes/configuration/credentials.md index b90de679023..47cdfe403f6 100644 --- a/content/manuals/ai/sandboxes/configuration/credentials.md +++ b/content/manuals/ai/sandboxes/configuration/credentials.md @@ -441,7 +441,8 @@ the kit handles the wiring; you only provide the value. Custom secrets are global by default. Pass `--sandbox` to scope one to a specific sandbox. Values must be at least eight characters long, including -values returned by dynamic sources. +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`: @@ -466,9 +467,9 @@ 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-`). When a sandboxed process sends a request to any of the -configured hosts 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. +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 @@ -476,8 +477,11 @@ 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`, a local custom secret uses the headers listed in +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). @@ -493,21 +497,8 @@ 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 HTTP header names -and the following headers, which the proxy handles itself: - -- `Host` -- `Content-Length` -- `Transfer-Encoding` -- `Trailer` -- `Accept-Encoding` -- `Proxy-Authorization` -- `Proxy-Authenticate` -- `Proxy-Connection` -- `Connection` -- `Keep-Alive` -- `Upgrade` -- `Te` +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