docker · Pradumnasaraf · May 16, 2026
@@ -337,7 +337,7 @@ While iterating on a kit, apply changes to a running sandbox with
 `sbx kit add` instead of recreating it:
 
 ```console
-$ sbx kit add my-sandbox ./my-kit/
+$ sbx kit add claude-my-project ./my-kit/
 ```
 
 `kit add` re-runs install commands and re-copies files. Kits can't be

@@ -179,7 +179,7 @@ Stop the sandbox (or let the CLI prompt you), then save it with a name and
 tag:
 
 ```console
-$ sbx template save my-sandbox my-template:v1
+$ sbx template save claude-my-project my-template:v1
 ```
 
 The image is stored in the sandbox runtime's local image store. Create a
@@ -209,7 +209,7 @@ To share a saved template or move it to another machine, export it as a
 tar file:
 
 ```console
-$ sbx template save my-sandbox my-template:v1 --output my-template.tar
+$ sbx template save claude-my-project my-template:v1 --output my-template.tar
 ```
 
 On the other machine, load the tar file and use it:

@@ -143,15 +143,15 @@ traffic is allowed except private networks and localhost.
 Allow mode (block specific destinations):
 
 ```console
-$ docker sandbox network proxy my-sandbox \
+$ docker sandbox network proxy claude-my-project \
   --policy allow \
   --block-cidr 10.0.0.0/8
 ```
 
 Deny mode (allow specific destinations):
 
 ```console
-$ docker sandbox network proxy my-sandbox \
+$ docker sandbox network proxy claude-my-project \
   --policy deny \
   --allow-host api.anthropic.com \
   --allow-host "*.npmjs.org"

@@ -199,7 +199,7 @@ directory without touching your main working tree.
 When the session ends, review what the agent did from the worktree:
 
 ```console
-$ cd .sbx/<sandbox-name>-worktrees/my-feature
+$ cd .sbx/claude-my-project-worktrees/my-feature
 $ git log
 $ git diff main
 ```
@@ -243,15 +243,19 @@ set and how to customize it.
 Sandboxes persist after the agent exits. To stop a sandbox without deleting it:
 
 ```console
-$ sbx stop my-sandbox
+$ sbx stop claude-my-project
 ```
 
+The sandbox name comes from the agent and workspace directory — see
+[Reconnecting and naming](usage.md#reconnecting-and-naming) for details, or run
+`sbx ls` to see the names of your existing sandboxes.
+
 Installed packages, Docker images, and configuration changes are preserved
 across restarts. When you're done with a sandbox, remove it to reclaim disk
 space:
 
 ```console
-$ sbx rm my-sandbox
+$ sbx rm claude-my-project
 ```
 
 Removing a sandbox deletes everything inside it — installed packages, Docker

@@ -69,7 +69,7 @@ secret globally so it's available to all sandboxes. To scope a secret to a
 specific sandbox instead:
 
 ```console
-$ sbx secret set my-sandbox openai
+$ sbx secret set openai-my-project openai
 ```
 
 > [!NOTE]

@@ -93,8 +93,8 @@ $ sbx policy deny network -g ads.example.com
 Pass a sandbox name to scope a rule to one sandbox:
 
 ```console
-$ sbx policy allow network my-sandbox api.example.com
-$ sbx policy deny network my-sandbox ads.example.com
+$ sbx policy allow network claude-my-project api.example.com
+$ sbx policy deny network claude-my-project ads.example.com
 ```
 
 Specify multiple hosts in one command with a comma-separated list:
@@ -107,11 +107,11 @@ List all active policy rules with `sbx policy ls`:
 
 ```console
 $ sbx policy ls
-NAME                  TYPE      ORIGIN               DECISION   STATUS   RESOURCES
-balanced-dev          network   local                allow      active   api.anthropic.com
-ads-block             network   local                deny       active   ads.example.com
-kit:my-sandbox        network   sandbox:my-sandbox   allow      active   api.example.com
-kit:my-sandbox:deny   network   sandbox:my-sandbox   deny       active   telemetry.example.com
+NAME                         TYPE      ORIGIN                      DECISION   STATUS   RESOURCES
+balanced-dev                 network   local                       allow      active   api.anthropic.com
+ads-block                    network   local                       deny       active   ads.example.com
+kit:claude-my-project        network   sandbox:claude-my-project   allow      active   api.example.com
+kit:claude-my-project:deny   network   sandbox:claude-my-project   deny       active   telemetry.example.com
 ```
 
 The columns are:
@@ -131,7 +131,7 @@ Use `--type network` to show only network policies. Without a sandbox argument,
 filter the list to global rules and rules scoped to that sandbox only:
 
 ```console
-$ sbx policy ls my-sandbox
+$ sbx policy ls claude-my-project
 ```
 
 Remove a policy by resource or by rule ID:
@@ -144,7 +144,7 @@ $ sbx policy rm network -g --id 2d3c1f0e-4a73-4e05-bc9d-f2f9a4b50d67
 To remove a sandbox-scoped policy, include the sandbox name:
 
 ```console
-$ sbx policy rm network my-sandbox --resource api.example.com
+$ sbx policy rm network claude-my-project --resource api.example.com
 ```
 
 ### Resetting to defaults
@@ -210,14 +210,14 @@ Use `sbx policy log` to see which hosts your sandboxes have contacted:
 ```console
 $ sbx policy log
 Blocked requests:
-SANDBOX      TYPE     HOST                   PROXY        RULE            REASON         LAST SEEN        COUNT
-my-sandbox   network  blocked.example.com    transparent  domain-blocked  default-deny   10:15:25 29-Jan  1
+SANDBOX             TYPE     HOST                   PROXY        RULE            REASON         LAST SEEN        COUNT
+claude-my-project   network  blocked.example.com    transparent  domain-blocked  default-deny   10:15:25 29-Jan  1
 
 Allowed requests:
-SANDBOX      TYPE     HOST                   PROXY          RULE             REASON   LAST SEEN        COUNT
-my-sandbox   network  api.anthropic.com      forward        domain-allowed            10:15:23 29-Jan  42
-my-sandbox   network  registry.npmjs.org     forward-bypass domain-allowed            10:15:20 29-Jan  18
-my-sandbox   network  app.example.com        browser-open                             10:15:10 29-Jan  1
+SANDBOX             TYPE     HOST                   PROXY          RULE             REASON   LAST SEEN        COUNT
+claude-my-project   network  api.anthropic.com      forward        domain-allowed            10:15:23 29-Jan  42
+claude-my-project   network  registry.npmjs.org     forward-bypass domain-allowed            10:15:20 29-Jan  18
+claude-my-project   network  app.example.com        browser-open                             10:15:10 29-Jan  1
 ```
 
 The **PROXY** column shows how the request left the sandbox:
@@ -236,7 +236,7 @@ The **RULE** column identifies the policy rule that matched the request. The
 Filter by sandbox name by passing it as an argument:
 
 ```console
-$ sbx policy log my-sandbox
+$ sbx policy log claude-my-project
 ```
 
 Use `--limit N` to show only the last `N` entries, `--json` for

@@ -17,21 +17,26 @@ The basic workflow is [`run`](/reference/cli/sbx/run/) to start,
 ```console
 $ sbx run claude                    # start an agent
 $ sbx ls                            # see what's running
-$ sbx stop my-sandbox               # pause it
-$ sbx rm my-sandbox                 # delete it entirely
+$ sbx stop claude-my-project        # pause it
+$ sbx rm claude-my-project          # delete it entirely
 ```
 
+Sandboxes are auto-named `<agent>-<directory>` when you don't pass `--name` —
+running `sbx run claude` from `~/my-project` creates a sandbox named
+`claude-my-project`. Run `sbx ls` to see the names of your existing sandboxes,
+or see [Reconnecting and naming](#reconnecting-and-naming) for more.
+
 To get a shell inside a running sandbox — useful for inspecting the environment,
 checking Docker containers, or manually installing something:
 
 ```console
-$ sbx exec -it <sandbox-name> bash
+$ sbx exec -it claude-my-project bash
 ```
 
 If you need a clean slate, remove the sandbox and re-run:
 
 ```console
-$ sbx rm my-sandbox
+$ sbx rm claude-my-project
 $ sbx run claude
 ```
 
@@ -137,7 +142,7 @@ push or open a PR from there:
 
 ```console
 $ git worktree list                          # find the worktree path
-$ cd .sbx/<sandbox-name>-worktrees/my-feature
+$ cd .sbx/my-sandbox-worktrees/my-feature
 $ git log                                    # see what the agent did
 $ git push -u origin my-feature
 $ gh pr create
@@ -215,15 +220,21 @@ For common signing failures, see
 
 ## Reconnecting and naming
 
+When you don't pass `--name`, the sandbox is auto-named `<agent>-<directory>`,
+where `<directory>` is the workspace folder name. For example, running
+`sbx run claude` from `~/my-project` creates a sandbox named
+`claude-my-project`. Use this name with commands like `sbx stop`, `sbx rm`,
+and `sbx exec`. Run `sbx ls` to see the names of your existing sandboxes.
+
 Sandboxes persist after the agent exits. Running the same workspace path again
 reconnects to the existing sandbox rather than creating a new one:
 
 ```console
-$ sbx run claude ~/my-project  # creates sandbox
-$ sbx run claude ~/my-project  # reconnects to same sandbox
+$ sbx run claude ~/my-project  # creates sandbox claude-my-project
+$ sbx run claude ~/my-project  # reconnects to claude-my-project
 ```
 
-Use `--name` to make this explicit and avoid ambiguity:
+Use `--name` to set a custom name and avoid ambiguity:
 
 ```console
 $ sbx run claude --name my-project
@@ -267,7 +278,7 @@ side-by-side. Remove unused sandboxes when you're done to reclaim disk space:
 ```console
 $ sbx run claude ~/project-a
 $ sbx run claude ~/project-b
-$ sbx rm <sandbox-name>       # when finished
+$ sbx rm claude-project-a       # when finished
 ```
 
 ## Copying files between host and sandbox
@@ -277,9 +288,9 @@ your host and a sandbox. This is useful for one-off files that aren't part of a
 mounted workspace, such as generated output, logs, or setup files.
 
 ```console
-$ sbx cp ./config.json my-sandbox:/home/user/
-$ sbx cp my-sandbox:/home/user/output.log ./
-$ sbx cp ./src/ my-sandbox:/home/user/src
+$ sbx cp ./config.json claude-my-project:/home/user/
+$ sbx cp claude-my-project:/home/user/output.log ./
+$ sbx cp ./src/ claude-my-project:/home/user/src
 ```
 
 One side of the copy must use `SANDBOX:PATH`. Copying directly between two
@@ -308,30 +319,30 @@ 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 claude-my-project --publish 8080:3000   # host 8080 → sandbox port 3000
 $ open http://localhost:8080
 ```
 
 To let the OS pick a free host port instead of choosing one yourself:
 
 ```console
-$ sbx ports my-sandbox --publish 3000        # ephemeral host port
-$ sbx ports my-sandbox                       # check which port was assigned
+$ sbx ports claude-my-project --publish 3000        # ephemeral host port
+$ sbx ports claude-my-project                       # check which port was assigned
 ```
 
 `sbx ls` shows active port mappings alongside each sandbox, and `sbx ports`
 lists them in detail:
 
 ```console
 $ sbx ls
-SANDBOX         AGENT   STATUS   PORTS                    WORKSPACE
-my-sandbox      claude  running  127.0.0.1:8080->3000/tcp /home/user/proj
+SANDBOX             AGENT   STATUS   PORTS                    WORKSPACE
+claude-my-project   claude  running  127.0.0.1:8080->3000/tcp /home/user/proj
 ```
 
 To stop forwarding a port:
 
 ```console
-$ sbx ports my-sandbox --unpublish 8080:3000
+$ sbx ports claude-my-project --unpublish 8080:3000
 ```
 
 A few things to keep in mind:
@@ -346,7 +357,7 @@ A few things to keep in mind:
   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
+  must use `--unpublish 8080:3000`. Run `sbx ports claude-my-project` first if you
   used an ephemeral port and need to find the assigned host port.
 
 ## Accessing host services from a sandbox