diff --git a/content/manuals/ai/sandboxes/agents/docker-agent.md b/content/manuals/ai/sandboxes/agents/docker-agent.md index 713cb2a265a..d0fc2e2259d 100644 --- a/content/manuals/ai/sandboxes/agents/docker-agent.md +++ b/content/manuals/ai/sandboxes/agents/docker-agent.md @@ -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 diff --git a/content/manuals/ai/sandboxes/agents/shell.md b/content/manuals/ai/sandboxes/agents/shell.md index 004bb0c1f9a..54d88a60dc0 100644 --- a/content/manuals/ai/sandboxes/agents/shell.md +++ b/content/manuals/ai/sandboxes/agents/shell.md @@ -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` diff --git a/content/manuals/ai/sandboxes/architecture.md b/content/manuals/ai/sandboxes/architecture.md index b8d9f2c1e73..19b975b77bd 100644 --- a/content/manuals/ai/sandboxes/architecture.md +++ b/content/manuals/ai/sandboxes/architecture.md @@ -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-` Git remote is also +removed from your host repository. ## Comparison to alternatives diff --git a/content/manuals/ai/sandboxes/customize/kit-examples.md b/content/manuals/ai/sandboxes/customize/kit-examples.md index 2e8556cead3..9bf728e64e3 100644 --- a/content/manuals/ai/sandboxes/customize/kit-examples.md +++ b/content/manuals/ai/sandboxes/customize/kit-examples.md @@ -112,17 +112,23 @@ certificates without further configuration. ## Run a background service - - -`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. +`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: + +```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 diff --git a/content/manuals/ai/sandboxes/customize/kits.md b/content/manuals/ai/sandboxes/customize/kits.md index eb7038d8f79..59b0cec6cab 100644 --- a/content/manuals/ai/sandboxes/customize/kits.md +++ b/content/manuals/ai/sandboxes/customize/kits.md @@ -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: diff --git a/content/manuals/ai/sandboxes/customize/templates.md b/content/manuals/ai/sandboxes/customize/templates.md index b525f0caf86..da4410bb740 100644 --- a/content/manuals/ai/sandboxes/customize/templates.md +++ b/content/manuals/ai/sandboxes/customize/templates.md @@ -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` diff --git a/content/manuals/ai/sandboxes/faq.md b/content/manuals/ai/sandboxes/faq.md index 2e60dff35f7..79a2c94652d 100644 --- a/content/manuals/ai/sandboxes/faq.md +++ b/content/manuals/ai/sandboxes/faq.md @@ -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. diff --git a/content/manuals/ai/sandboxes/security/credentials.md b/content/manuals/ai/sandboxes/security/credentials.md index 68f00d2abc7..644646f51c9 100644 --- a/content/manuals/ai/sandboxes/security/credentials.md +++ b/content/manuals/ai/sandboxes/security/credentials.md @@ -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 diff --git a/content/manuals/ai/sandboxes/security/isolation.md b/content/manuals/ai/sandboxes/security/isolation.md index 10404d02313..872cdfc1437 100644 --- a/content/manuals/ai/sandboxes/security/isolation.md +++ b/content/manuals/ai/sandboxes/security/isolation.md @@ -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. diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index 240f96256a2..b89710ac0a5 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -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/-worktrees/ -$ git branch -D -``` - ## 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 diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md index 5d6ba2c3d3e..0b4eb1c2d94 100644 --- a/content/manuals/ai/sandboxes/usage.md +++ b/content/manuals/ai/sandboxes/usage.md @@ -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.