Skip to content

docs: sandbox published ports survive restarts #25386

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

Open
dvdksn wants to merge 2 commits into
base: main
Choose a base branch
from
+20 −22
Open

docs: sandbox published ports survive restarts #25386

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
40b8d95
docs: sandbox published ports survive restarts
dvdksn Jun 18, 2026
1e66664
docs: tighten port publishing notes into prose
dvdksn Jun 18, 2026
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
42 changes: 20 additions & 22 deletions content/manuals/ai/sandboxes/usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -288,28 +288,26 @@ To stop forwarding a port:
$ sbx ports my-sandbox --unpublish 8080:3000
```

A few things to keep in mind:

- **Services must listen on all interfaces** — a service listening only on
`127.0.0.1` inside the sandbox won't be reachable through a published port.
Bind to `0.0.0.0` for IPv4, or `[::]` to accept both IPv4 and IPv6. Most dev
servers default to `127.0.0.1`, so you'll usually need to pass a flag like
`--host 0.0.0.0` or `--host '[::]'` when starting them.
- **`localhost` on the host can resolve to IPv6** — by default, `--publish`
listens on both `127.0.0.1` and `::1`. Your browser or client may pick IPv6
when resolving `localhost`. If the sandboxed service only listens on IPv4,
the IPv6 connection fails with "connection reset by peer" — even though
`http://127.0.0.1:<port>/` works. To fix it, bind the sandboxed service to
`[::]` so it accepts both families, or restrict the published port to one
family with `--publish 8080:3000/tcp4` (IPv4) or `/tcp6` (IPv6).
- **Not persistent** — published ports are lost when the sandbox stops or the
daemon restarts. Re-publish after restarting.
- **No create-time flag** — unlike `docker run -p`, there's no `--publish`
option on `sbx run` or `sbx create`. Ports can only be published after the
sandbox is running.
- **Unpublish requires the host port** — `--unpublish 3000` is rejected; you
must use `--unpublish 8080:3000`. Run `sbx ports my-sandbox` first if you
used an ephemeral port and need to find the assigned host port.
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`.

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
an OS-assigned host port (such as `--publish 3000`) gets a new host port on each

@docker-agent docker-agent Jun 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MEDIUM] --publish 3000 example may confuse Docker users about OS-assigned vs. explicit host ports

The new text uses --publish 3000 as an example of a port published with an OS-assigned host port. However, Docker users familiar with docker run -p may interpret --publish 3000 as an explicit mapping (sandbox port 3000 to host port 3000), not as a request for an ephemeral host port. In Docker's standard CLI, an OS-assigned host port is typically expressed as -p :3000 or -p 0:3000 (with a colon).

If sbx publish's bare-port syntax genuinely differs from docker run -p, a brief clarification here would prevent confusion — for example, noting that --publish 3000 means "sandbox port 3000 on an ephemeral host port" or using --publish :3000 if that syntax is also supported.

start, so check `sbx ports my-sandbox` to find it. If an explicit host port is
already in use at restart, the CLI or the dashboard prompts you to choose

@docker-agent docker-agent Jun 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MEDIUM] Specific interactive behavior claim — "prompts you to choose another" — may need verification

The sentence claims that when an explicit host port is already in use at restart, "the CLI or the dashboard prompts you to choose another." This is a specific UX assertion: an interactive prompt appears. If the actual behavior is a non-interactive error exit, a warning with automatic fallback, or something else, users will be misled about how to handle the conflict.

Worth double-checking that the CLI/dashboard UX matches this description before merging, especially since the precise interaction mode (prompt vs. error) affects how users should respond.

another. Removing the sandbox releases its ports.

You can't publish ports at create time — there's no `--publish` flag on
`sbx run` or `sbx create`, so publish them once the sandbox is running. To stop
forwarding, `--unpublish 8080:3000` removes a single mapping, and
`--unpublish 3000` removes every host port mapped to sandbox port 3000.

## Accessing host services from a sandbox

Expand Down