Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
17 changes: 14 additions & 3 deletions content/manuals/ai/sandboxes/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -447,15 +447,26 @@ If you know which ports you need, publish them when you create the sandbox:
$ sbx run --publish 8080:3000 --name my-sandbox claude
```

For an existing sandbox, use `sbx port publish` to
forward traffic from your host. Publishing a port on a stopped local sandbox
starts it first:
For an existing sandbox, keep the agent or `sbx exec` session running your
service open, then use `sbx port publish` from another terminal to forward
traffic from your host:

```console
$ sbx port publish my-sandbox 8080:3000
$ open http://localhost:8080
```

Publishing a port saves the mapping but doesn't keep the sandbox running.
If you publish on a stopped local sandbox, the command starts it and applies
the mapping. Unless the sandbox is detached or another session attaches, it
stops again shortly after the command exits.

Port mappings persist across stops and restarts. Forwarding stops while the
sandbox is stopped and resumes when it starts again, without publishing again.
Your server must also be running inside the sandbox. To keep a service
accessible after agent and exec sessions end,
[keep the sandbox running in the background](#keep-a-sandbox-running-in-the-background).

To let the OS pick a free host port instead of choosing one yourself, specify
only the sandbox port. Then use `sbx port ls` to check which host port was
assigned:
Expand Down
3 changes: 3 additions & 0 deletions content/manuals/ai/sandboxes/workflows/development.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,9 @@ For an existing sandbox, use `sbx port publish` to
forward traffic from your host. Publishing a port on a stopped local sandbox
starts it first.

Unless the sandbox is detached or another session keeps it running, it stops
shortly after the command exits. See [port publishing and sandbox lifecycle](../usage.md#publish-ports).

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 Down