Skip to content

sbx: document Linux keychain fallback for headless hosts #25232

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dvdksn wants to merge 3 commits into
base: main
Choose a base branch
from
+58 −3
Open

sbx: document Linux keychain fallback for headless hosts #25232

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9bd53c2
sbx: document Linux keychain fallback for headless hosts
dvdksn Jun 2, 2026
068f346
sbx: address review nits — drop parentheses, parallel list
dvdksn Jun 3, 2026
ae4fa30
sbx: tighten headless-Linux FAQ wording
dvdksn Jun 3, 2026
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
24 changes: 24 additions & 0 deletions content/manuals/ai/sandboxes/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Copy Markdown

@docker-agent docker-agent Jun 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[LIKELY HIGH] Linux fallback path may use the wrong namespace

Both new sections document the Linux credential fallback path as $XDG_CONFIG_HOME/com.docker.sandboxes (defaulting to ~/.config/com.docker.sandboxes), but every other Linux XDG path in the project uses the namespace sandboxes — not com.docker.sandboxes. For example, troubleshooting.md shows:

~/.local/state/sandboxes/
~/.cache/sandboxes/
~/.config/sandboxes/

The com.docker.sandboxes naming is macOS convention (reverse-DNS Application Support directories). If the actual Linux on-disk path is ~/.config/sandboxes/ (consistent with all other Linux paths), the documentation would mislead users looking for the encrypted fallback file.

Please confirm the correct path against the implementation in docker/sandboxes#3231.

`~/.config/com.docker.sandboxes` when `$XDG_CONFIG_HOME` is unset. No setup is
Comment thread
dvdksn marked this conversation as resolved.
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).
37 changes: 34 additions & 3 deletions content/manuals/ai/sandboxes/security/credentials.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Comment thread
dvdksn marked this conversation as resolved.
- Windows: the Windows Credential Manager.
- Linux: the Secret Service exposed by your desktop keyring, such as GNOME
Comment thread
dvdksn marked this conversation as resolved.
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
Copy link
Copy Markdown

@docker-agent docker-agent Jun 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[LIKELY HIGH] Linux fallback path may use the wrong namespace

Same issue as above: $XDG_CONFIG_HOME/com.docker.sandboxes (defaulting to ~/.config/com.docker.sandboxes) does not match the Linux XDG namespace pattern used elsewhere in the docs (sandboxes, not com.docker.sandboxes). If the actual path is ~/.config/sandboxes/, users following this documentation won't find the file.

`~/.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
Expand Down Expand Up @@ -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
Expand Down