diff --git a/content/manuals/ai/sandboxes/faq.md b/content/manuals/ai/sandboxes/faq.md
index b8584cac88ca..06841b622d7e 100644
--- a/content/manuals/ai/sandboxes/faq.md
+++ b/content/manuals/ai/sandboxes/faq.md
@@ -158,3 +158,27 @@ the sandbox.
 Collocating skills and other agent configuration with the project itself is a
 good practice regardless of sandboxes. It's versioned alongside the code and
 evolves with the project as it changes.
+
+## Can I use Docker Sandboxes on headless Linux?
+
+Yes. On Linux, `sbx` stores secrets in the Secret Service exposed by your
+desktop keyring, such as GNOME Keyring or KDE Wallet. Headless servers and some
+WSL setups have no running Secret Service, so `sbx` falls back to an encrypted
+file under `$XDG_CONFIG_HOME/com.docker.sandboxes`, which defaults to
+`~/.config/com.docker.sandboxes` when `$XDG_CONFIG_HOME` is unset. No setup is
+required. When you store a secret on such a host, `sbx` prints a notice:
+
+```text
+No keychain detected - this secret will be stored in an encrypted file on disk
+```
+
+The file is encrypted at rest and protected by `0700` directory permissions,
+the same posture as `~/.docker/config.json`. It's weaker than an OS keychain,
+which also mediates access per application.
+
+To keep secrets in a keyring instead, run a Secret Service on the host before
+storing them: install `gnome-keyring` and start `dbus-run-session`, or run the
+keyring daemon under a login session that unlocks it. Once a working Secret
+Service is available, `sbx` stores new
+secrets in the keychain again. For where each platform keeps secrets, see
+[Where secrets are stored](security/credentials.md#where-secrets-are-stored).
diff --git a/content/manuals/ai/sandboxes/security/credentials.md b/content/manuals/ai/sandboxes/security/credentials.md
index 73a9ce6b8bce..c9d423dc6b0a 100644
--- a/content/manuals/ai/sandboxes/security/credentials.md
+++ b/content/manuals/ai/sandboxes/security/credentials.md
@@ -61,6 +61,36 @@ provider-specific details.
 identifier. Built-in agents declare a fixed set of services. Custom kits can
 declare their own. The same `sbx secret set` flow works for both.
 
+### Where secrets are stored
+
+The store backing `sbx secret set` depends on your operating system:
+
+- macOS: the system Keychain.
+- Windows: the Windows Credential Manager.
+- Linux: the Secret Service exposed by your desktop keyring, such as GNOME
+  Keyring or KDE Wallet.
+
+The Ubuntu package depends on GNOME Keyring, so a standard desktop install
+needs no extra setup.
+
+On Linux hosts without a running Secret Service — headless servers and some
+WSL setups — `sbx` falls back to an encrypted file under your user config
+directory `$XDG_CONFIG_HOME/com.docker.sandboxes`, which defaults to
+`~/.config/com.docker.sandboxes` when `$XDG_CONFIG_HOME` is unset. The fallback
+is automatic and needs no configuration. When you store a secret this way,
+`sbx` prints a notice:
+
+```text
+No keychain detected - this secret will be stored in an encrypted file on disk
+```
+
+The file is encrypted at rest and protected by `0700` directory permissions,
+the same posture as `~/.docker/config.json`. This is weaker than an OS
+keychain, which also mediates access per application. If you start a Secret
+Service on the host later, `sbx` stores new secrets in the keychain again. For
+more on running sandboxes without a desktop keyring, see
+[Can I use Docker Sandboxes on headless Linux?](../faq.md#can-i-use-docker-sandboxes-on-headless-linux)
+
 ### Store a secret
 
 ```console
@@ -303,9 +333,10 @@ The proxy reads the variable from your terminal session. See individual
 
 ## Best practices
 
-- Use [stored secrets](#stored-secrets) over environment variables. The OS
-  keychain encrypts credentials at rest and controls access, while environment
-  variables are plaintext in your shell.
+- Use [stored secrets](#stored-secrets) over environment variables. Stored
+  secrets are encrypted at rest in the OS keychain (or an encrypted file on
+  Linux hosts without a keychain), while environment variables are plaintext in
+  your shell. See [Where secrets are stored](#where-secrets-are-stored).
 - Don't set API keys manually inside the sandbox. Sandbox agents are
   pre-configured to use proxy-managed credentials.
 - For Claude Code and Codex, OAuth is another secure option: the flow runs on