From 8d8f3bd5cb90bf7a2b592940615d993917231f88 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 20 Nov 2026 09:26:43 +0000 Subject: [PATCH 1/4] docs: clarify inactive sandbox port mappings Port listings include mappings retained by stopped sandboxes, which can lack an assigned host port. Explain inactive status and when to list ports to find the assigned host port. --- content/manuals/ai/sandboxes/usage.md | 15 ++++++++++----- .../manuals/ai/sandboxes/workflows/development.md | 14 ++++++++++---- 2 files changed, 20 insertions(+), 9 deletions(-) diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md index 94b0f948406..7fee9f82d02 100644 --- a/content/manuals/ai/sandboxes/usage.md +++ b/content/manuals/ai/sandboxes/usage.md @@ -457,17 +457,22 @@ $ open http://localhost:8080 ``` 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: +only the sandbox port. While the sandbox is running, use `sbx port ls` to +check which host port was assigned: ```console $ sbx port publish my-sandbox 3000 $ sbx port ls my-sandbox ``` -`sbx ls` shows active port mappings alongside each sandbox. `sbx port ls` lists -them in detail. The `CREATED` column shows the sandbox age, and the `STATUS` -column identifies sandboxes kept running in detached mode with `(detached)`. +`sbx port ls` includes mappings kept by stopped sandboxes, marked `inactive`. +An OS-assigned host port appears as a placeholder until the sandbox starts and +binds the port. See [Local services](workflows/development.md#accessing-services-in-the-sandbox) +for details. + +`sbx ls` shows active port mappings alongside each sandbox. Its `CREATED` +column shows the sandbox age, and its `STATUS` column identifies sandboxes +kept running in detached mode with `(detached)`. ```console $ sbx ls diff --git a/content/manuals/ai/sandboxes/workflows/development.md b/content/manuals/ai/sandboxes/workflows/development.md index 3b50da9c005..334688846a8 100644 --- a/content/manuals/ai/sandboxes/workflows/development.md +++ b/content/manuals/ai/sandboxes/workflows/development.md @@ -60,16 +60,22 @@ $ open http://localhost:8080 ``` 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: +only the sandbox port. While the sandbox is running, use `sbx port ls` to +check which host port was assigned: ```console $ sbx port publish my-sandbox 3000 $ sbx port ls my-sandbox ``` -`sbx ls` shows active port mappings alongside each sandbox, and `sbx port ls` -lists them in detail: +`sbx port ls` also lists the port mappings a stopped sandbox keeps. When any +mapping is inactive, the output includes a `STATUS` column. An `inactive` +mapping forwards no traffic until the sandbox starts and binds the port again. +For an inactive mapping with an OS-assigned host port, the host port appears as +a placeholder until the port is bound. Start the sandbox, then list its ports +again to find the assigned host port. + +`sbx ls` shows active port mappings alongside each sandbox: ```console $ sbx ls From a4d6f11b416bf62b88a6c7083141d030645312e2 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 20 Nov 2026 12:44:53 +0000 Subject: [PATCH 2/4] docs: Simplify sandbox port lifecycle guidance Port guidance repeated the same explanation and described output details that obscured what users need to know. Keep the inactive mapping behavior with restart guidance and link there from the basic usage page. --- content/manuals/ai/sandboxes/usage.md | 19 +++---------------- .../ai/sandboxes/workflows/development.md | 14 ++++---------- 2 files changed, 7 insertions(+), 26 deletions(-) diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md index 7fee9f82d02..bf3b902655f 100644 --- a/content/manuals/ai/sandboxes/usage.md +++ b/content/manuals/ai/sandboxes/usage.md @@ -456,19 +456,8 @@ $ sbx port publish my-sandbox 8080:3000 $ open http://localhost:8080 ``` -To let the OS pick a free host port instead of choosing one yourself, specify -only the sandbox port. While the sandbox is running, use `sbx port ls` to -check which host port was assigned: - -```console -$ sbx port publish my-sandbox 3000 -$ sbx port ls my-sandbox -``` - -`sbx port ls` includes mappings kept by stopped sandboxes, marked `inactive`. -An OS-assigned host port appears as a placeholder until the sandbox starts and -binds the port. See [Local services](workflows/development.md#accessing-services-in-the-sandbox) -for details. +For OS-assigned host ports and port mappings across restarts, see +[Local services](workflows/development.md#accessing-services-in-the-sandbox). `sbx ls` shows active port mappings alongside each sandbox. Its `CREATED` column shows the sandbox age, and its `STATUS` column identifies sandboxes @@ -487,9 +476,7 @@ $ sbx port unpublish my-sandbox 8080:3000 ``` When `sbx run` re-attaches to an existing sandbox, it ignores `--publish`. Use -`sbx port publish` to publish ports on that sandbox. For dev server and host-service -recipes, see -[Local services](workflows/development.md#local-services). +`sbx port publish` to publish ports on that sandbox. ## What persists diff --git a/content/manuals/ai/sandboxes/workflows/development.md b/content/manuals/ai/sandboxes/workflows/development.md index 334688846a8..dcb3529f210 100644 --- a/content/manuals/ai/sandboxes/workflows/development.md +++ b/content/manuals/ai/sandboxes/workflows/development.md @@ -68,13 +68,6 @@ $ sbx port publish my-sandbox 3000 $ sbx port ls my-sandbox ``` -`sbx port ls` also lists the port mappings a stopped sandbox keeps. When any -mapping is inactive, the output includes a `STATUS` column. An `inactive` -mapping forwards no traffic until the sandbox starts and binds the port again. -For an inactive mapping with an OS-assigned host port, the host port appears as -a placeholder until the port is bound. Start the sandbox, then list its ports -again to find the assigned host port. - `sbx ls` shows active port mappings alongside each sandbox: ```console @@ -103,9 +96,10 @@ those require the sandboxed service to listen on IPv6 as well — bind it to `[::]` — or a client arriving over `::1` has its connection accepted and then reset. -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 different host port +Stopped sandboxes keep their port mappings, listed as `inactive` by +`sbx port ls`, but forward no traffic. `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 different host port on each start. Check `sbx port ls 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. From 134c1b3b77042dba5267aa7ca633e2d1fbd36270 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 20 Nov 2026 12:56:51 +0000 Subject: [PATCH 3/4] docs: Clarify when stopped sandbox ports are published again The restart wording could imply that restarting the daemon publishes ports for a stopped sandbox. Tie port restoration to starting the sandbox again. --- content/manuals/ai/sandboxes/workflows/development.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/manuals/ai/sandboxes/workflows/development.md b/content/manuals/ai/sandboxes/workflows/development.md index dcb3529f210..80ca3315e7c 100644 --- a/content/manuals/ai/sandboxes/workflows/development.md +++ b/content/manuals/ai/sandboxes/workflows/development.md @@ -97,8 +97,8 @@ those require the sandboxed service to listen on IPv6 as well — bind it to reset. Stopped sandboxes keep their port mappings, listed as `inactive` by -`sbx port ls`, but forward no traffic. `sbx` re-publishes them when the sandbox -or the daemon restarts. Explicit host ports are reused, while a port published +`sbx port ls`, but forward no traffic. `sbx` re-publishes them when you start +the sandbox again. Explicit host ports are reused, while a port published with an OS-assigned host port, such as `--publish 3000`, gets a different host port on each start. Check `sbx port ls 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 From f87dca32eb6b719c43189ab434071173a7cef4d2 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 20 Nov 2026 13:04:22 +0000 Subject: [PATCH 4/4] docs: trim sandbox list output explanation The port-publishing section explains unrelated sandbox list columns. Remove that detail and keep the active port mapping example. --- content/manuals/ai/sandboxes/usage.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md index bf3b902655f..747097a3c71 100644 --- a/content/manuals/ai/sandboxes/usage.md +++ b/content/manuals/ai/sandboxes/usage.md @@ -459,9 +459,7 @@ $ open http://localhost:8080 For OS-assigned host ports and port mappings across restarts, see [Local services](workflows/development.md#accessing-services-in-the-sandbox). -`sbx ls` shows active port mappings alongside each sandbox. Its `CREATED` -column shows the sandbox age, and its `STATUS` column identifies sandboxes -kept running in detached mode with `(detached)`. +`sbx ls` shows active port mappings alongside each sandbox: ```console $ sbx ls