docs: clarify Sandboxes first-run policy setup (#26421)

## Summary

The getting-started walkthrough promised a network preset prompt on the
first sandbox run, even when policy was already configured. Explain when
the CLI prompts, document `sbx policy init balanced` for manual
initialization, and remove outdated prompt transcripts from the
walkthrough and local-policy page. Also clarify that agent kits can add
model-provider allowances under Locked Down.

@netlify /ai/sandboxes/get-started/

Generated by Codex
This commit is contained in:
David Karlsson authored and GitHub committed 2026-10-27 17:59:10 +01:00
1 parent f55dc7b65b
commit b2095f2e9e
2 files changed
+27 -42

No files matched your search

+13 -25
View File
@@ -53,27 +53,15 @@ $ cd ~/my-project
$ sbx run --name my-sandbox claude
```
The first time you run a sandbox, the CLI prompts you to choose a default
network preset:
In an interactive terminal, the CLI prompts you to choose a preset if the
global network policy hasn't been initialized. Select **Balanced** to permit traffic to common development
services while blocking other destinations unless you approve them. If a policy
is already configured, the CLI uses it without prompting.
```plaintext
Initialize the global network policy for your sandboxes:
Applies to all sandboxes, current and future — change it later with
"sbx policy allow/deny/rm". Kits, including built-in agent kits, may
also add per-sandbox rules.
1. Open — All network traffic allowed, no restrictions.
❯ 2. Balanced — Default deny, with common dev sites allowed.
3. Locked Down — All network traffic blocked unless you allow it.
Use ↑/↓ or 1–3 to navigate, Enter to confirm, Esc to cancel.
```
**Balanced** is a good starting point — it permits traffic to common
development services while blocking everything else. You can adjust individual
rules later. See [Local policy](governance/access-controls/local.md) for a full
description of each option.
To initialize the policy without an interactive prompt, run
`sbx policy init balanced` before `sbx run`. See
[Local policy](governance/access-controls/local.md) for the available presets
and how to change an existing policy.
Replace `claude` with the agent you want to use — see [Agents](agents/) for the
full list.
@@ -122,8 +110,8 @@ when running several agents on one repository — use
## Control what the agent can reach
Isolation isn't only about the filesystem. You also control what the sandbox
can reach on the network. You chose a default policy before the sandbox
started, and you can inspect or adjust it at any time.
can reach on the network. You can inspect or adjust the active policy at any
time.
Check which rules are in effect:
@@ -137,9 +125,9 @@ To allow a specific host:
$ sbx policy allow network registry.npmjs.org
```
With **Locked Down**, even your model provider API is blocked unless you
explicitly allow it. With **Balanced**, common development services are
permitted by default. See
With Balanced, common development services are permitted by default. With
Locked Down, destinations need an allow rule from you or a kit. Built-in agent
kits can add rules for their model providers. See
[local policy](governance/access-controls/local.md) for the full rule set
and how to customize it.
@@ -37,24 +37,21 @@ with a hostname rule (for example, `sbx policy allow network "myhost:22"`) or an
address-based rule. UDP requires the experimental feature and policy rules
described in [Allow outbound UDP](#allow-outbound-udp). ICMP is blocked.
If you haven't chosen a default preset, the CLI prompts you before it runs a
sandbox. Running `sbx policy reset` clears the preset and prompts you to choose
again:
If the global network policy hasn't been initialized, the CLI prompts you to
choose a preset when you run a sandbox in an interactive terminal. If a policy
is already configured, including one carried over from an earlier installation,
the CLI uses it without prompting.
```plaintext
Initialize the global network policy for your sandboxes:
To initialize the policy without an interactive prompt, run:
Applies to all sandboxes, current and future — change it later with
"sbx policy allow/deny/rm". Kits, including built-in agent kits, may
also add per-sandbox rules.
1. Open — All network traffic allowed, no restrictions.
❯ 2. Balanced — Default deny, with common dev sites allowed.
3. Locked Down — All network traffic blocked unless you allow it.
Use ↑/↓ or 1–3 to navigate, Enter to confirm, Esc to cancel.
```console
$ sbx policy init balanced
```
Available values are `allow-all`, `balanced`, and `deny-all`. Initialization is
a one-time setup. To change an existing preset, use
[`sbx policy reset`](#resetting).
| Preset | Description |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Open | All outbound TCP traffic is allowed. Equivalent to adding a wildcard allow rule with `sbx policy allow network "**"`. |
@@ -95,9 +92,9 @@ workflows. Run `sbx policy ls` to see exactly which rules it includes.
### Non-interactive environments
In non-interactive environments such as CI pipelines or headless servers, the
interactive prompt can't be displayed. Use `sbx policy init` to set the
preset before running any other `sbx` commands:
In non-interactive environments such as CI pipelines or headless servers, an
uninitialized policy causes `sbx run` to return an error. Use `sbx policy init`
to set the preset before running a sandbox:
```console
$ sbx policy init balanced