Skip to content

docs: explain IPv6 localhost resolution for published sandbox ports #25200

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

Merged
dvdksn merged 1 commit into from
May 29, 2026
+11 −3
Merged

docs: explain IPv6 localhost resolution for published sandbox ports #25200

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
14 changes: 11 additions & 3 deletions content/manuals/ai/sandboxes/usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -348,10 +348,18 @@ $ sbx ports my-sandbox --unpublish 8080:3000

A few things to keep in mind:

- **Services must bind to `0.0.0.0`** — a service listening on `127.0.0.1`
inside the sandbox won't be reachable through a published port. Most dev
- **Services must listen on all interfaces** — a service listening only on
Copy link
Copy Markdown

@docker-agent docker-agent May 28, 2026

Choose a reason for hiding this comment

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

[MEDIUM] Prohibited **Term** — Description list format in new bullets

Both new bullets use the **Bold term** — description pattern that the Docker style guide explicitly prohibits in lists (STYLE.md: "Avoid marketing-style list formatting — Don't use 'Term - Description' format, which reads like marketing copy"). The same rule also means bold should only appear on UI elements (buttons, menus, field labels), not on technical concept labels.

The existing bullets in this list already have this pattern, but this PR adds two more instances. Consider reformatting as plain descriptive bullets — for example:

- 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`. ...

Or use plain prose. Note: the pre-existing bullets (Not persistent, No create-time flag, Unpublish requires the host port) have the same formatting issue — it may be worth fixing those at the same time.

`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` when starting them.
`--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`
Expand Down