Skip to content

docs: update sandbox port publishing defaults #25949

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

Closed
dvdksn wants to merge 1 commit into from
+12 −12
Closed

docs: update sandbox port publishing defaults #25949

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
7 changes: 4 additions & 3 deletions content/manuals/ai/sandboxes/customize/kit-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -354,11 +354,12 @@ ports:
| Field | Description |
| ----------- | ------------------------------------------------------------------- |
| `container` | Container port, 1 to 65535. |
| `protocol` | `tcp` or `udp`. Empty means `tcp`. |
| `protocol` | `tcp` or `udp`. Omit for `tcp4`, which binds only IPv4. Set `tcp` to bind both address families. |
| `name` | Optional label surfaced by tools that list published port bindings. |

Host ports are allocated ephemerally on `127.0.0.1`. Users can pin host ports
with `sbx ports --publish <host>:<container>`.
Host ports are allocated ephemerally on the loopback addresses that match the
protocol. Users can pin host ports with
`sbx ports --publish <host>:<container>`.

## Environment

Expand Down
2 changes: 1 addition & 1 deletion content/manuals/ai/sandboxes/usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -321,7 +321,7 @@ them in detail.
```console
$ sbx ls
SANDBOX AGENT STATUS PORTS WORKSPACE
my-sandbox claude running 127.0.0.1:8080->3000/tcp /home/user/proj
my-sandbox claude running 127.0.0.1:8080->3000/tcp4 /home/user/proj
```

To stop forwarding a port:
Expand Down
15 changes: 7 additions & 8 deletions content/manuals/ai/sandboxes/workflows/development.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,8 @@ $ sbx run --publish 8080:3000 --name my-sandbox claude
```

For an existing sandbox, use [`sbx ports`](/reference/cli/sbx/ports/) to
forward traffic from your host.
forward traffic from your host. Publishing a port on a stopped local sandbox
starts the sandbox first.

The common case: an agent has started a dev server or API, and you want to open
it in your browser or run tests against it.
Expand All @@ -70,7 +71,7 @@ lists them in detail:
```console
$ sbx ls
SANDBOX AGENT STATUS PORTS WORKSPACE
my-sandbox claude running 127.0.0.1:8080->3000/tcp /home/user/proj
my-sandbox claude running 127.0.0.1:8080->3000/tcp4 /home/user/proj
```

To stop forwarding a port:
Expand All @@ -82,12 +83,10 @@ $ sbx ports my-sandbox --unpublish 8080:3000
For a service to be reachable, it must listen on all interfaces inside the
sandbox, not only `127.0.0.1`. Bind it to `0.0.0.0` for IPv4 or `[::]` for both
IPv4 and IPv6. Most dev servers need a flag like `--host 0.0.0.0` to do this.
On the host, `--publish` listens on both `127.0.0.1` and `::1`, so a client
resolving `localhost` might pick IPv6 and fail with "connection reset by peer"
if the sandboxed service only listens on IPv4, even when
`http://127.0.0.1:<port>/` works. To fix that, bind the service to `[::]`, or
pin the published port to one family with `--publish 8080:3000/tcp4` or
`/tcp6`.
When you omit the protocol, `--publish` uses `tcp4` and listens on
`127.0.0.1`. If you specify an IPv6 host IP, the omitted protocol uses `tcp6`
instead. Set the protocol to `tcp` to listen on both `127.0.0.1` and `::1`, or
use `tcp6` to listen only on IPv6.

Published ports survive restarts: `sbx` re-publishes them when the sandbox or
the daemon restarts. Explicit host ports are reused, while a port published with
Expand Down