Skip to content

docs(sandboxes): correct the on-disk secret store's protection claim #25875

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

Merged
dvdksn merged 1 commit into from
Aug 18, 2026
+24 −18
Merged

docs(sandboxes): correct the on-disk secret store's protection claim #25875

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
14 changes: 8 additions & 6 deletions content/manuals/ai/sandboxes/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -225,18 +225,20 @@ $ sbx settings set clipboard.imagePaste false

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
WSL setups have no running Secret Service, so `sbx` falls back to a 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
No keychain detected - this secret will be stored on disk, protected by file permissions rather than a password
```

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.
`sbx` stores the file in a directory with `0700` permissions, the same
file-permission model used for `~/.docker/config.json`. Any user or process that
can read the file can retrieve the stored credentials, so treat the directory as
sensitive. Where available, prefer a keychain, which 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
Expand Down
28 changes: 16 additions & 12 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 @@ -59,22 +59,25 @@ The store backing `sbx secret set` depends on your operating system:
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
On Linux hosts without a running Secret Service — headless servers and some WSL
setups — `sbx` falls back to a 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
No keychain detected - this secret will be stored on disk, protected by file permissions rather than a password
```

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
`sbx` stores the file in a directory with `0700` permissions, the same
file-permission model used for `~/.docker/config.json`. Any user or process that
can read the file can retrieve the stored credentials, so treat the directory as
sensitive. Where available, prefer a keychain, which 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
Expand Down Expand Up @@ -445,9 +448,10 @@ $ sbx secret rm --sandbox my-sandbox --registry ghcr.io -f

## Best practices

- Use [stored secrets](#stored-secrets) to provide credentials. They are
encrypted at rest in the OS keychain (or an encrypted file on Linux hosts
without a keychain). See [Where secrets are stored](#where-secrets-are-stored).
- Use [stored secrets](#stored-secrets) to provide credentials. The OS keychain
protects them at rest; on Linux hosts without a keychain they are held in a
permission-protected file instead. 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.
- Registry credentials stay on the host and are injected by the proxy when a
Expand Down