Merge pull request #26112 from dvdksn/codex/sandboxes-docs-clarifications

docs: clarify Sandboxes networking, certificates, and updates

content/manuals/ai/sandboxes/customize/templates.md

@@ -174,9 +174,22 @@ use `shell` (which drops you into a Bash shell with no agent).
 
 ### Template caching
 
-Template images are cached locally. The first use pulls from the registry;
-subsequent sandboxes reuse the cache. Cached images persist across sandbox
-creation and deletion, and are cleared when you run `sbx reset`.
+When creating a sandbox, `sbx` checks the registry for the template image by
+default and downloads missing or updated layers. If the pull fails and the
+image is cached locally, it can use the cached image. Cached images persist
+across sandbox creation and deletion, and are cleared when you run `sbx reset`.
+
+### Updating agents
+
+Agent templates include an agent version, which can differ from the agent's
+latest release. Updating the `sbx` CLI or pulling an updated template doesn't
+update agents inside existing sandboxes.
+
+To update an installed agent, run its documented update command inside the
+sandbox, either from a sandbox shell or with `sbx exec`. Restart the agent
+session to use the updated version. The update persists across sandbox stops
+and starts, but is deleted when you remove the sandbox. To reuse the updated
+agent in other sandboxes, [save a template](#saving-a-sandbox-as-a-template).
 
 ## Saving a sandbox as a template
 

content/manuals/ai/sandboxes/governance/access-controls/local.md

@@ -59,7 +59,25 @@ Initialize the global network policy for your sandboxes:
 | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Open        | All outbound traffic is allowed. Equivalent to adding a wildcard allow rule with `sbx policy allow network "**"`.                                 |
 | Balanced    | Default deny, with a baseline allowlist covering AI provider APIs, package managers, code hosts, container registries, and common cloud services. |
-| Locked Down | All outbound traffic is blocked, including model provider APIs (for example, `api.anthropic.com`). You must explicitly allow everything you need. |
+| Locked Down | No baseline allow rules. Destinations need an allow rule from you or a kit. |
+
+Presets initialize the global policy. Built-in agent kits and other kits can
+add per-sandbox allow rules, including under **Locked Down** (`deny-all`). The
+preset isn't an explicit deny rule that overrides those allowances. To inspect
+the rules a kit adds to a sandbox, run:
+
+```console
+$ sbx policy ls my-sandbox --source kit --type network --wide
+```
+
+To block a destination allowed by a kit, add an explicit deny rule:
+
+```console
+$ sbx policy deny network --sandbox my-sandbox openrouter.ai
+```
+
+Deny rules take precedence over allow rules. See
+[Policy precedence](../concepts.md#precedence).
 
 The **Balanced** preset's baseline allowlist is a good starting point for most
 workflows. Run `sbx policy ls` to see exactly which rules it includes. As of

content/manuals/ai/sandboxes/troubleshooting.md

@@ -250,6 +250,43 @@ the egress path in the **PROXY** column:
   internal CA applies. The only difference between them is whether the client
   knows it's talking to a proxy.
 
+### Certificate errors during Docker builds
+
+Containers started by the sandbox's Docker Engine have their own trust stores.
+They don't inherit the sandbox's installed certificates. If an HTTPS download
+in a Dockerfile fails with `self signed certificate in certificate chain`,
+install the proxy CA in the build image before the download.
+
+From a shell inside the sandbox, write its proxy CA into your build context:
+
+```console
+$ printf '%s' "$PROXY_CA_CERT_B64" | base64 -d > sbx-proxy-ca.crt
+```
+
+For a Debian-based image with `ca-certificates` installed, copy the certificate
+and update the trust store before commands that make HTTPS requests:
+
+```dockerfile
+FROM python:3.13-slim
+COPY sbx-proxy-ca.crt /usr/local/share/ca-certificates/sbx-proxy-ca.crt
+RUN update-ca-certificates
+```
+
+Build inside the sandbox, passing its proxy settings to the build:
+
+```console
+$ docker build --build-arg HTTP_PROXY --build-arg HTTPS_PROXY --build-arg NO_PROXY -t my-app .
+```
+
+If your organization also inspects TLS, install its root CA in the build image
+as a separate `.crt` file before `update-ca-certificates`. Keep the system CA
+bundle intact so the image trusts both proxies and public certificate
+authorities. The earlier [certificate troubleshooting](#api-calls-fail-with-a-certificate-error)
+explains which proxy paths need each CA.
+
+Keep the generated proxy certificate out of version control. Regenerate it and
+rebuild the image if the sandbox proxy CA changes.
+
 ## Sandbox runs out of disk space
 
 The sandbox root (`/`) filesystem defaults to 20 GB. To increase it, set
@@ -324,6 +361,20 @@ the command again:
 ✓ Git repository detected: \\wsl.localhost\Ubuntu\home\you\repo
 ```
 
+## SSH agent socket is missing
+
+If `SSH_AUTH_SOCK` is set inside a sandbox but `ssh-add -L` reports
+`No such file or directory`, check whether your custom template includes
+`socat`. Docker Sandboxes uses it to create the socket that forwards requests
+to your host SSH agent. Installing OpenSSH client tools alone isn't enough.
+
+For an Ubuntu-based custom template, add `socat` to the packages installed as
+root in your Dockerfile, then rebuild the template and create a sandbox from
+it. Docker-provided sandbox templates already include `socat`.
+
+If the socket exists but forwarding still fails, check the
+[SSH agent settings](configuration/credentials.md#ssh-agent).
+
 ## Sandbox commits aren't signed
 
 Docker Sandboxes can sign Git commits with SSH keys from your host agent.