docker · dvdksn · Aug 20, 2026 · Aug 20, 2026 · Aug 20, 2026 · Aug 21, 2026
diff --git a/content/guides/claude-code-sandbox-model-runner.md b/content/guides/claude-code-sandbox-model-runner.md
@@ -147,7 +147,7 @@ see the
 Run Claude Code in the sandbox and pass the model flag through to the agent:
 
 ```console
-$ sbx run claude-dmr -- --model ai/devstral-small-2
+$ sbx run --name claude-dmr -- --model ai/devstral-small-2
 ```
 
 Everything after `--` is forwarded to the Claude Code CLI.
@@ -181,7 +181,7 @@ Then point Claude Code at the packaged model the next time you run the
 sandbox:
 
 ```console
-$ sbx run claude-dmr -- --model gpt-oss:32k
+$ sbx run --name claude-dmr -- --model gpt-oss:32k
 ```
 
 ## Clean up

@@ -10,8 +10,8 @@ params:
 
 Docker Sandboxes run AI coding agents in isolated microVM sandboxes. Each
 sandbox gets its own Docker daemon, filesystem, and network — the agent can
-build containers, install packages, and modify files without touching your host
-system.
+build containers, install packages, and modify files without accessing host
+resources beyond those you share.
 
 > [!NOTE]
 > The `sbx` CLI is free to use, including for commercial work. Only

@@ -17,16 +17,18 @@ Launch Claude Code in a sandbox by pointing it at a project directory:
 $ sbx run claude ~/my-project
 ```
 
-The workspace parameter defaults to the current directory, so `sbx run claude`
-from inside your project works too. To start Claude with a specific prompt:
+To start Claude with a specific prompt in the current directory:
 
 ```console
-$ sbx run claude --name my-sandbox -- "Add error handling to the login function"
+$ sbx run --name my-sandbox claude -- "Add error handling to the login function"
 ```
 
 Everything after `--` is passed directly to Claude Code. You can also pipe in a
 prompt from a file with `-- "$(cat prompt.txt)"`.
 
+To create a [mountless sandbox](../usage.md#choose-a-workspace), use
+`sbx create` without a workspace path, then attach by name.
+
 ## Authentication
 
 Claude Code requires either an Anthropic API key or a Claude subscription.
@@ -71,7 +73,7 @@ itself a flag (begins with `-`), so `--dangerously-skip-permissions` is
 preserved:
 
 ```console
-$ sbx run claude -- -c   # runs claude --dangerously-skip-permissions -c
+$ sbx run --name <sandbox-name> -- -c   # runs claude --dangerously-skip-permissions -c
 ```
 
 When the first argument is a bare word, such as the `agents` subcommand, it
@@ -88,7 +90,7 @@ starts background sessions that run tasks in parallel. Pair it with
 sandbox:
 
 ```console
-$ sbx run --clone claude -- agents
+$ sbx run --clone claude . -- agents
 ```
 
 This invocation replaces the
@@ -98,7 +100,7 @@ bypass-permissions mode inside the sandbox. To work around this, either
 use Claude Code's auto mode or pass the flag explicitly:
 
 ```console
-$ sbx run --clone claude -- --dangerously-skip-permissions agents
+$ sbx run --clone claude . -- --dangerously-skip-permissions agents
 ```
 
 Claude Code may use branches or worktrees to keep changes from its background

@@ -20,13 +20,16 @@ Create a sandbox and run Codex for a project directory:
 $ sbx run codex ~/my-project
 ```
 
-The workspace parameter is optional and defaults to the current directory:
+`sbx run` defaults the workspace to the current directory:
 
 ```console
 $ cd ~/my-project
 $ sbx run codex
 ```
 
+To create a [mountless sandbox](../usage.md#choose-a-workspace), use
+`sbx create` without a workspace path, then attach by name.
+
 ## Authentication
 
 If you haven't stored an OpenAI credential, `sbx run codex` prompts you to
@@ -75,7 +78,7 @@ itself a flag (begins with `-`). A bare word — such as a prompt — replaces t
 defaults instead, so lead with the flag to keep bypass mode:
 
 ```console
-$ sbx run codex -- --dangerously-bypass-approvals-and-sandbox "fix the build"
+$ sbx run --name <sandbox-name> -- --dangerously-bypass-approvals-and-sandbox "fix the build"
 ```
 
 ## Base image

@@ -20,13 +20,16 @@ Create a sandbox and run Cursor for a project directory:
 $ sbx run cursor ~/my-project
 ```
 
-The workspace parameter is optional and defaults to the current directory:
+`sbx run` defaults the workspace to the current directory:
 
 ```console
 $ cd ~/my-project
 $ sbx run cursor
 ```
 
+To create a [mountless sandbox](../usage.md#choose-a-workspace), use
+`sbx create` without a workspace path, then attach by name.
+
 ## Authentication
 
 Cursor supports two authentication methods: an API key or OAuth.
@@ -65,7 +68,7 @@ Arguments after `--` are added after the default flags when the first one is
 itself a flag (begins with `-`), so `--yolo` is preserved:
 
 ```console
-$ sbx run cursor -- -p "refactor this"   # runs cursor-agent --yolo -p "refactor this"
+$ sbx run --name <sandbox-name> -- -p "refactor this"   # runs cursor-agent --yolo -p "refactor this"
 ```
 
 When the first argument is a bare word — a subcommand or prompt — it replaces

@@ -17,8 +17,11 @@ Create a sandbox and run Docker Agent for a project directory:
 $ sbx run docker-agent ~/my-project
 ```
 
-The workspace parameter defaults to the current directory, so
-`sbx run docker-agent` from inside your project works too.
+`sbx run docker-agent` defaults the workspace to the current directory, so you
+can run it from inside your project.
+
+To create a [mountless sandbox](../usage.md#choose-a-workspace), use
+`sbx create` without a workspace path, then attach by name.
 
 ## Authentication
 
@@ -60,7 +63,7 @@ as the `run` subcommand or a config file — it replaces the defaults, so includ
 `run --yolo` yourself:
 
 ```console
-$ sbx run docker-agent -- run --yolo agent.yml
+$ sbx run --name <sandbox-name> -- run --yolo agent.yml
 ```
 
 ## Base image

@@ -20,13 +20,16 @@ Create a sandbox and run Gemini for a project directory:
 $ sbx run gemini ~/my-project
 ```
 
-The workspace parameter is optional and defaults to the current directory:
+`sbx run` defaults the workspace to the current directory:
 
 ```console
 $ cd ~/my-project
 $ sbx run gemini
 ```
 
+To create a [mountless sandbox](../usage.md#choose-a-workspace), use
+`sbx create` without a workspace path, then attach by name.
+
 ## Authentication
 
 Gemini requires either a Google API key or a Google account with Gemini access.
@@ -65,7 +68,7 @@ Arguments after `--` are added after the default flags when the first one is
 itself a flag (begins with `-`), so `--yolo` is preserved:
 
 ```console
-$ sbx run gemini -- -p "explain this"   # runs gemini --yolo -p "explain this"
+$ sbx run --name <sandbox-name> -- -p "explain this"   # runs gemini --yolo -p "explain this"
 ```
 
 When the first argument is a bare word — a subcommand or prompt — it replaces

@@ -20,13 +20,16 @@ Create a sandbox and run OpenCode for a project directory:
 $ sbx run opencode ~/my-project
 ```
 
-The workspace parameter is optional and defaults to the current directory:
+`sbx run` defaults the workspace to the current directory:
 
 ```console
 $ cd ~/my-project
 $ sbx run opencode
 ```
 
+To create a [mountless sandbox](../usage.md#choose-a-workspace), use
+`sbx create` without a workspace path, then attach by name.
+
 OpenCode launches a TUI (text user interface) where you can select your
 preferred LLM provider and interact with the agent.
 
@@ -94,7 +97,7 @@ The sandbox runs `opencode` with no implicit flags. Args after `--` are passed
 straight through. For example, to resume an existing session:
 
 ```console
-$ sbx run opencode -- -s <session-id>
+$ sbx run --name <sandbox-name> -- -s <session-id>
 ```
 
 ### TUI mode

@@ -14,13 +14,21 @@ environment.
 $ sbx run shell ~/my-project
 ```
 
-The workspace path defaults to the current directory. To run a one-off
+`sbx run` defaults the workspace to the current directory. To run a one-off
 command instead of an interactive shell, pass it after `--`:
 
 ```console
 $ sbx run shell -- -c "echo 'Hello from sandbox'"
 ```
 
+To create a [mountless sandbox](../usage.md#choose-a-workspace), use
+`sbx create` without a workspace path, then attach by name:
+
+```console
+$ sbx create --name scratch shell
+$ sbx run --name scratch
+```
+
 ## Default startup command
 
 Without extra args, the sandbox runs `bash -l`. When the first argument after

@@ -8,16 +8,32 @@ keywords: docker sandboxes, architecture, microVM, workspace mounting, sandbox l
 This page explains how Docker Sandboxes work under the hood. For the security
 properties of the architecture, see [Sandbox isolation](security/isolation.md).
 
-## Workspace mounting
-
-Your workspace is mounted directly into the sandbox through a filesystem
-passthrough. The sandbox sees your actual host files, so changes in either
-direction are instant with no sync process involved.
-
-Your workspace is mounted at the same absolute path as on your host. Preserving
-absolute paths means error messages, configuration files, and build outputs all
-reference paths you can find on your host. The agent sees exactly the directory
-structure you see, which reduces confusion when debugging or reviewing changes.
+## Workspace storage
+
+Starting with `sbx` version 0.42.0, workspace paths are optional for
+`sbx create`. When you omit them, the sandbox has no host workspace bind mount.
+The sandbox uses the template image's configured `WORKDIR` as its default
+working directory. Docker-provided agent templates set `WORKDIR` to
+`/home/agent/workspace`. A custom template can set another absolute path. If
+the daemon can't resolve a usable absolute `WORKDIR` from the image config, it
+falls back to `/home/agent/workspace`. Files created there stay inside the
+sandbox and persist across stops and restarts.
+
+When you pass a workspace path to `sbx create` or `sbx run`, the directory is
+mounted into the sandbox through a filesystem passthrough. `sbx run` uses the
+current directory when you don't pass a path. The sandbox sees your actual
+host files, so changes in either direction are instant with no sync process
+involved.
+
+A directly mounted workspace appears at the same absolute path as on your
+host. Preserving absolute paths means error messages, configuration files, and
+build outputs all reference paths you can find on your host. The agent sees the
+same directory structure, which reduces confusion when debugging or reviewing
+changes.
+
+Clone mode uses a third storage layout. The host repository is mounted
+read-only at `/run/sandbox/source`, and the agent works in a private clone
+inside the sandbox. See [Clone mode](usage.md#clone-mode).
 
 > [!WARNING]
 > Avoid mounting network-attached or remote storage (network drives, SMB/NFS
@@ -29,7 +45,8 @@ structure you see, which reduces confusion when debugging or reviewing changes.
 
 When you create a sandbox, everything inside it persists until you remove it:
 Docker images and containers built or pulled by the agent, installed packages,
-agent state and history, and workspace changes.
+agent state and history, and files in mountless or cloned workspaces. Files in
+a directly mounted workspace live on the host instead.
 
 Each sandbox maintains its own Docker daemon state, image cache, and package
 installations. Multiple sandboxes don't share images or layers. The
@@ -40,14 +57,15 @@ when creating the sandbox.
 Each sandbox consumes disk space for its VM image, Docker images, container
 layers, and volumes, and this grows as you build images and install packages.
 
-Virtiofs caching is enabled by default on all operating systems. File reads
-from the sandbox VM are cached on the host side, reducing round-trips through
-the filesystem passthrough and improving performance for read-heavy workloads
-such as `git status` or directory scans. To opt out, set
+Virtiofs caching is enabled by default for directly mounted workspaces on all
+operating systems. File reads from the sandbox VM are cached on the host side,
+reducing round-trips through the filesystem passthrough and improving
+performance for read-heavy workloads such as `git status` or directory scans.
+To opt out, set
 `DOCKER_SANDBOXES_ENABLE_VIRTIOFS_CACHE=0` when creating the sandbox:
 
 ```console
-$ DOCKER_SANDBOXES_ENABLE_VIRTIOFS_CACHE=0 sbx run <template>
+$ DOCKER_SANDBOXES_ENABLE_VIRTIOFS_CACHE=0 sbx run <agent>
 ```
 
 ## Networking
@@ -98,9 +116,9 @@ tool calls, resource reads, prompt retrieval, or gateway meta-tool execution.
 
 ## Lifecycle
 
-`sbx run` initializes a VM with a workspace for a specified agent and starts
-the agent. You can stop and restart without recreating the VM, preserving
-installed packages and Docker images.
+`sbx run` initializes a VM for a specified agent and starts the agent. You can
+stop and restart without recreating the VM, preserving installed packages,
+Docker images, and in-sandbox files.
 
 Sandboxes persist until explicitly removed. Stopping an agent doesn't delete
 the VM; environment setup carries over between runs. Use `sbx rm` to delete

@@ -260,7 +260,7 @@ When specified as a string, `workspace` is the path. Use the object form for
 clone mode:
 
 > [!WARNING]
-> With [direct mount](../security/isolation.md#direct-mount-default), the agent can
+> With [direct mount](../security/isolation.md#direct-mount), the agent can
 > modify every file in a workspace. If an environment file is inside a mounted
 > workspace, the agent can change the file that controls later `sbx env`
 > commands. Store environment files outside all direct-mounted workspaces.

@@ -427,6 +427,12 @@ the sandbox with the kit.
 Runs synchronously when a kit is applied, either during sandbox creation or
 through `sbx kit add`. Shell strings are passed to `sh -c`.
 
+Kit install commands start in the template image's configured `WORKDIR`.
+Docker-provided templates use `/home/agent/workspace`, which isn't necessarily
+the primary workspace in a direct-mounted or clone-mode sandbox. Don't rely on
+the current directory to locate workspace files. Use absolute paths for bundled
+assets from `files/home/`.
+
 | Field         | Default | Description                   |
 | ------------- | ------- | ----------------------------- |
 | `command`     | —       | Shell command string.         |

@@ -8,8 +8,8 @@ keywords: sandbox, sbx, get started, credentials, clone mode, network policy
 
 Docker Sandboxes run AI coding agents in isolated microVM sandboxes. Each
 sandbox gets its own Docker daemon, filesystem, and network — the agent can
-build containers, install packages, and modify files without touching your host
-system.
+build containers, install packages, and modify files without accessing host
+resources beyond those you share.
 
 This page walks through your first session: run an agent in a sandbox, see how
 the sandbox isolates it, control what it can reach on the network, and clean
@@ -99,7 +99,8 @@ Each row shows a sandbox's name, the agent running in it, its status, any
 workspace — the host directory shared into the sandbox. That workspace is the
 one part of your machine the agent can see.
 
-By default, the workspace is shared read-write, so the agent and your host see
+When you run `sbx run` from a project directory without passing a workspace
+path, the current directory is mounted read-write. The agent and your host see
 the same files. Edits the agent makes to your project appear in your working
 tree as it writes them, and you review them as an ordinary Git diff before
 committing.

@@ -63,13 +63,17 @@ $ ssh demo.sbx
 ## Select the workspace folder
 
 Connecting an app to a sandbox selects the remote environment, but it might not
-open the mounted workspace automatically. Use the app's remote folder picker to
-select the workspace when you configure the connection or start a session.
-
-The folder picker might open at the sandbox user's home directory, typically
-`/home/agent`. Workspaces retain their absolute host paths inside the sandbox.
-For example, if you mount `/Users/bob/src/my-project`, select
-`/Users/bob/src/my-project` in the remote folder picker.
+open the primary workspace automatically. The initial folder depends on the
+client. A remote folder picker might open at the sandbox user's home directory,
+`/home/agent`, while an interactive `ssh` shell might start in
+`/home/agent/workspace`. Select the intended folder explicitly instead of
+relying on the initial location.
+
+For a sandbox with a primary workspace, each workspace path appears inside the
+sandbox at the same absolute path as on the host. For example, if you pass
+`/Users/bob/src/my-project`, select that path in the remote folder picker. For
+a mountless sandbox that uses a Docker-provided agent template, select
+`/home/agent/workspace`.
 
 ## Connect a specific tool