From 9bd53c21f8ae3127a2db29d83af655401c2fc33f Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 2 Jun 2026 12:18:19 +0200 Subject: [PATCH 1/3] sbx: document Linux keychain fallback for headless hosts On Linux without a running Secret Service (headless servers, some WSL setups), sbx falls back to an encrypted on-disk store instead of the OS keychain. Document where secrets are stored per platform in the credentials page and add a headless-Linux FAQ entry. Co-Authored-By: Claude Opus 4.8 (1M context) --- content/manuals/ai/sandboxes/faq.md | 24 +++++++++++++ .../ai/sandboxes/security/credentials.md | 34 +++++++++++++++++-- 2 files changed, 55 insertions(+), 3 deletions(-) diff --git a/content/manuals/ai/sandboxes/faq.md b/content/manuals/ai/sandboxes/faq.md index b8584cac88ca..529494295b69 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 (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` (usually +`~/.config/com.docker.sandboxes`). 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. A common setup installs `gnome-keyring` and starts +`dbus-run-session`, or runs 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..ac6389286da0 100644 --- a/content/manuals/ai/sandboxes/security/credentials.md +++ b/content/manuals/ai/sandboxes/security/credentials.md @@ -61,6 +61,33 @@ 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`, usually +`~/.config/com.docker.sandboxes`). 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 +330,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 From 068f34640df06ebee88ffd34d0061d86d4c3b9ea Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 3 Jun 2026 10:26:27 +0200 Subject: [PATCH 2/3] =?UTF-8?q?sbx:=20address=20review=20nits=20=E2=80=94?= =?UTF-8?q?=20drop=20parentheses,=20parallel=20list?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Remove parentheses from the XDG config path per the style guide and make the per-OS storage list parallel by moving the Ubuntu package note into prose. Co-Authored-By: Claude Opus 4.8 (1M context) --- content/manuals/ai/sandboxes/faq.md | 10 +++++----- .../manuals/ai/sandboxes/security/credentials.md | 13 ++++++++----- 2 files changed, 13 insertions(+), 10 deletions(-) diff --git a/content/manuals/ai/sandboxes/faq.md b/content/manuals/ai/sandboxes/faq.md index 529494295b69..1c23fa5ba920 100644 --- a/content/manuals/ai/sandboxes/faq.md +++ b/content/manuals/ai/sandboxes/faq.md @@ -162,11 +162,11 @@ 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 (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` (usually -`~/.config/com.docker.sandboxes`). No setup is required — when you store a -secret on such a host, `sbx` prints a notice: +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 diff --git a/content/manuals/ai/sandboxes/security/credentials.md b/content/manuals/ai/sandboxes/security/credentials.md index ac6389286da0..c9d423dc6b0a 100644 --- a/content/manuals/ai/sandboxes/security/credentials.md +++ b/content/manuals/ai/sandboxes/security/credentials.md @@ -68,14 +68,17 @@ 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. + 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`, usually -`~/.config/com.docker.sandboxes`). The fallback is automatic and needs no -configuration. When you store a secret this way, `sbx` prints a notice: +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 From ae4fa302d4552da292b0defe0ce2c86549f29fbb Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 3 Jun 2026 10:32:57 +0200 Subject: [PATCH 3/3] sbx: tighten headless-Linux FAQ wording Split the em-dash into two sentences and replace the "a common setup" hedge with a direct imperative, per review. Co-Authored-By: Claude Opus 4.8 (1M context) --- content/manuals/ai/sandboxes/faq.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/manuals/ai/sandboxes/faq.md b/content/manuals/ai/sandboxes/faq.md index 1c23fa5ba920..06841b622d7e 100644 --- a/content/manuals/ai/sandboxes/faq.md +++ b/content/manuals/ai/sandboxes/faq.md @@ -166,7 +166,7 @@ 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: +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 @@ -177,8 +177,8 @@ 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. A common setup installs `gnome-keyring` and starts -`dbus-run-session`, or runs the keyring daemon under a login session that -unlocks it. Once a working Secret Service is available, `sbx` stores new +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).