From 33285650d974443e89b12d868b4e577165144cec Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Wed, 5 Aug 2026 09:02:05 +0000
Subject: [PATCH] docs: document create-time port publishing

The usage and workflow guides incorrectly said ports could only be published after sandbox creation. Document the create-time flags and retain sbx ports for existing sandboxes.
---
 content/manuals/ai/sandboxes/usage.md     | 30 ++++++++++++-------
 content/manuals/ai/sandboxes/workflows.md | 35 +++++++++++++++--------
 2 files changed, 43 insertions(+), 22 deletions(-)

diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md
index 793dd703fe5..ef4286e39b6 100644
--- a/content/manuals/ai/sandboxes/usage.md
+++ b/content/manuals/ai/sandboxes/usage.md
@@ -216,20 +216,30 @@ sandboxes isn't supported.
 ## Publish ports
 
 Sandboxes are [network-isolated](security/isolation.md) — your browser or local
-tools can't reach a server running inside one by default. Use
-[`sbx ports`](/reference/cli/sbx/ports/) to forward traffic from your host into
-a running sandbox.
+tools can't reach a server running inside one by default. A port mapping of
+`8080:3000` publishes sandbox port 3000 on host port 8080.
+
+If you know which ports you need, publish them when you create the sandbox:
+
+```console
+$ 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:
 
 ```console
-$ sbx ports my-sandbox --publish 8080:3000   # host 8080 → sandbox port 3000
+$ sbx ports my-sandbox --publish 8080:3000
 $ open http://localhost:8080
 ```
 
-To let the OS pick a free host port instead of choosing one yourself:
+To let the OS pick a free host port instead of choosing one yourself, specify
+only the sandbox port. Then use `sbx ports` to check which host port was
+assigned:
 
 ```console
-$ sbx ports my-sandbox --publish 3000        # ephemeral host port
-$ sbx ports my-sandbox                       # check which port was assigned
+$ sbx ports my-sandbox --publish 3000
+$ sbx ports my-sandbox
 ```
 
 `sbx ls` shows active port mappings alongside each sandbox. `sbx ports` lists
@@ -247,9 +257,9 @@ To stop forwarding a port:
 $ sbx ports my-sandbox --unpublish 8080:3000
 ```
 
-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. For
-dev server and host-service recipes, see
+When `sbx run` re-attaches to an existing sandbox, it ignores `--publish`. Use
+`sbx ports` to publish ports on that sandbox. For dev server and host-service
+recipes, see
 [Local services](workflows.md#local-services).
 
 ## What persists
diff --git a/content/manuals/ai/sandboxes/workflows.md b/content/manuals/ai/sandboxes/workflows.md
index d740050ba88..fe1533fc1c3 100644
--- a/content/manuals/ai/sandboxes/workflows.md
+++ b/content/manuals/ai/sandboxes/workflows.md
@@ -284,7 +284,8 @@ volumes inside it are deleted with it.
 
 This pattern works well for tasks where the agent needs to run the project's
 test suite or inspect a service it started. If you need to reach that service
-from your host, publish a port after the sandbox is running.
+from your host, publish the port when you create the sandbox, or publish it
+later with `sbx ports`.
 
 ## Local services
 
@@ -294,23 +295,33 @@ needs to call a service running on your host.
 ### Accessing services in the sandbox
 
 Sandboxes are [network-isolated](security/isolation.md) — your browser or local
-tools can't reach a server running inside one by default. Use
-[`sbx ports`](/reference/cli/sbx/ports/) to forward traffic from your host into
-a running sandbox.
+tools can't reach a server running inside one by default. A port mapping of
+`8080:3000` publishes sandbox port 3000 on host port 8080.
+
+If you know which ports you need, publish them when you create the sandbox:
+
+```console
+$ 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.
 
 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.
 
 ```console
-$ sbx ports my-sandbox --publish 8080:3000   # host 8080 → sandbox port 3000
+$ sbx ports my-sandbox --publish 8080:3000
 $ open http://localhost:8080
 ```
 
-To let the OS pick a free host port instead of choosing one yourself:
+To let the OS pick a free host port instead of choosing one yourself, specify
+only the sandbox port. Then use `sbx ports` to check which host port was
+assigned:
 
 ```console
-$ sbx ports my-sandbox --publish 3000        # ephemeral host port
-$ sbx ports my-sandbox                       # check which port was assigned
+$ sbx ports my-sandbox --publish 3000
+$ sbx ports my-sandbox
 ```
 
 `sbx ls` shows active port mappings alongside each sandbox, and `sbx ports`
@@ -345,10 +356,10 @@ on each start. 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
 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.
+When `sbx run` re-attaches to an existing sandbox, it ignores `--publish`. Use
+`sbx ports` to publish ports on that sandbox. 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