From 50c469e538633a621dc36fb993c83905c4b8c67d Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 15 Jul 2026 07:32:19 +0000 Subject: [PATCH] docs(sandboxes): restructure get-started around value-first arc Reorder the sbx get-started page to lead with value for first-time users: run an agent, see how the sandbox isolates it, then control network access. Move clone mode and the interactive dashboard into "What's next", add an isolation payoff section, and drop the rm --force detour. Co-Authored-By: Claude Opus 4.8 --- content/manuals/ai/sandboxes/get-started.md | 137 +++++++++----------- 1 file changed, 62 insertions(+), 75 deletions(-) diff --git a/content/manuals/ai/sandboxes/get-started.md b/content/manuals/ai/sandboxes/get-started.md index 6df68f0127..4df5fae075 100644 --- a/content/manuals/ai/sandboxes/get-started.md +++ b/content/manuals/ai/sandboxes/get-started.md @@ -11,9 +11,9 @@ sandbox gets its own Docker daemon, filesystem, and network — the agent can build containers, install packages, and modify files without touching your host system. -This page walks through a typical first session: installing the CLI, -authenticating your agent, running a sandbox, isolating the agent's workspace, -and cleaning up. +This page walks through your first session: install the CLI, run an agent in a +sandbox, see how the sandbox isolates it, control what it can reach on the +network, and clean up. ## Prerequisites @@ -156,7 +156,15 @@ full list. The first run takes a little longer while the agent image is pulled. Subsequent runs reuse the cached image and start in seconds. -You can check what's running at any time: +This attaches you to the agent running inside the sandbox. Give it a real +task — ask it to add a feature, install a dependency, or build and run your +project. The agent has a full Linux environment with its own Docker daemon, so +it can install packages, build images, and start containers on its own while it +works. + +## See what the agent can touch + +From another terminal, list your sandboxes: ```console $ sbx ls @@ -164,62 +172,32 @@ SANDBOX AGENT STATUS PORTS WORKSPACE my-sandbox claude running ~/my-project ``` -You can also run `sbx` with no arguments to open an interactive dashboard. -The dashboard shows your sandboxes with live status, lets you attach to -agents, open shells, and manage network rules from one place. See -[Interactive mode](usage.md#interactive-mode) for details. +Each row shows a sandbox's name, the agent running in it, its status, any +[published ports](usage.md#accessing-services-in-the-sandbox), and its +workspace — the host directory shared into the sandbox. That workspace is the +one part of your machine the agent can see. -![The interactive dashboard showing sandbox status, resource usage, and network governance controls.](images/sbx-dashboard.png) +By default, the workspace is shared read-write, so 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. -## Use clone mode +Everything else runs inside the microVM, isolated from your host: -By default, the agent edits your working tree directly. To give the agent an -isolated copy of your repository, use `--clone`. Because `--clone` is a -create-time flag, stop and remove the existing sandbox first: +- The agent has its own filesystem, Docker daemon, and network. +- Packages it installs, images it pulls, and containers it starts stay inside + the sandbox. Your host system is untouched, and removing the sandbox discards + them. -```console -$ sbx stop my-sandbox -$ sbx rm my-sandbox -$ sbx run --clone --name my-sandbox claude -``` +If you'd rather the agent not touch your working tree at all — for example, +when running several agents on one repository — use +[clone mode](usage.md#clone-mode), which gives it a private clone instead. -In clone mode, the sandbox keeps a private Git clone inside the microVM and -mounts your host repository read-only. The sandbox exposes its clone as a -`sandbox-` remote on your host, so you review the agent's -commits the same way you'd fetch from any other remote: +## Control what the agent can reach -```console -$ git fetch sandbox-my-sandbox -$ git log sandbox-my-sandbox/main -$ git diff main..sandbox-my-sandbox/main -``` - -When you're ready to create a pull request: - -```console -$ git checkout -b my-feature sandbox-my-sandbox/main -$ git push -u origin my-feature -$ gh pr create -``` - -For Claude Code, pair `--clone` with the -[agents view](agents/claude-code.md#agents-view) to dispatch tasks to -subagents that each work on their own branch inside the same sandbox: - -```console -$ sbx run --clone --name my-sandbox claude -- agents -``` - -Clone mode is especially useful when running multiple agents on the same -repository in parallel — each works in its own isolated clone without -touching your host working tree. See [Clone mode](usage.md#clone-mode) for -the full workflow, including how to have the agent commit to a dedicated -branch. - -## Manage network access - -Your network policy controls what the sandbox can reach. If the agent fails to -connect to an API or service, it's likely blocked by the policy. +Isolation isn't only about the filesystem. You also control what the sandbox +can reach on the network. You chose a default policy when you signed in, and +you can inspect or adjust it at any time. Check which rules are in effect: @@ -233,14 +211,16 @@ To allow a specific host: $ sbx policy allow network registry.npmjs.org ``` -With **Locked Down**, even your model provider API is blocked unless you -explicitly allow it. With **Balanced**, common development services are -permitted by default. See [Policies](governance/local.md) for the full rule -set and how to customize it. +With **Balanced**, common development services are allowed by default. With +**Locked Down**, everything is blocked until you allow it — including your +model provider's API. If the agent can't reach a service it needs, the network +policy is the first place to look. See [Policies](governance/local.md) for the +full rule set and how to customize it. ## Clean up -Sandboxes persist after the agent exits. To stop a sandbox without deleting it: +Sandboxes persist after the agent exits, so you can stop one and pick up where +you left off later: ```console $ sbx stop my-sandbox @@ -254,24 +234,31 @@ space: $ sbx rm my-sandbox ``` -If the sandbox has an active session, pass `--force`: - -```console -$ sbx rm --force my-sandbox -``` - Removing a sandbox deletes everything inside it — installed packages, Docker images, and the in-sandbox Git clone if you used clone mode. Files in your host working tree are unaffected. -## Next steps +## What's next -- [Usage guide](usage.md) — sandbox management, reconnecting, multiple - workspaces, port forwarding, and more -- [Agents](agents/) — supported agents and configuration -- [Customize](customize/) — build reusable templates or declare capabilities - with kits -- [Credentials](security/credentials.md) — credential storage and management -- [Workspace isolation](security/isolation.md#workspace-isolation) — what - the agent can affect on your host, and how to review changes -- [Governance](governance/) — control outbound access +You've run an agent, seen how the sandbox isolates it, and controlled its +network access. A few directions from here. + +Run `sbx` with no arguments to open the interactive dashboard: a live view of +every sandbox where you can attach to agents, open shells, and manage network +rules from one place. + +![The interactive dashboard showing sandbox status, resource usage, and network governance controls.](images/sbx-dashboard.png) + +Then explore: + +- [Clone mode](usage.md#clone-mode) — give each agent an isolated Git clone + instead of your working tree, so you can run several agents on one repository + in parallel and review each one's commits separately. +- [Customize with kits](customize/) — package an agent, its tools, and its + network rules into a reusable definition you launch with a single flag. +- [Agents](agents/) — the full list of supported agents and how to configure + each one. +- [Governance](governance/) — centrally manage network and filesystem policies + across a team. +- [Usage guide](usage.md) — reconnecting, multiple workspaces, port forwarding, + and more.