From 269a025560b15f4cf04a2f5b4fc090c13696e0cc Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 16 Sep 2026 12:55:07 +0000 Subject: [PATCH 1/4] docs: clarify sandbox network presets and kit rules The Locked Down description implied that only user-added rules could grant access, overlooking built-in agent kit allowances. Explain preset initialization, show kit-rule inspection, and demonstrate an explicit deny. --- .../governance/access-controls/local.md | 20 ++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/content/manuals/ai/sandboxes/governance/access-controls/local.md b/content/manuals/ai/sandboxes/governance/access-controls/local.md index 566138f474..4320f743ef 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/local.md +++ b/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 From 448092b2e1b705b6d4f98235465271d190b88b3e Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 16 Sep 2026 12:56:01 +0000 Subject: [PATCH 2/4] docs: explain proxy CA trust for builds inside sandboxes Nested build containers do not inherit the sandbox certificate store. Add a Dockerfile example that installs the proxy CA, passes build proxy settings, and accounts for an additional organization CA. --- .../manuals/ai/sandboxes/troubleshooting.md | 37 +++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index 0ecaa572e6..378edd3a62 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -234,6 +234,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 From 0e2fd033793e9cd3bf936ab7deeb5b93715fa288 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 16 Sep 2026 12:56:35 +0000 Subject: [PATCH 3/4] docs: explain missing SSH agent sockets in custom sandboxes Custom images without socat cannot create the forwarded SSH agent socket even when SSH_AUTH_SOCK is set. Document the dependency and link to forwarding settings for other failures. --- content/manuals/ai/sandboxes/troubleshooting.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index 378edd3a62..dce71c474d 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -345,6 +345,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. From 75d1ee312280c2028be294e043edeaf35f2fe1bb Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 16 Sep 2026 12:56:35 +0000 Subject: [PATCH 4/4] docs: distinguish sandbox template and agent updates The template cache description omitted the default registry refresh, and users had no guidance for updating installed agents. Correct the cache behavior and explain generic agent updates and their persistence boundary. --- .../ai/sandboxes/customize/templates.md | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/content/manuals/ai/sandboxes/customize/templates.md b/content/manuals/ai/sandboxes/customize/templates.md index 48ac92cdd5..87ae9b01a2 100644 --- a/content/manuals/ai/sandboxes/customize/templates.md +++ b/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