docker / docker/docs

[docs-scanner] Contradictory information about when sandbox-scoped secrets take effect

Open
#25,906 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Markdown
Stars
4.7k
Forks
8.5k
Avg merge
2d 18h
Merged PRs (30d)
108

Description

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

Issue

The page contains contradictory information about when sandbox-scoped secrets take effect. In the "Store a secret" section, it states:

A sandbox-scoped secret takes effect immediately, even if the sandbox is running. A global secret only applies when a sandbox is created. If you set or change a global secret while a sandbox is running, recreate the sandbox for the new value to take effect.

However, in the "Custom secrets" section, it states:

Custom secrets are global by default. Pass --sandbox to scope one to a specific sandbox.

And then in upstream-proxy.md, when discussing proxy settings (which are analogous to secrets in terms of sandbox configuration), it clearly states:

Sandbox scope (proxy.sandbox, no_proxy.sandbox, and the sandbox side of proxy and no_proxy) is re-resolved every time a sandbox is created or restarted. A change takes effect on the next sandbox you create or restart; already-running sandboxes keep the proxy they were created with.

Why this matters

A reader trying to understand when to restart their sandbox after changing a sandbox-scoped secret will get conflicting information. The first quote says sandbox-scoped secrets "take effect immediately, even if the sandbox is running," while the proxy documentation (which describes similar sandbox-scoped configuration) says changes only take effect "on the next sandbox you create or restart."

This contradiction will lead users to either:

  1. Expect immediate effect and be confused when secrets don't work
  2. Unnecessarily restart sandboxes when it's not needed
Suggested fix

Verify the actual behavior and make the documentation consistent. If sandbox-scoped secrets truly do take effect immediately (unlike proxy settings), explain the mechanism that makes this different from other sandbox-scoped configuration. If they don't take effect immediately, correct the note to match the proxy documentation's behavior.

Consider adding a cross-reference between these two pages since they both deal with sandbox-scoped configuration timing.


Found by nightly documentation quality scanner

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with content/manuals/ai/sandboxes/configuration/credentials.md, comparing the “Store a secret” and “Custom secrets” sections, then read upstream-proxy.md for the documented restart behavior. Verify when sandbox-scoped secret changes take effect and update the documentation so the behavior is consistent, adding a cross-reference if appropriate.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.