docs: add Docker Sandboxes settings reference (#26156)

Settings usage is scattered across individual guides. Add a Settings
page under Configuration explaining value precedence, environment
variables, and when changes take effect. Each catalog entry includes a
use case, an example, and the consequences of changing the setting, with
links to detailed task guides.

A small `setting-metadata` shortcode separates type, default, and
environment variable from prose using a responsive definition list. It
also provides plain Markdown output. Link existing settings mentions to
the reference and remove duplicated explanations while retaining
task-specific instructions.

Verified against Sandboxes v0.45.0 source. Feature-flag controls are
excluded; experimental entries are limited to documented flows. Scoped
lint, the Hugo build, and 70 rendered internal links passed. Checked all
26 metadata records in HTML and Markdown and browser layouts at widths
from 320 to 1440 pixels.

@netlify /ai/sandboxes/configuration/settings/

Generated by Codex

COMPONENTS.md

@@ -262,6 +262,25 @@ params:
 - Use green for new GA features
 - Use gray for deprecated features
 
+### Setting metadata
+
+Use `setting-metadata` below a setting's heading to display its type, default,
+and optional environment variable. Keep explanations and examples in the page
+body. The component uses a definition list with wrapping values and preserves
+the metadata in Markdown output.
+
+```markdown
+{{</* setting-metadata
+  type="boolean"
+  default="false"
+  env="DOCKER_SANDBOXES_CLIPBOARD_IMAGE_PASTE"
+*/>}}
+```
+
+The `type` and `default` parameters are required. Omit `env` when the setting
+has no environment variable equivalent. Use `default="Empty string"` for an
+empty string default.
+
 ### Summary bars
 
 Summary bars indicate subscription requirements, version requirements, or

content/manuals/ai/sandboxes/agents/claude-code.md

@@ -55,8 +55,8 @@ for workarounds.
 
 ### Remote control
 
-To use Claude Code's `/remote-control` command inside a sandbox, turn on remote
-control:
+To use Claude Code's `/remote-control` command inside a sandbox, turn on
+[`claude.remoteControl`](../configuration/settings.md#clauderemotecontrol):
 
 ```console
 $ sbx settings set claude.remoteControl true

content/manuals/ai/sandboxes/architecture.md

@@ -52,7 +52,9 @@ Each sandbox maintains its own Docker daemon state, image cache, and package
 installations. Multiple sandboxes don't share images or layers. The
 [shared agent skills store](workflows/agent-skills.md) is an exception:
 sandboxes created for supported agents mount the same host-side store read-only
-by default. Use `--skills` or `skills.defaultMode` to choose another mode at
+by default. Use `--skills` or
+[`skills.defaultMode`](configuration/settings.md#skillsdefaultmode)
+to choose another mode at
 creation. Existing sandboxes retain their mounts until recreated.
 
 Each sandbox consumes disk space for its VM image, Docker images, container

content/manuals/ai/sandboxes/configuration/_index.md

@@ -2,8 +2,8 @@
 title: Configure Docker Sandboxes
 linkTitle: Configuration
 weight: 60
-description: Configure credentials, local and hosted models, project environments, GPU passthrough, registry mirrors, and upstream proxy settings for Docker Sandboxes.
-keywords: docker sandboxes, sbx, configuration, credentials, models, environment files, gpu passthrough, registry mirror, upstream proxy
+description: Configure Docker Sandboxes settings, credentials, models, project environments, GPU passthrough, registry mirrors, and upstream proxies.
+keywords: docker sandboxes, sbx, configuration, settings, credentials, models, environment files, gpu passthrough, registry mirror, upstream proxy
 ---
 
 Configure credentials and how Docker Sandboxes run for a project, host, or
@@ -11,6 +11,8 @@ network environment. These settings control sandbox creation, authentication,
 and connectivity. To change the tools and agent configuration inside a
 sandbox, see [Customize](../customize/).
 
+- [Settings](settings.md) lists host-level settings, environment variable
+  equivalents, and commands to inspect and change values.
 - [Credentials](credentials.md) configures API keys, authentication
   credentials, and registry access for sandboxed agents.
 - [Models](models.md) selects local models, hosted providers, or custom

content/manuals/ai/sandboxes/configuration/credentials.md

@@ -311,9 +311,10 @@ configure that path for every sandbox:
 $ sbx settings set ssh.agentSocketPath "$SSH_AUTH_SOCK"
 ```
 
-An empty `ssh.agentSocketPath`, which is the default, uses each client's
-current `SSH_AUTH_SOCK` instead. The `ssh.agentForwardingEnabled` setting is a
-boolean that turns forwarding on or off.
+An empty [`ssh.agentSocketPath`](settings.md#sshagentsocketpath), which is the
+default, uses each client's current `SSH_AUTH_SOCK` instead. Use
+[`ssh.agentForwardingEnabled`](settings.md#sshagentforwardingenabled) to turn
+forwarding on or off.
 
 After changing forwarding or the socket selection, restart the daemon so
 existing sandboxes use the new configuration:

content/manuals/ai/sandboxes/configuration/environment-files.md

@@ -481,7 +481,7 @@ kits:
 ```
 
 Remote kit sources must match the
-[kit source allowlist](../customize/kits.md#restrict-kit-sources). Docker Hub is
+[`kit.allowedSources`](settings.md#kitallowedsources) setting. Docker Hub is
 allowed by default. To use Git kits from `docker/sbx-kits-contrib`, add its
 source:
 
@@ -600,7 +600,9 @@ commands.
 Plans containing lifecycle commands or credential `command` sources require
 approval for every invocation by default, even when the command text hasn't
 changed. Approve one invocation with `--auto-approve`, skip lifecycle commands
-with `--skip-host-commands`, or remember approval until the commands change:
+with `--skip-host-commands`, or turn on
+[`env.rememberHostCommands`](settings.md#envrememberhostcommands) to remember
+approval until the commands change:
 
 ```console
 $ sbx settings set env.rememberHostCommands true

content/manuals/ai/sandboxes/configuration/registry-mirror.md

@@ -12,8 +12,8 @@ Docker Engine's requirements, Docker inside the sandbox uses it too.
 
 ## Configure the mirror
 
-Set `platform.images.registryMirror` to the mirror host. Include a port when
-needed, but omit the URL scheme:
+Set [`platform.images.registryMirror`](settings.md#platformimagesregistrymirror)
+to the mirror host. Include a port when needed, but omit the URL scheme:
 
 ```console
 $ sbx settings set platform.images.registryMirror registry.example.com

content/manuals/ai/sandboxes/configuration/settings.md

@@ -0,0 +1,684 @@
+---
+title: Docker Sandboxes settings
+linkTitle: Settings
+description: Configure Docker Sandboxes with sbx settings. View effective values, manage persistent overrides, and use environment variables for supported settings.
+keywords: docker sandboxes, sbx, settings, configuration, environment variables, overrides
+weight: 5
+---
+
+Use `sbx settings` to configure Docker Sandboxes on your host, including
+clipboard access, kit sources, and defaults for sandbox creation. Settings
+apply across your local sandboxes. For project-specific configuration, use
+[environment files](environment-files.md).
+
+The commands read and write settings through the local daemon, starting it if
+necessary. Overrides persist across CLI invocations and daemon restarts.
+
+## View settings
+
+List settings with their effective value, type, source, and description:
+
+```console
+$ sbx settings list
+```
+
+Long values and descriptions are truncated in the table. Use
+`sbx settings list --no-trunc` for complete text, or `sbx settings list --json`
+for JSON output. The JSON records also include defaults and environment
+variable names where available.
+
+To inspect one setting:
+
+```console
+$ sbx settings get clipboard.imagePaste
+false
+$ sbx settings get clipboard.imagePaste --json
+```
+
+Without `--json`, `get` prints only the effective value. With `--json`, it
+prints the complete setting record, including the source and default.
+
+## Change a setting
+
+Set an override by passing the setting key and a value of the required type.
+For example, allow sandboxed agents to read images from your host clipboard:
+
+```console
+$ sbx settings set clipboard.imagePaste true
+```
+
+For JSON values, quote the argument so your shell passes it intact. This
+example permits kits from Docker Hub and your organization's GitHub repositories:
+
+```console
+$ sbx settings set kit.allowedSources '["docker.io/","github.com/myorg/"]'
+```
+
+JSON arrays and objects replace the whole value. Include any entries you want
+to keep.
+
+Remove an override with `unset`:
+
+```console
+$ sbx settings unset clipboard.imagePaste
+```
+
+The setting falls back to its environment variable, if set, or its default.
+Setting a value equal to its built-in default also removes the stored override.
+
+### Value precedence
+
+For each setting, the first available value wins:
+
+1. The setting's environment variable, if it has one
+2. A user override written with `sbx settings set`
+3. The built-in default
+
+The `SOURCE` column in `sbx settings list` identifies the selected source as
+`envvar`, `override`, or `default`. If an environment variable takes precedence,
+`set` still updates the stored override and reports why the effective value
+hasn't changed. `unset` removes only the stored override, not the environment
+variable.
+
+### When changes take effect
+
+Most changes take effect within about five seconds. Settings marked `yes` in
+the `RESTART` column require a daemon restart for existing daemon-side consumers:
+
+```console
+$ sbx daemon restart
+```
+
+The `set` and `unset` commands print a restart reminder when needed. Some
+settings apply only when creating a sandbox: changing a template default or disk
+size doesn't update existing sandboxes. Proxy settings have separate timing for
+CLI requests, daemon traffic, and sandbox traffic. See
+[When proxy changes take effect](upstream-proxy.md#when-changes-take-effect).
+
+## Environment variables
+
+Some settings have an environment variable equivalent, listed in the reference
+entries below. These variables configure Docker Sandboxes on the host. They
+don't set environment variables inside a sandbox.
+
+The daemon inherits environment variables when it starts. Export a variable
+before the first `sbx` command, or restart an existing daemon from the shell
+where you set it. For example:
+
+```console
+$ export DOCKER_SANDBOXES_CLIPBOARD_IMAGE_PASTE=true
+$ sbx daemon restart
+$ sbx settings get clipboard.imagePaste
+true
+```
+
+Changing your shell environment doesn't change the environment of a running
+daemon, even for settings that normally take effect without a restart. To
+return to a stored override or default, remove the variable and restart:
+
+```console
+$ unset DOCKER_SANDBOXES_CLIPBOARD_IMAGE_PASTE
+$ sbx daemon restart
+```
+
+CLI operations that read settings locally use their own environment on each
+invocation. Keep the CLI and daemon environments consistent when using these
+variables. A persistent override with `sbx settings set` avoids needing to
+export a variable in each shell.
+
+## Settings reference
+
+Each entry lists its built-in default, before overrides. An environment
+variable appears only when the setting has a direct equivalent. Use
+`sbx settings list` to inspect the values supported by your installed version.
+
+### Agents and host access
+
+#### clipboard.imagePaste {.wrap-anywhere}
+
+{{< setting-metadata type="boolean" default="false"
+  env="DOCKER_SANDBOXES_CLIPBOARD_IMAGE_PASTE" >}}
+
+Turn this on to paste screenshots and other host clipboard images into agents
+such as Claude Code and Codex with `Ctrl+V`. Text paste doesn't need this setting.
+
+```console
+$ sbx settings set clipboard.imagePaste true
+```
+
+This grants sandboxed processes access to host clipboard images. The change
+applies to running sandboxes without recreating them. Set it to `false` to
+withdraw that access. See [image paste](../faq.md#can-i-paste-images-into-an-agent)
+for supported behavior.
+
+#### claude.remoteControl {.wrap-anywhere}
+
+{{< setting-metadata type="boolean" default="false"
+  env="DOCKER_SANDBOXES_CLAUDE_REMOTE_CONTROL" >}}
+
+Turn this on before using Claude Code's `/remote-control` command inside a
+sandbox:
+
+```console
+$ sbx settings set claude.remoteControl true
+```
+
+The remote-control connection must authenticate with its own session token.
+This setting lets it do so instead of having the sandbox proxy replace that
+token with the host credential. Set it to `false` to restore credential
+replacement on that connection. Changes apply to requests from running
+sandboxes. See [Claude Code remote control](../agents/claude-code.md#remote-control).
+
+#### env.rememberHostCommands {.wrap-anywhere}
+
+{{< setting-metadata type="boolean" default="false" >}}
+
+Use this when you repeatedly run a trusted environment file and want to
+approve its host commands once, until those commands change:
+
+```console
+$ sbx settings set env.rememberHostCommands true
+```
+
+The first approval is still required. Commands run on your host with your
+permissions, outside the sandbox. Leave the setting at `false` to require
+approval on every invocation, or use `--auto-approve` to approve only one
+invocation. See [environment lifecycle commands](environment-files.md#lifecycle).
+
+#### ssh.agentForwardingEnabled {.wrap-anywhere}
+
+{{< setting-metadata type="boolean" default="true" >}}
+
+Set this to `false` when sandboxes should not be able to request signatures
+from your host SSH agent, including for Git authentication and commit signing:
+
+```console
+$ sbx settings set ssh.agentForwardingEnabled false
+$ sbx daemon restart
+```
+
+Restarting the daemon applies the change to existing forwarders. When forwarding
+is enabled, the private keys remain on the host, but sandboxed processes can
+ask the agent to use them. See [SSH agent credentials](credentials.md#ssh-agent).
+
+#### ssh.agentSocketPath {.wrap-anywhere}
+
+{{< setting-metadata type="string" default="Empty string" >}}
+
+Use a fixed path when every sandbox should use the same host SSH agent, such
+as a password manager's agent, regardless of which shell starts the sandbox:
+
+```console
+$ sbx settings set ssh.agentSocketPath "$SSH_AUTH_SOCK"
+$ sbx daemon restart
+```
+
+Run this from a shell whose `SSH_AUTH_SOCK` points to the intended agent. The
+command stores that path, not a reference to the variable. With an empty value,
+Docker Sandboxes uses the socket supplied by each client instead. Remove the
+fixed path with `sbx settings unset ssh.agentSocketPath` and restart the daemon
+to update existing forwarders.
+
+### Images and storage
+
+#### platform.images.registryMirror {.wrap-anywhere}
+
+{{< setting-metadata type="string" default="Empty string" >}}
+
+Use this when your organization routes Docker Hub pulls through a registry
+mirror. Specify a host, optionally with a port and path prefix, without a URL
+scheme:
+
+```console
+$ sbx settings set platform.images.registryMirror registry.example.com/docker-remote
+```
+
+The mirror applies to template and kit references that resolve to Docker Hub.
+References to other registries stay unchanged. An empty value disables
+mirroring.
+
+A bare, non-loopback host can also configure Docker pulls inside sandboxes
+created after the change. A mirror with a path prefix doesn't configure those
+pulls. See [registry mirrors](registry-mirror.md) for authentication, certificate
+requirements, and how to apply changes to existing sandboxes.
+
+#### platform.images.useDHI {.wrap-anywhere}
+
+{{< setting-metadata type="boolean" default="false"
+  env="DOCKER_SANDBOXES_USE_DHI" >}}
+
+Turn this on to use Docker Hardened Image variants when creating sandboxes
+with default agent templates:
+
+```console
+$ sbx settings set platform.images.useDHI true
+```
+
+For example, the default template `docker/sandbox-templates:claude-code-docker`
+becomes `dhi/sbx-templates:claude-code-docker`. The image tag stays the same.
+An explicit `--template` or a custom kit image takes precedence.
+
+Existing sandboxes keep their template. Create a sandbox after changing the
+setting to use the selected image variant.
+
+#### sandbox.disk.dockerVolume {.wrap-anywhere}
+
+{{< setting-metadata type="string" default="10g" >}}
+
+Increase this default if sandboxes need more room for Docker images,
+containers, and volumes under `/var/lib/docker`. The minimum is 512 MiB:
+
+```console
+$ sbx settings set sandbox.disk.dockerVolume 20g
+```
+
+The size applies when creating a sandbox. It doesn't resize existing volumes
+or increase the size of the sandbox workspace.
+
+To choose a size for one sandbox without changing the default:
+
+```console
+$ DOCKER_SANDBOXES_DOCKER_SIZE=30g sbx create claude ~/my-project
+```
+
+This variable applies to that creation command. It doesn't change the value
+reported by `sbx settings get sandbox.disk.dockerVolume`.
+
+### Kits
+
+#### kit.allowedSources {.wrap-anywhere}
+
+{{< setting-metadata type="JSON" default="[\"docker.io/\"]"
+  env="DOCKER_SANDBOXES_KIT_ALLOWED_SOURCES" >}}
+
+Add a publisher here before installing its kits from a remote registry or Git
+repository. The value replaces the entire allowlist, so retain any sources you
+still need:
+
+```console
+$ sbx settings set kit.allowedSources '["docker.io/","github.com/myorg/"]'
+```
+
+Prefixes match on a path-segment boundary: `github.com/myorg/` permits that
+organization's repositories, but not `github.com/myorg-other/`. The value
+`["*"]` permits any remote source. Local directories and ZIP files are controlled
+by [kit.allowLocalKits](#kitallowlocalkits), and pinned agent kits have the
+[kit.allowExtractedAgents](#kitallowextractedagents) exception.
+
+See [restrict kit sources](../customize/kits.md#restrict-kit-sources) for source
+formats and examples.
+
+#### kit.allowLocalKits {.wrap-anywhere}
+
+{{< setting-metadata type="boolean" default="true"
+  env="DOCKER_SANDBOXES_KIT_ALLOW_LOCAL" >}}
+
+Set this to `false` to require kits to come from a remote source instead of a
+local directory or ZIP file:
+
+```console
+$ sbx settings set kit.allowLocalKits false
+```
+
+Remote sources must still satisfy [kit.allowedSources](#kitallowedsources).
+Keep this enabled while developing kits locally. Allowing local kits doesn't
+exempt them from signature requirements when
+[kit.requireSignature](#kitrequiresignature) is enabled.
+
+#### kit.allowExtractedAgents {.wrap-anywhere}
+
+{{< setting-metadata type="boolean" default="true"
+  env="DOCKER_SANDBOXES_KIT_ALLOW_EXTRACTED_AGENTS" >}}
+
+Some agents that previously shipped inside Docker Sandboxes are distributed
+as kits. By default, Docker Sandboxes permits the exact pinned references it
+uses for those agents even if their sources aren't in `kit.allowedSources`,
+and exempts them from `kit.requireSignature`.
+
+To apply your source and signature requirements to those kits too:
+
+```console
+$ sbx settings set kit.allowExtractedAgents false
+```
+
+After this change, launching one of those agents can fail unless you allow its
+source and, when signatures are required, it has a signature from a trusted
+signer. The default exception applies only to the pinned references, not to
+other kits from the same publisher.
+
+#### kit.requireSignature {.wrap-anywhere}
+
+{{< setting-metadata type="boolean" default="false"
+  env="DOCKER_SANDBOXES_KIT_REQUIRE_SIGNATURE" >}}
+
+Turn this on to reject unsigned kits and kits whose signatures don't match
+your trusted signers. Configure [kit.trustedSigners](#kittrustedsigners) first,
+then require signatures:
+
+```console
+$ sbx settings set kit.requireSignature true
+```
+
+The check applies when installing kits from local directories, Git, or OCI
+registries. ZIP kits can't carry verifiable signatures and are rejected.
+Pinned agent kits remain exempt while
+[kit.allowExtractedAgents](#kitallowextractedagents) is `true`.
+
+A signature covers the kit's `spec.yaml` and `files/` content. It doesn't pin
+image tags or verify downloads performed by the kit's commands. See
+[sign and verify kits](../customize/kits.md#sign-and-verify-kits).
+
+#### kit.trustedSigners {.wrap-anywhere}
+
+{{< setting-metadata type="JSON" default="Docker employee identities"
+  env="DOCKER_SANDBOXES_KIT_TRUSTED_SIGNERS" >}}
+
+Set the identities or public keys whose kit signatures you trust. The value is
+a JSON array. Each entry describes either a keyless signer or a public key, and
+a signature can match any entry.
+
+For a keyless signer, specify both the identity and its OpenID Connect issuer:
+
+```console
+$ sbx settings set kit.trustedSigners \
+    '[{"identity":"release-bot@example.com","issuer":"https://accounts.google.com"}]'
+```
+
+For a public key:
+
+```console
+$ sbx settings set kit.trustedSigners '[{"key":"/path/to/cosign.pub"}]'
+```
+
+Each command replaces the whole list. To trust both, include both objects in
+one array. The default policy trusts Docker employee identities ending in
+`@docker.com`, attested by Google's issuer. Setting trusted signers alone
+doesn't require signatures: also enable
+[kit.requireSignature](#kitrequiresignature).
+
+#### kit.ignoreTransparencyLog {.wrap-anywhere}
+
+{{< setting-metadata type="boolean" default="false"
+  env="DOCKER_SANDBOXES_KIT_IGNORE_TLOG" >}}
+
+Use this for private kits whose keyless signatures were created with
+`--tlog-upload=false`, so verification doesn't require a public Rekor
+transparency log entry:
+
+```console
+$ sbx settings set kit.ignoreTransparencyLog true
+```
+
+Signature and signer verification still apply. These signatures must provide a
+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.
+
+### MCP gateway
+
+#### mcp.forceLocalGateway {.wrap-anywhere}
+
+{{< setting-metadata type="boolean" default="false" >}}
+
+Set this to `true` to use the local MCP gateway when your account would
+otherwise use the SaaS gateway:
+
+```console
+$ sbx settings set mcp.forceLocalGateway true
+$ sbx daemon restart
+```
+
+The daemon caches its gateway selection, so a restart is required after changing
+this setting. It doesn't override a gateway selected by organization governance.
+Set it back to `false` and restart to return to automatic selection. See
+[MCP gateway](../mcp-gateway.md) for server registration and agent setup.
+
+### Diagnostics
+
+#### diagnostics.autoUpload {.wrap-anywhere}
+
+{{< setting-metadata type="string" default="Empty string" >}}
+
+Choose whether Docker Sandboxes may automatically upload diagnostic bundles
+after eligible daemon errors:
+
+- `yes`: Consent to automatic uploads.
+- `no`: Decline automatic uploads and suppress further consent prompts.
+- Empty string: No recorded decision. Docker Sandboxes may prompt for consent,
+  but doesn't automatically upload without it.
+
+For example, decline automatic uploads:
+
+```console
+$ sbx settings set diagnostics.autoUpload no
+```
+
+Use `sbx settings unset diagnostics.autoUpload` to clear the decision. Read
+[automatic diagnostics uploads](../troubleshooting.md#enable-automatic-diagnostics-uploads)
+for what bundles contain before opting in. This controls automatic uploads,
+not an explicit `sbx diagnose --upload` request.
+
+#### diagnostics.autoUploadErrorCooldownInDays {.wrap-anywhere}
+
+{{< setting-metadata type="integer" default="1" >}}
+
+Increase this value to upload automatic diagnostic bundles less frequently.
+For example, allow at most one automatic upload per seven days:
+
+```console
+$ sbx settings set diagnostics.autoUploadErrorCooldownInDays 7
+```
+
+The cooldown applies across all eligible errors, not separately to each error
+type. Values below one are treated as one day. This setting doesn't grant
+upload consent: [diagnostics.autoUpload](#diagnosticsautoupload) must be `yes`.
+
+### Upstream proxies and TLS
+
+Upstream proxy support is experimental. Use these settings to control how
+outbound traffic reaches the network. See [upstream proxies](upstream-proxy.md)
+for setup and [when changes take effect](upstream-proxy.md#when-changes-take-effect).
+
+The standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` variables and their
+lowercase forms are fallbacks for proxy selection, not direct overrides of the
+`proxy` and `no_proxy` settings.
+
+#### proxy {.wrap-anywhere}
+
+{{< setting-metadata type="string" default="Empty string" >}}
+
+Set a shared upstream proxy when both sandbox traffic and host-side Docker
+Sandboxes traffic should pass through it:
+
+```console
+$ sbx settings set proxy http://proxy.corp:3128
+$ sbx daemon restart
+```
+
+The value can be an HTTP, HTTPS, or SOCKS5 proxy URL, a PAC source, `system` to
+use the operating system's proxy, or `direct` to bypass upstream proxies. An
+empty value falls back to the standard proxy environment variables and then the
+operating system's proxy settings.
+
+The scope-specific settings below take precedence over this shared value.
+See [proxy value formats](upstream-proxy.md#set-a-proxy-manually) and
+[proxy precedence](upstream-proxy.md#precedence).
+
+#### proxy.sandbox {.wrap-anywhere}
+
+{{< setting-metadata type="string" default="Empty string"
+  env="DOCKER_SANDBOXES_PROXY" >}}
+
+Use this when traffic from inside sandboxes needs a different route from the
+daemon and CLI. For example, send sandbox traffic through a SOCKS5 proxy:
+
+```console
+$ sbx settings set proxy.sandbox socks5h://proxy.corp:1080
+$ sbx daemon restart
+```
+
+With `socks5h://`, the proxy resolves destination names. Use `direct` to bypass
+the shared proxy for sandbox traffic, or unset this setting to inherit `proxy`.
+It doesn't affect daemon traffic. Sandboxes created after the change use the
+updated value; existing sandbox proxies require a daemon restart.
+
+#### proxy.daemon {.wrap-anywhere}
+
+{{< setting-metadata type="string" default="Empty string" >}}
+
+Use this to route the daemon's requests, such as image pulls, separately from
+sandbox traffic. Supported host CLI requests, including `sbx login` and
+`sbx diagnose --upload`, also use this scope.
+
+For example, keep a shared proxy for sandbox traffic while letting the daemon
+connect directly:
+
+```console
+$ sbx settings set proxy.daemon direct
+$ sbx daemon restart
+```
+
+Unset this setting to inherit `proxy`. Supported CLI requests use changes on
+the next invocation; the daemon's own requests require a restart.
+
+#### no_proxy {.wrap-anywhere}
+
+{{< setting-metadata type="string" default="Empty string" >}}
+
+List destinations that should bypass the selected upstream proxy. Use a
+comma-separated string of hosts, domain suffixes, IP addresses, or CIDR ranges:
+
+```console
+$ sbx settings set no_proxy "registry.internal,10.0.0.0/8"
+$ sbx daemon restart
+```
+
+This shared list applies to sandbox and daemon traffic unless a scope-specific
+list replaces it. A value of `*` bypasses the upstream proxy for all destinations.
+Proxy exclusions don't grant network access: sandbox requests must still pass
+[network policy](../governance/access-controls/network.md).
+
+#### no_proxy.sandbox {.wrap-anywhere}
+
+{{< setting-metadata type="string" default="Empty string"
+  env="DOCKER_SANDBOXES_NO_PROXY" >}}
+
+Use this when only sandbox traffic should bypass the upstream proxy for a set
+of destinations. For example, connect directly to cluster services:
+
+```console
+$ sbx settings set no_proxy.sandbox "*.svc.cluster.local"
+$ sbx daemon restart
+```
+
+A non-empty value replaces the shared `no_proxy` list for sandbox traffic; it
+doesn't append to it. Include any shared exclusions that sandboxes still need.
+Unset it to inherit `no_proxy` again. Existing sandbox proxies require a daemon
+restart.
+
+#### no_proxy.daemon {.wrap-anywhere}
+
+{{< setting-metadata type="string" default="Empty string" >}}
+
+Use this when the daemon and supported CLI requests need different proxy
+exclusions from sandbox traffic. For example, pull images directly from an
+internal registry:
+
+```console
+$ sbx settings set no_proxy.daemon "registry.internal"
+$ sbx daemon restart
+```
+
+A non-empty value replaces the shared `no_proxy` list for this scope. It doesn't
+change sandbox exclusions. Unset it to inherit `no_proxy` again. Supported CLI
+requests use changes on the next invocation; daemon requests require a restart.
+
+#### proxy.integratedAuth {.wrap-anywhere}
+
+{{< setting-metadata type="boolean" default="false" >}}
+
+Turn this on when a corporate proxy requires NTLM or Kerberos authentication
+using your Windows sign-in identity:
+
+```console
+$ sbx settings set proxy.integratedAuth true
+$ sbx daemon restart
+```
+
+It applies to both sandbox and daemon proxy traffic. Authentication happens on
+the host, so the Windows credentials don't enter the sandbox. It has no effect
+on macOS or Linux. For cross-platform authentication with credentials in a
+proxy URL, see [proxy authentication](upstream-proxy.md#authentication).
+
+#### tls.allowNegativeSerial {.wrap-anywhere}
+
+{{< setting-metadata type="boolean" default="false"
+  env="DOCKER_SANDBOXES_TLS_ALLOW_NEGATIVE_SERIAL" >}}
+
+Use this compatibility setting when HTTPS requests fail with
+`x509: negative serial number` because a TLS-inspecting proxy issues
+certificates with negative serial numbers:
+
+```console
+$ sbx settings set tls.allowNegativeSerial true
+$ sbx daemon restart
+```
+
+It relaxes certificate validation to accept those serial numbers. It doesn't
+make an untrusted certificate authority trusted or resolve other certificate
+errors. For an untrusted internal CA, see
+[certificate troubleshooting](../troubleshooting.md#api-calls-fail-with-a-certificate-error).
+
+### Shared agent skills
+
+Shared agent skills are experimental.
+
+#### skills.defaultMode {.wrap-anywhere}
+
+{{< setting-metadata type="string" default="readonly" >}}
+
+Choose how future sandboxes use the shared agent skills store when you omit
+`--skills`:
+
+- `readonly`: Agents can read shared skills but can't change the store.
+- `readwrite`: Agents can read and modify skills used by other sandboxes.
+- `off`: Don't mount the shared store.
+
+For example, omit the shared store by default:
+
+```console
+$ sbx settings set skills.defaultMode off
+```
+
+An explicit `--skills` value or environment-file `skills` value overrides this
+default. Existing sandboxes retain their mounts: recreate them to change their
+access mode. See [share agent skills](../workflows/agent-skills.md) for setup
+and the consequences of sharing a writable store.
+
+## Command reference
+
+### sbx settings list
+
+List settings. Alias: `sbx settings ls`.
+
+Use `--json` for complete records as JSON, or `--no-trunc` for full text. These
+options are mutually exclusive.
+
+### sbx settings get \<KEY\>
+
+Print one effective value.
+
+Use `--json` for the complete setting record.
+
+### sbx settings set \<KEY\> \<VALUE\>
+
+Write a user override.
+
+Values are parsed as `bool`, `int`, `float`, `string`, or `json`, according to
+the setting's type.
+
+### sbx settings unset \<KEY\>
+
+Remove a user override.
+
+Use `sbx settings <COMMAND> --help` for command help.

content/manuals/ai/sandboxes/configuration/upstream-proxy.md

@@ -39,7 +39,8 @@ your OS has no proxy configured, traffic goes direct.
 
 ## Set a proxy manually
 
-Use `sbx settings set` to override the default for one or both kinds of traffic:
+Use [`sbx settings set`](settings.md#change-a-setting) to override the default
+for one or both kinds of traffic:
 
 ```console
 $ sbx settings set proxy http://proxy.corp:3128          # both kinds of traffic
@@ -85,9 +86,8 @@ environment variables, so existing setups keep working without migration:
   form of `proxy.sandbox` and `no_proxy.sandbox`. They apply to sandbox traffic
   only and never affect daemon traffic.
 
-The daemon reads these variables when it starts, so set them before your first
-`sbx` command, or restart the daemon for a change to affect daemon and sandbox
-traffic. Supported CLI clients read their environment on each invocation.
+For how to apply environment variable changes to the CLI and daemon, see
+[Settings environment variables](settings.md#environment-variables).
 
 ## Precedence
 

content/manuals/ai/sandboxes/customize/kits.md

@@ -490,8 +490,8 @@ ERROR: resolve kits: kit "git+https://github.com/docker/sbx-kits-contrib.git#dir
 ```
 
 To allow another publisher, add its host or host/path prefix to the
-`kit.allowedSources` setting. The setting replaces the whole list, so include
-the entries you want to keep:
+[`kit.allowedSources`](../configuration/settings.md#kitallowedsources) setting.
+The setting replaces the whole list, so include the entries you want to keep:
 
 ```console
 $ sbx settings set kit.allowedSources '["docker.io/","github.com/docker/"]'
@@ -510,8 +510,8 @@ require a remote source:
 $ sbx settings set kit.allowLocalKits false
 ```
 
-For non-interactive use, both settings have environment-variable equivalents:
-`DOCKER_SANDBOXES_KIT_ALLOWED_SOURCES` and `DOCKER_SANDBOXES_KIT_ALLOW_LOCAL`.
+For defaults and environment variable equivalents, see the
+[kit settings reference](../configuration/settings.md#kits).
 
 ## Sign and verify kits
 
@@ -548,8 +548,9 @@ ZIP kits can't carry verifiable signatures.
 
 ### Require signed kits
 
-Set a trusted signer policy for the identities or keys you trust before
-requiring signatures. Otherwise, `sbx` uses the default policy, which trusts
+Set [`kit.trustedSigners`](../configuration/settings.md#kittrustedsigners) to
+the identities or keys you trust before requiring signatures. Otherwise, `sbx`
+uses the default policy, which trusts
 Docker employee identities attested by Google's OpenID Connect issuer. A
 keyless policy must specify both the certificate identity and its OpenID
 Connect issuer:

content/manuals/ai/sandboxes/faq.md

@@ -167,7 +167,7 @@ sends it directly. Pasting an image or screenshot with `Ctrl+V` is different:
 the agent reads it from your host clipboard, and the sandbox blocks that access
 unless you opt in.
 
-Turn it on with a local setting:
+Turn on [`clipboard.imagePaste`](configuration/settings.md#clipboardimagepaste):
 
 ```console
 $ sbx settings set clipboard.imagePaste true

content/manuals/ai/sandboxes/security/_index.md

@@ -30,7 +30,9 @@ What crosses the boundary into the VM:
   [network policy](defaults/) are proxied through the host.
 - Shared agent skills: sandboxes created for supported agents mount a
   persistent host-side store read-only by default at the agent's skills
-  directory. Use `--skills` or `skills.defaultMode` to choose another mode at
+  directory. Use `--skills` or
+  [`skills.defaultMode`](../configuration/settings.md#skillsdefaultmode)
+  to choose another mode at
   creation. Existing sandboxes retain their mounts until recreated.
 - **MCP gateway traffic:** supported agents connect to a host-side MCP gateway
   endpoint. The gateway brokers access to registered MCP servers.

content/manuals/ai/sandboxes/security/defaults.md

@@ -40,7 +40,9 @@ workspace modes and what to review after a direct-mount session.
 ## Shared skills defaults
 
 Sandboxes created for supported agents mount a persistent shared skills store
-read-only by default. The `skills.defaultMode` setting can change this default,
+read-only by default. The
+[`skills.defaultMode`](../configuration/settings.md#skillsdefaultmode) setting
+can change this default,
 and `--skills` overrides it for a sandbox at creation. A sandbox with `readwrite` access can change skills that other
 participating sandboxes load, including those with `readonly` access. Use
 `--skills=off` when creating a sandbox to omit the shared store. Existing

content/manuals/ai/sandboxes/troubleshooting.md

@@ -128,7 +128,8 @@ ERROR: resolve kits: kit "git+https://github.com/docker/sbx-kits-contrib.git#dir
 
 `sbx` restricts kit installs to an allowlist of sources, which defaults to
 Docker Hub (`docker.io/`) only. Add the kit's publisher to the
-`kit.allowedSources` setting, keeping the entries you want to retain:
+[`kit.allowedSources`](configuration/settings.md#kitallowedsources) setting,
+keeping the entries you want to retain:
 
 ```console
 $ sbx settings set kit.allowedSources '["docker.io/","github.com/docker/"]'
@@ -394,8 +395,10 @@ If the socket exists but forwarding still fails, check the
 Docker Sandboxes can sign Git commits with SSH keys from your host agent.
 For setup steps, see [Commit signing](workflows/git.md#commit-signing).
 
-Forwarding is enabled by default. Confirm that it hasn't been disabled and
-check whether a fixed socket path is configured:
+Forwarding is enabled by default. Check
+[`ssh.agentForwardingEnabled`](configuration/settings.md#sshagentforwardingenabled)
+and [`ssh.agentSocketPath`](configuration/settings.md#sshagentsocketpath) to
+confirm that forwarding is enabled and inspect the socket selection:
 
 ```console
 $ sbx settings get ssh.agentForwardingEnabled
@@ -513,7 +516,9 @@ If you have set custom `XDG_STATE_HOME`, `XDG_CACHE_HOME`, or
 
 ## Enable automatic diagnostics uploads
 
-To opt in to automatic diagnostics uploads after certain daemon errors, run:
+To opt in to automatic diagnostics uploads after certain daemon errors, set
+[`diagnostics.autoUpload`](configuration/settings.md#diagnosticsautoupload) to
+`yes`:
 
 ```console
 $ sbx settings set diagnostics.autoUpload yes

content/manuals/ai/sandboxes/workflows/agent-skills.md

@@ -137,16 +137,14 @@ For example, create a sandbox without the shared store:
 $ sbx run --skills=off claude
 ```
 
-To change the default for future sandboxes, set `skills.defaultMode` to `off`,
+To change the default for future sandboxes, set
+[`skills.defaultMode`](../configuration/settings.md#skillsdefaultmode) to `off`,
 `readonly`, or `readwrite`:
 
 ```console
 $ sbx settings set skills.defaultMode readonly
 ```
 
-When no mode is specified, the daemon uses `skills.defaultMode`, whose built-in
-value is `readonly`. An explicit `--skills` value overrides that default.
-
 The mode is applied only when a sandbox is created. Upgrading `sbx` or changing
 `skills.defaultMode` leaves existing sandbox mounts unchanged. Remove and
 recreate a sandbox to change its mode. Sandboxes created without shared skills

layouts/_shortcodes/setting-metadata.html

@@ -0,0 +1,21 @@
+{{ if or (not (isset .Params "type")) (not (isset .Params "default")) }}
+  {{ errorf "setting-metadata requires type and default: %s" .Position }}
+{{ end }}
+<dl
+  class="not-prose my-4 grid grid-cols-2 gap-x-6 gap-y-3 rounded-lg border border-gray-200 bg-gray-50 p-4 text-sm shadow-sm dark:border-gray-700 dark:bg-gray-900"
+>
+  <div class="min-w-0">
+    <dt class="text-gray-600 dark:text-gray-400">Type</dt>
+    <dd class="mt-1 wrap-anywhere">{{ .Get "type" }}</dd>
+  </div>
+  <div class="min-w-0">
+    <dt class="text-gray-600 dark:text-gray-400">Default</dt>
+    <dd class="mt-1 wrap-anywhere">{{ .Get "default" }}</dd>
+  </div>
+  {{ with .Get "env" }}
+    <div class="col-span-2 min-w-0">
+      <dt class="text-gray-600 dark:text-gray-400">Environment variable</dt>
+      <dd class="mt-1 wrap-anywhere"><code>{{ . }}</code></dd>
+    </div>
+  {{ end }}
+</dl>

layouts/_shortcodes/setting-metadata.markdown.md

@@ -0,0 +1,7 @@
+{{ if or (not (isset .Params "type")) (not (isset .Params "default")) }}
+  {{ errorf "setting-metadata requires type and default: %s" .Position }}
+{{ end }}
+- Type: {{ .Get "type" }}
+- Default: {{ .Get "default" }}
+{{ with .Get "env" }}- Environment variable: `{{ . }}`
+{{ end }}