From b2095f2e9eeeeec25ba817dbe69e4a6c48238e94 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 27 Oct 2026 17:59:10 +0100 Subject: [PATCH] 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 --- content/manuals/ai/sandboxes/get-started.md | 38 +++++++------------ .../governance/access-controls/local.md | 31 +++++++-------- 2 files changed, 27 insertions(+), 42 deletions(-) diff --git a/content/manuals/ai/sandboxes/get-started.md b/content/manuals/ai/sandboxes/get-started.md index 28b6bfe6a9..b3fc1efbcb 100644 --- a/content/manuals/ai/sandboxes/get-started.md +++ b/content/manuals/ai/sandboxes/get-started.md @@ -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. diff --git a/content/manuals/ai/sandboxes/governance/access-controls/local.md b/content/manuals/ai/sandboxes/governance/access-controls/local.md index 68636519c6..e5d1f5e93e 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/local.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/local.md @@ -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