Skip to content

docs: clarify Sandboxes first-run policy setup #26421

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
dvdksn wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: clarify Sandboxes first-run policy setup #26421

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 13 additions & 25 deletions content/manuals/ai/sandboxes/get-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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:

Expand All @@ -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.

Expand Down
31 changes: 14 additions & 17 deletions content/manuals/ai/sandboxes/governance/access-controls/local.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 "**"`. |
Expand Down Expand Up @@ -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
Expand Down
Loading