Merge pull request #25322 from dvdksn/worktree-sbx-content-audit-fixes

Content quality fixes for AI Sandboxes docs
2026-06-19 07:35:16 +00:00 · 2026-06-10 14:54:50 +02:00
parent 7cea2802c1 3ed5acc026
commit c5fea43c1f
11 changed files with 39 additions and 41 deletions
@@ -7,7 +7,7 @@ description: |
 keywords: docker sandboxes, docker agent, openai, anthropic, sbx
 ---

-Official documentation: [Docker Agent](https://docs.docker.com/ai/docker-agent/)
+Official documentation: [Docker Agent](/manuals/ai/docker-agent/_index.md)

 ## Quick start

@@ -21,7 +21,7 @@ command instead of an interactive shell, pass it after `--`:
 $ sbx run shell -- -c "echo 'Hello from sandbox'"
 ```

-### Default startup command
+## Default startup command

 Without extra args, the sandbox runs `bash -l`. Args after `--` replace `-l`
 rather than being appended. To preserve login-shell behavior, include `-l`
@@ -57,7 +57,8 @@ installed packages and Docker images.
 Sandboxes persist until explicitly removed. Stopping an agent doesn't delete
 the VM; environment setup carries over between runs. Use `sbx rm` to delete
 the sandbox, its VM, and all of its contents. If the sandbox used
-`--branch`, the worktree directories and their branches are also removed.
+[`--clone`](usage.md#clone-mode), the `sandbox-<name>` Git remote is also
+removed from your host repository.

 ## Comparison to alternatives

@@ -112,17 +112,23 @@ certificates without further configuration.

 ## Run a background service

-<!-- TODO: follow up on commands.startup[].background.
-     `background: true` on its own isn't enough to keep a
-     long-running service alive — the process exits shortly after start.
-     Using `nohup … &` inside a shell command is the current workaround
-     and what this section teaches. If background ever actually daemonizes
-     the command, this section can be simplified. -->
+`commands.startup` runs on every sandbox start. To keep a long-running
+service such as a dev server or daemon alive, set `background: true`. The
+sandbox runs the command in the background and replays startup commands on
+each start, so the service comes back after a stop/start cycle:

-`commands.startup` runs at every sandbox start. For long-running
-services, background them inside a shell command and redirect output to
-a log file. Relying on the `background: true` field alone can leave
-the service attached to a shell that exits, which silently kills it.
+```yaml
+commands:
+  startup:
+    - command: ["my-service", "--port", "8080"]
+      user: "1000"
+      background: true
+```
+
+A background service doesn't write to your terminal. To capture its output
+for debugging, wrap the command in a shell and redirect to a log file. Let
+`background: true` run the command in the background rather than adding a
+trailing `&` yourself:

 ```yaml
 commands:
@@ -130,14 +136,13 @@ commands:
    - command:
        - sh
        - -c
-        - nohup my-service --port 8080 > /tmp/my-service.log 2>&1 &
+        - my-service --port 8080 > /tmp/my-service.log 2>&1
      user: "1000"
+      background: true
 ```

-The log file is worth the extra flag: if the service exits early, its
-stderr goes to a parent shell that isn't attached to anything you can
-read. An empty log file tells you the wrapper ran; a populated one
-tells you why it failed.
+An empty log file tells you the wrapper ran; a populated one tells you why
+the service failed.

 ## Bake runtime values into a file with initFiles

@@ -60,7 +60,8 @@ idempotent — see the [`startup`](#startup) spec reference:
 ```yaml
 commands:
  startup:
-    - command: ["sh", "-c", "my-daemon &"]
+    - command: ["my-daemon"]
+      background: true
 ```

 ### Inject files
@@ -292,8 +293,9 @@ select = ["E", "F", "I"]
 ```

 > [!TIP]
-> The templates for the built-in agents (`claude`, `codex`, etc) already
-> includes `uv`, so this mixin can use it without installing it separately.
+> The templates for the built-in agents (`claude`, `codex`, and so on)
+> already include `uv`, so this mixin can use it without installing it
+> separately.

 To start a new sandbox with this mixin:

@@ -82,7 +82,7 @@ $ sbx run claude --template docker.io/docker/sandbox-templates:claude-code
 ### Build a custom template

 Building a custom template requires
-[Docker Desktop](https://docs.docker.com/desktop/).
+[Docker Desktop](/manuals/desktop/_index.md).

 Write a Dockerfile that extends one of the base images. Pick the variant
 that matches the agent you plan to run. For example, extend `claude-code`
@@ -18,7 +18,8 @@ Signing in gives each sandbox a verified identity, which lets Docker:
  audit logs need a concept of "who," and adding that later would be worse for
  everyone.
 - **Authenticate against Docker infrastructure.** Sandboxes pull images, run
-  daemons, and talk to Docker services. A Docker account makes that seamless.
+  daemons, and talk to Docker services. A Docker account authenticates those
+  requests.

 Your Docker account email is only used for authentication, not marketing.

@@ -198,7 +198,7 @@ Use SSH agent forwarding for Git operations over SSH and SSH-based commit
 signing. The signing key must be loaded in the host SSH agent for sandboxed
 commit signing to work. Outbound SSH connections are still subject to sandbox
 network policy. For details, see
-[Signed commits](../usage.md#signed-commits).
+[Commit signing](../workflows.md#commit-signing).

 ## Custom secrets

@@ -57,7 +57,7 @@ Mounting your host Docker socket into a container would give the agent full
 access to your environment.

 Docker Sandboxes avoid this by running a separate [Docker
-Engine](https://docs.docker.com/engine/) inside the sandbox environment, isolated from
+Engine](/manuals/engine/_index.md) inside the sandbox environment, isolated from
 your host. When the agent runs `docker build` or `docker compose up`, those
 commands execute against that engine. The agent has no path to your host Docker
 daemon.
@@ -183,8 +183,9 @@ Extracting the tar archive as the current user avoids the `chown` call.

 Filesystem operations such as `git status`, `git log`, or directory scans can
 be noticeably slow when the sandbox workspace is mounted in direct mode (the
-default for workspaces without `--clone`). The slowness occurs because virtiofs
-caching is disabled by default to prevent data corruption.
+default for workspaces without `--clone`). In direct mode, virtiofs caching is
+disabled by default to prevent data corruption. Clone-mode sandboxes enable
+virtiofs caching automatically, so this tuning applies only to direct mode.

 To speed up filesystem-intensive workloads, opt into virtiofs caching when
 creating the sandbox:
@@ -226,22 +227,10 @@ the command again:
 ✓ Git repository detected: \\wsl.localhost\Ubuntu\home\you\repo
 ```

-## Stale Git worktree after removing a sandbox
-
-If you used `--branch`, worktree cleanup during `sbx rm` is best-effort. If
-it fails, the sandbox is removed but the branch and worktree are left behind.
-If `git worktree list` shows a stale worktree in `.sbx/` after removing a
-sandbox, clean it up manually:
-
-```console
-$ git worktree remove .sbx/<sandbox-name>-worktrees/<branch-name>
-$ git branch -D <branch-name>
-```
-
 ## Sandbox commits aren't signed

 Docker Sandboxes can sign Git commits with SSH keys from your host agent.
-For setup steps, see [Signed commits](usage.md#signed-commits).
+For setup steps, see [Commit signing](workflows.md#commit-signing).

 If `ssh-add -L` prints `The agent has no identities.`, the sandbox can reach
 the forwarded agent, but the host agent doesn't have a loaded key. Load the
@@ -246,7 +246,7 @@ packages persist for the sandbox's lifetime. For teams or repeated setups,
 see [Customize](customize/) for reusable templates and declarative kits.

 Agents can also build Docker images, run containers, and use
-[Compose](https://docs.docker.com/compose/). Everything runs inside the sandbox's private Docker
+[Compose](/manuals/compose/_index.md). Everything runs inside the sandbox's private Docker
 daemon, so containers started by the agent never appear in your host's
 `docker ps`. When you remove the sandbox, all images, containers, and volumes
 inside it are deleted with it.