Merge pull request #26057 from dvdksn/docs/sandbox-npm-custom-secret

docs: clarify custom secrets and add a private npm example

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

@@ -317,8 +317,15 @@ when an agent validates the environment variable format at boot, or when the
 credential lands in a request body rather than a header — use
 `sbx secret set-custom`. The secret is keyed on one or more target domains, an
 environment variable name, and an optional placeholder string, instead of a
-service identifier. Custom secrets are global by default. Pass `--sandbox` to
-scope one to a specific sandbox.
+service identifier.
+
+Prefer the [service-based flow](#stored-secrets) whenever it's an option —
+the kit handles the wiring; you only provide the value.
+
+### Set a custom secret
+
+Custom secrets are global by default. Pass `--sandbox` to scope one to a
+specific sandbox.
 
 ```console
 $ sbx secret set-custom \
@@ -327,6 +334,20 @@ $ sbx secret set-custom \
     --value <secret>
 ```
 
+> [!WARNING]
+> Passing the secret as `--value <secret>` records it in your shell history
+> and exposes it to other processes running as your user. Avoid pasting
+> real credentials inline — read the value from a variable that's already
+> in your environment, and clear shell history if a real secret was passed
+> on the command line.
+
+Inside the sandbox, `API_KEY` is set to a generated placeholder (for example,
+`sbx-cs-<rand>`). When a sandboxed process sends a request to any of the
+configured hosts and the placeholder appears anywhere in the request, the
+proxy replaces it with the real value. The agent never sees the real secret.
+
+### Target multiple hosts
+
 Repeat `--host` to cover multiple domains with the same secret — useful when
 an API is split across related hostnames or when two unrelated endpoints share
 a credential:
@@ -344,6 +365,8 @@ A `--host` value can also use wildcards, with the same syntax as
 single label (`*.example.com` covers `api.example.com`) and `**` matches any
 number (`**.example.com` covers `api.example.com` and `v2.api.example.com`).
 
+### Resolve custom secrets dynamically
+
 Custom secrets also accept [dynamic secret sources](#use-a-dynamic-secret-source).
 Replace `--value` with either `--ref` or `--command`:
 
@@ -359,20 +382,50 @@ duration to cache the resolved value. The verification and error-output flags
 work the same as they do for service secrets. `--ref` and `--command` can't be
 combined with `--value` or `--token`.
 
-> [!WARNING]
-> Passing the secret as `--value <secret>` records it in your shell history
-> and exposes it to other processes running as your user. Avoid pasting
-> real credentials inline — read the value from a variable that's already
-> in your environment, and clear shell history if a real secret was passed
-> on the command line.
+### Install npm packages from GitHub Packages
 
-Inside the sandbox, `API_KEY` is set to a generated placeholder (for example,
-`sbx-cs-<rand>`). When a sandboxed process sends a request to any of the
-configured hosts and the placeholder appears anywhere in the request, the
-proxy replaces it with the real value. The agent never sees the real secret.
+The built-in `github` service doesn't inject credentials into requests to
+`npm.pkg.github.com`. To install private npm packages from GitHub Packages,
+add a custom secret for that host.
 
-Prefer the [service-based flow](#stored-secrets) whenever it's an option —
-the kit handles the wiring; you only provide the value.
+On the host, authenticate the GitHub CLI with a token that can read the package.
+GitHub documents a personal access token (classic) with at least `read:packages`
+scope for this use. See
+[Authenticating to GitHub Packages](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#authenticating-to-github-packages).
+Then register the token source, replacing `my-sandbox` with your sandbox's name:
+
+```console
+$ sbx secret set-custom \
+    --sandbox my-sandbox \
+    --host npm.pkg.github.com \
+    --env NODE_AUTH_TOKEN \
+    --command 'gh auth token'
+```
+
+The command prints a generated placeholder. For an existing sandbox, set
+`NODE_AUTH_TOKEN` to that placeholder using `sbx run -e` for an agent session,
+or `/etc/sandbox-persistent.sh` for future sessions. See
+[Set environment variables](../usage.md#set-environment-variables).
+Use the placeholder, not the actual GitHub token.
+
+Inside the sandbox, add the following entries to your project's `.npmrc`,
+replacing `@my-org` with the package's scope. Keep `${NODE_AUTH_TOKEN}` literal
+so npm reads the environment variable:
+
+```ini
+@my-org:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
+```
+
+Install the package inside the sandbox:
+
+```console
+$ npm install @my-org/my-package
+```
+
+Replace `@my-org/my-package` with your package name. npm sends the placeholder
+to `npm.pkg.github.com`, and the proxy replaces it with the token retrieved by
+`gh auth token` on the host.
 
 ## Credential bindings