From ad7c49acf9cd3ebd1191ba010fdd7b7f9a5a3784 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Sun, 17 May 2026 17:39:20 -0700 Subject: [PATCH 1/2] docs(local-sandboxes): add Local Sandboxes feature page Introduces Local Sandboxes as a feature name (powered by Docker) covering when to use a local sandbox, how they work, prerequisites, how to launch one, what's available inside, and current limitations. - New page: agent-platform/local-agents/local-sandboxes.mdx - security-overview.mdx: rename 'Docker Sandboxes' subsection to 'Local Sandboxes' and link to the new page; trim aspirational bullets that aren't shipping today. - all-settings.mdx: link the 'docker_sandbox' default_session_mode value to the new page. - sidebar.ts: register the new page under Warp Agents > Capabilities. Co-Authored-By: Oz --- .../local-agents/local-sandboxes.mdx | 87 +++++++++++++++++++ .../security-overview.mdx | 9 +- .../docs/terminal/settings/all-settings.mdx | 2 +- src/sidebar.ts | 1 + 4 files changed, 92 insertions(+), 7 deletions(-) create mode 100644 src/content/docs/agent-platform/local-agents/local-sandboxes.mdx diff --git a/src/content/docs/agent-platform/local-agents/local-sandboxes.mdx b/src/content/docs/agent-platform/local-agents/local-sandboxes.mdx new file mode 100644 index 00000000..05803da3 --- /dev/null +++ b/src/content/docs/agent-platform/local-agents/local-sandboxes.mdx @@ -0,0 +1,87 @@ +--- +title: Local Sandboxes +description: >- + Run agent conversations and terminal commands in an isolated container on + your local machine, without exposing your home directory or current repo. +sidebar: + label: "Local Sandboxes" +--- + +A **Local Sandbox** is an isolated shell session that runs in a container on your local machine, so the agent (and any commands you run alongside it) can't see or write to your home directory or current repository by default. Use it to try unfamiliar tooling, run risky setup steps, or hand a long-running task to an agent without giving it access to your personal files. + +Local Sandboxes are powered by Docker. Each sandbox is a fresh, ephemeral container; closing the pane ends the session. + +:::note +Local Sandboxes are rolling out gradually. The entry points below may not be visible in every build yet. +::: + +## When to use a local sandbox + +Reach for a Local Sandbox when you want isolation without leaving your machine: + +* **Try risky commands** - Run setup scripts, package installs, or experimental tooling without polluting your host environment. +* **Hand a task to an agent against an unfamiliar repo** - Give the agent room to clone, build, and run code without exposing your existing checkout. +* **Test a clean toolchain** - Reproduce a "fresh box" so you can see what your project actually needs to bootstrap. +* **Isolate experiments from your local working tree** - Keep half-finished work and uncommitted changes from leaking into the next thing you try. + +For agent isolation in Warp's cloud infrastructure, see [Cloud agents](/agent-platform/cloud-agents/overview/). For the GUI sandbox used by Computer Use, see [Computer use](/agent-platform/capabilities/computer-use/). + +## How local sandboxes work + +Each Local Sandbox is a fresh Docker container with a bash shell: + +* **Fresh container per sandbox** - Warp creates a new container each time you open a sandbox and gives it its own scratch workspace. Sandboxes don't share filesystem state with each other or with your host shell. +* **No implicit access to your files** - Your home directory and current working directory aren't mounted in by default. The sandbox starts in an empty workspace inside the container. +* **Bash shell** - The shell inside the sandbox is bash, regardless of which shell you use on the host. +* **Warp features work as normal** - Agent conversations, blocks, slash commands, and the rest of the Warp experience work the same way they do in a host shell. + +## Prerequisites + +* **Docker installed and running locally** - Warp uses Docker to create the sandbox container. Install Docker Desktop (or your distribution's Docker engine) and confirm `docker info` succeeds before launching a sandbox. +* **Warp's local sandbox helper available on `PATH`** - Warp invokes a bundled helper to drive the container lifecycle. The helper must be on the `PATH` that your interactive shell sees, not just the `PATH` your GUI launcher provides. If launching the sandbox fails with a "binary not found" error, open a regular Warp terminal and confirm the helper resolves there before retrying. + +## Starting a local sandbox + +You can launch a Local Sandbox from three places in the Warp app. + +### Slash command + +In any local terminal session, type `/docker-sandbox` and submit. Warp opens a new pane running the sandbox. + +### New-session menu + +Open the new-session dropdown (the `+` button next to the tab bar) and choose **Local Docker Sandbox**. Warp opens a new tab running the sandbox. + +### Default for new sessions + +Set the default mode for new sessions to **Local Docker Sandbox** so every new tab launches a sandbox. The setting lives in [`settings.toml`](/terminal/settings/) as the `default_session_mode` key under `[general]`: + +```toml title="settings.toml" +[general] +default_session_mode = "docker_sandbox" +``` + +The same setting is also available in the Warp app under **Settings** > **Features** as **Default session mode**. + +## What's available inside the sandbox + +* **Bash shell** - A standard bash environment is the starting point. Install whatever tooling you need for the task at hand; changes stay inside the container. +* **Agent conversations** - Start an agent conversation inside the sandbox the same way you would in any other terminal session. The agent's actions are scoped to the container. +* **Cloned repositories, when you add them** - The sandbox doesn't mount your local checkout. Clone any code you want to work with (for example, `git clone `) from inside the sandbox. + +## Limitations + +Local Sandboxes have a few constraints to be aware of today: + +* **Local sessions only** - Local Sandboxes aren't available inside remote SSH sessions or in Warp's web client. +* **Empty workspace by default** - The sandbox starts in an empty directory. Your local repo isn't mounted in; clone it (or any other code) from inside the sandbox if you need it there. +* **CLI agent plugin install uses the manual flow** - Third-party CLI agent plugin installers run against the host shell, not the container. Inside a sandbox session, Warp shows the manual install instructions so you can run them inside the container yourself. +* **No automatic cleanup on close** - Closing a sandbox pane stops the session but doesn't remove the underlying container. Stopped sandbox containers stay on disk until you remove them; run `docker container prune` if you want to free up the space. + +## Related pages + +* [Warp Agents overview](/agent-platform/local-agents/overview/) - Run Warp's agents in any local session, including a Local Sandbox. +* [Environments](/agent-platform/cloud-agents/environments/) - Define repos, base image, and setup commands for cloud agent runs. +* [Computer use](/agent-platform/capabilities/computer-use/) - The cloud-side sandbox for desktop GUI automation. +* [Security overview](/enterprise/security-and-compliance/security-overview/#local-sandboxes) - How Local Sandboxes fit into Warp's broader isolation story. +* [All settings](/terminal/settings/all-settings/) - Reference for the `default_session_mode` setting and other `settings.toml` keys. diff --git a/src/content/docs/enterprise/security-and-compliance/security-overview.mdx b/src/content/docs/enterprise/security-and-compliance/security-overview.mdx index 82febd95..efb12f45 100644 --- a/src/content/docs/enterprise/security-and-compliance/security-overview.mdx +++ b/src/content/docs/enterprise/security-and-compliance/security-overview.mdx @@ -173,14 +173,11 @@ Route agent inference through your own cloud infrastructure for complete control See [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/) for configuration details. -### Docker Sandboxes +### Local Sandboxes -Isolate agent execution in containerized environments: +Run agent conversations and terminal commands in an isolated Docker container on the developer's machine, so the agent can't see or write to the host home directory or current repository by default. Sandboxes are ephemeral — each new sandbox starts in a fresh container with an empty workspace. -* **Process isolation** - Agents run in separate Docker containers, isolated from your host system -* **Resource limits** - Configure CPU, memory, and disk quotas per sandbox -* **Network controls** - Restrict outbound network access from sandboxes -* **Ephemeral environments** - Sandboxes are destroyed after use, leaving no trace +See [Local Sandboxes](/agent-platform/local-agents/local-sandboxes/) for details and setup. ### Agent permissions diff --git a/src/content/docs/terminal/settings/all-settings.mdx b/src/content/docs/terminal/settings/all-settings.mdx index b8bdbbfa..01382ff0 100644 --- a/src/content/docs/terminal/settings/all-settings.mdx +++ b/src/content/docs/terminal/settings/all-settings.mdx @@ -15,7 +15,7 @@ Top-level settings that control Warp's startup behavior, session management, and **Section**: `[general]` -* `default_session_mode` — The default mode for new terminal sessions. Type: string. Default: `"terminal"`. Options: `"terminal"`, `"agent"`, `"cloud_agent"`, `"tab_config"`, `"docker_sandbox"`. +* `default_session_mode` — The default mode for new terminal sessions. Type: string. Default: `"terminal"`. Options: `"terminal"`, `"agent"`, `"cloud_agent"`, `"tab_config"`, `"docker_sandbox"` (see [Local Sandboxes](/agent-platform/local-agents/local-sandboxes/)). * `default_tab_config_path` — Path to the tab config used when `default_session_mode` is `"tab_config"`. Type: string. Default: `""`. * `link_tooltip` — Whether to show a tooltip when hovering over links. Type: boolean. Default: `true`. * `login_item` — Whether to launch Warp automatically when you log in. Type: boolean. Default: `true`. diff --git a/src/sidebar.ts b/src/sidebar.ts index c2e510a8..85cf7d77 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -264,6 +264,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'agent-platform/capabilities/agent-notifications', label: 'Agent notifications' }, { slug: 'agent-platform/capabilities/full-terminal-use', label: 'Full terminal use' }, { slug: 'agent-platform/capabilities/computer-use', label: 'Computer use' }, + { slug: 'agent-platform/local-agents/local-sandboxes', label: 'Local Sandboxes' }, 'agent-platform/capabilities/codebase-context', { slug: 'agent-platform/capabilities/agent-profiles-permissions', label: 'Profiles & permissions' }, { slug: 'agent-platform/capabilities/web-search', label: 'Web search' }, From 1b99eb97eea2dcf3384ac5bfc814716fcfc33777 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Sun, 17 May 2026 18:09:05 -0700 Subject: [PATCH 2/2] docs(local-sandboxes): address PR #89 review feedback - local-sandboxes.mdx: drop bare 'ephemeral' framing in the opening paragraph; clarify that closing the pane ends the session but the stopped container persists on disk. Tighten the rollout note. Reword the 'unfamiliar repo' bullet so it doesn't imply Warp mounts the user's checkout. Collapse the two prerequisites into a single Docker prerequisite plus an actionable PATH troubleshooting note (no internals leak). Switch the '+' UI label from backticks to bold per the docs style guide. Consolidate the 'Bash shell' bullets and rewrite the 'Cloned repositories, when you add them' bullet to read cleaner. Reword the cleanup limitation to warn that 'docker container prune' removes *all* stopped containers, and recommend 'docker ps -a' + 'docker rm ' for surgical removal. - security-overview.mdx: replace 'Sandboxes are ephemeral' with copy that distinguishes fresh-launch behavior from stopped-container on-disk persistence so the security overview no longer overstates the data-retention guarantee. Addresses bot review on PR #89: - 3255792999 (security-overview 'ephemeral' overstatement) - 3255793000 ('docker container prune' scope warning) - 3255793001 (non-actionable helper PATH prerequisite) Co-Authored-By: Oz --- .../local-agents/local-sandboxes.mdx | 17 +++++++++-------- .../security-overview.mdx | 2 +- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/src/content/docs/agent-platform/local-agents/local-sandboxes.mdx b/src/content/docs/agent-platform/local-agents/local-sandboxes.mdx index 05803da3..2b04c05c 100644 --- a/src/content/docs/agent-platform/local-agents/local-sandboxes.mdx +++ b/src/content/docs/agent-platform/local-agents/local-sandboxes.mdx @@ -9,10 +9,10 @@ sidebar: A **Local Sandbox** is an isolated shell session that runs in a container on your local machine, so the agent (and any commands you run alongside it) can't see or write to your home directory or current repository by default. Use it to try unfamiliar tooling, run risky setup steps, or hand a long-running task to an agent without giving it access to your personal files. -Local Sandboxes are powered by Docker. Each sandbox is a fresh, ephemeral container; closing the pane ends the session. +Local Sandboxes are powered by Docker. Each launch starts in a fresh container with an empty workspace. Closing the pane ends the sandbox session, but the stopped container remains on disk until you remove it — see [Limitations](#limitations). :::note -Local Sandboxes are rolling out gradually. The entry points below may not be visible in every build yet. +The entry points below may not be visible to every user yet. ::: ## When to use a local sandbox @@ -20,7 +20,7 @@ Local Sandboxes are rolling out gradually. The entry points below may not be vis Reach for a Local Sandbox when you want isolation without leaving your machine: * **Try risky commands** - Run setup scripts, package installs, or experimental tooling without polluting your host environment. -* **Hand a task to an agent against an unfamiliar repo** - Give the agent room to clone, build, and run code without exposing your existing checkout. +* **Give an agent a clean container** - Let the agent clone, build, and run code in a fresh workspace, instead of touching your existing checkout. * **Test a clean toolchain** - Reproduce a "fresh box" so you can see what your project actually needs to bootstrap. * **Isolate experiments from your local working tree** - Keep half-finished work and uncommitted changes from leaking into the next thing you try. @@ -38,7 +38,8 @@ Each Local Sandbox is a fresh Docker container with a bash shell: ## Prerequisites * **Docker installed and running locally** - Warp uses Docker to create the sandbox container. Install Docker Desktop (or your distribution's Docker engine) and confirm `docker info` succeeds before launching a sandbox. -* **Warp's local sandbox helper available on `PATH`** - Warp invokes a bundled helper to drive the container lifecycle. The helper must be on the `PATH` that your interactive shell sees, not just the `PATH` your GUI launcher provides. If launching the sandbox fails with a "binary not found" error, open a regular Warp terminal and confirm the helper resolves there before retrying. + +Warp resolves the container tooling it needs from your interactive shell `PATH`. If launching a sandbox fails with a "binary not found" error, confirm Docker is running and relaunch Warp from a terminal so it inherits your full `PATH`. ## Starting a local sandbox @@ -50,7 +51,7 @@ In any local terminal session, type `/docker-sandbox` and submit. Warp opens a n ### New-session menu -Open the new-session dropdown (the `+` button next to the tab bar) and choose **Local Docker Sandbox**. Warp opens a new tab running the sandbox. +Open the new-session dropdown (the **+** button next to the tab bar) and choose **Local Docker Sandbox**. Warp opens a new tab running the sandbox. ### Default for new sessions @@ -65,9 +66,9 @@ The same setting is also available in the Warp app under **Settings** > **Featur ## What's available inside the sandbox -* **Bash shell** - A standard bash environment is the starting point. Install whatever tooling you need for the task at hand; changes stay inside the container. * **Agent conversations** - Start an agent conversation inside the sandbox the same way you would in any other terminal session. The agent's actions are scoped to the container. -* **Cloned repositories, when you add them** - The sandbox doesn't mount your local checkout. Clone any code you want to work with (for example, `git clone `) from inside the sandbox. +* **Whatever you install** - Run `apt-get`, `npm install`, `pip install`, or any other tooling from the bash shell. Changes stay inside the container. +* **Code you clone in** - The sandbox doesn't mount your local checkout. Use `git clone ` (or copy files in via `docker cp`) to bring code into the sandbox. ## Limitations @@ -76,7 +77,7 @@ Local Sandboxes have a few constraints to be aware of today: * **Local sessions only** - Local Sandboxes aren't available inside remote SSH sessions or in Warp's web client. * **Empty workspace by default** - The sandbox starts in an empty directory. Your local repo isn't mounted in; clone it (or any other code) from inside the sandbox if you need it there. * **CLI agent plugin install uses the manual flow** - Third-party CLI agent plugin installers run against the host shell, not the container. Inside a sandbox session, Warp shows the manual install instructions so you can run them inside the container yourself. -* **No automatic cleanup on close** - Closing a sandbox pane stops the session but doesn't remove the underlying container. Stopped sandbox containers stay on disk until you remove them; run `docker container prune` if you want to free up the space. +* **No automatic cleanup on close** - Closing a sandbox pane stops the session but doesn't remove the underlying container. Stopped sandbox containers stay on disk until you remove them. Use `docker ps -a` to list stopped containers and `docker rm ` to remove specific ones. `docker container prune` also works, but it removes **all** stopped containers on your machine, not only sandbox containers — use it only if you're comfortable with that scope. ## Related pages diff --git a/src/content/docs/enterprise/security-and-compliance/security-overview.mdx b/src/content/docs/enterprise/security-and-compliance/security-overview.mdx index efb12f45..48599966 100644 --- a/src/content/docs/enterprise/security-and-compliance/security-overview.mdx +++ b/src/content/docs/enterprise/security-and-compliance/security-overview.mdx @@ -175,7 +175,7 @@ See [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/) fo ### Local Sandboxes -Run agent conversations and terminal commands in an isolated Docker container on the developer's machine, so the agent can't see or write to the host home directory or current repository by default. Sandboxes are ephemeral — each new sandbox starts in a fresh container with an empty workspace. +Run agent conversations and terminal commands in an isolated Docker container on the developer's machine, so the agent can't see or write to the host home directory or current repository by default. Each sandbox launches in a fresh container with an empty workspace; stopped containers persist on disk until they're removed via Docker. See [Local Sandboxes](/agent-platform/local-agents/local-sandboxes/) for details and setup.