docs(local-sandboxes): add Local Sandboxes feature page

[hongyi-chen]

Summary

Adds documentation for Local Sandboxes — an isolated, container-based local terminal session that lets users (and agents) run commands without exposing the host home directory or current repo by default. The feature surfaces in the new-session dropdown, via the /docker-sandbox slash command, and as a default_session_mode value in settings.toml, but had no end-user documentation today.

The page is named Local Sandboxes (powered by Docker) per direction. Docker is mentioned briefly as the underlying isolation tech, not as the feature name.

New page

• src/content/docs/agent-platform/local-agents/local-sandboxes.mdx — combined feature doc covering: what a local sandbox is, when to use one, how they work, prerequisites, three launch surfaces (slash command, new-session menu, default session mode), what is available inside the sandbox, and current limitations. Includes a single :::note flagging that the feature is rolling out gradually.

Cross-link updates

• enterprise/security-and-compliance/security-overview.mdx — renamed the existing "Docker Sandboxes" subsection to Local Sandboxes, linked to the new page, and trimmed aspirational bullets (CPU/memory/disk quotas, network controls) that are not actually shipping today.
• terminal/settings/all-settings.mdx — added an inline link from the "docker_sandbox" value in the default_session_mode bullet to the new page so users discovering the option from settings can find context.
• src/sidebar.ts — registered the new page under Warp Agents > Capabilities (next to Computer use, which is the cloud analog).

What was deliberately not exposed

Researched warp-internal to ground the page; took care to avoid leaking implementation details that should stay private:

• Internal feature-flag names, internal type/module names, telemetry event names.
• The hardcoded environment ID used today for sandbox environment lookup.
• Host-side cache-directory path layout and container naming prefix.
• The bundled sandbox helper binary name (referred to generically as "Warp's local sandbox helper").

Validation

• Style lint (header case, frontmatter, callouts, product casing, Oz terms, UI backticks) — clean on changed files.
• python3 .agents/skills/check_for_broken_links/check_links.py --internal-only — 0 broken (318 files, 2398 internal links).
• npm run build — 320 pages built successfully (sidebar compiles, new page renders).

Open follow-ups (not part of this PR)

• The in-app menu currently says Local Docker Sandbox and the slash command is /docker-sandbox. The page documents the actual UI strings; if you want me to file a follow-up to rename the UI to Local Sandbox for full alignment, I can do that as a separate task.
• The lint script's PROPER_FEATURE_NAMES list does not yet include "Local Sandboxes"; I worked around it by lowercasing H2 headers ("How local sandboxes work") rather than modifying the lint config in scope.

Conversation: https://staging.warp.dev/conversation/45a1df29-6318-4447-9473-284b3858554a
Plan: https://staging.warp.dev/drive/notebook/UCzVNBib8GZEeCHhjeVD7L

Co-Authored-By: Oz oz-agent@warp.dev

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	May 18, 2026 1:11am

[oz-for-oss]

@hongyi-chen

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[oz-for-oss]

Overview

This PR adds a new Local Sandboxes docs page and links it from security, settings, and sidebar surfaces. The structure is mostly coherent, but the security and cleanup wording needs tightening before merge because it can overstate container ephemerality and point users at a broad destructive Docker cleanup command.

Concerns

• The security overview calls sandboxes ephemeral even though the new feature page says stopped sandbox containers remain on disk until the user removes them.
• The cleanup guidance recommends docker container prune without warning that it removes all stopped Docker containers, not only Warp-created sandbox containers.
• The helper PATH prerequisite asks users to verify an unnamed helper, which makes the troubleshooting step hard to follow.

Security

• Avoid describing Local Sandboxes as ephemeral without the stopped-container persistence caveat; users may rely on that wording for sensitive-data handling decisions.

Verdict

Found: 0 critical, 2 important, 1 suggestions

Request changes

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[oz-for-oss]

⚠️ [IMPORTANT] [SECURITY] The feature page says stopped sandbox containers stay on disk until users remove them, so ephemeral overstates the data-retention guarantee here. Say each launch starts from a fresh container and mention stopped containers can persist until Docker cleanup.

[hongyi-chen]

Fixed in 1b99eb9. The Local Sandboxes subsection no longer claims sandboxes are ephemeral. New copy: "Each sandbox launches in a fresh container with an empty workspace; stopped containers persist on disk until they're removed via Docker." This aligns the security overview with the feature page's cleanup limitation.

[oz-for-oss]

⚠️ [IMPORTANT] docker container prune removes all stopped Docker containers, not just Warp sandbox containers. Warn about that scope or point users to Docker's per-container removal flow before recommending it for cleanup.

[hongyi-chen]

Fixed in 1b99eb9. The cleanup bullet now recommends docker ps -a + docker rm <container> for surgical removal, and explicitly warns that docker container prune "removes all stopped containers on your machine, not only sandbox containers — use it only if you're comfortable with that scope."

[oz-for-oss]

💡 [SUGGESTION] This prerequisite asks users to confirm a helper resolves but intentionally does not name the helper, so the diagnostic is not actionable. Either name the command users should check or rephrase this as a generic troubleshooting step with concrete remediation.

[hongyi-chen]

Fixed in 1b99eb9. The non-actionable "confirm the helper resolves" step is gone. Prerequisites are now a single Docker line, followed by a short troubleshooting note that says: "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." That gives the user a concrete remediation without needing us to name the bundled helper.

[hongyi-chen]

Pushed 1b99eb9 to address the review. Summary:

Bot comments addressed:

• security-overview.mdx no longer claims "Sandboxes are ephemeral"; it now distinguishes fresh-launch behavior from stopped-container on-disk persistence so the page stops over-promising.
• The cleanup limitation no longer recommends docker container prune as a blanket fix. It now points users to docker ps -a + docker rm <container> for surgical removal and explicitly warns that prune clears all stopped containers, not just sandbox ones.
• The non-actionable "confirm the helper resolves" prerequisite is gone. Prerequisites are now a single Docker line plus an actionable troubleshooting note about relaunching Warp from a terminal to inherit the full PATH.

Additional senior-copywriter polish in the same commit:

• Removed the bare "ephemeral" claim from the feature page's opening paragraph so it no longer contradicts the cleanup section.
• Tightened the rollout :::note and dropped the vague "rolling out gradually" framing.
• Reworked the "When to use" bullet that read as if Warp mounted the user's repo into the sandbox.
• Switched the + UI label from backticks to bold per the docs style guide.
• Consolidated the "Bash shell" overlap between sections and rewrote the awkward "Cloned repositories, when you add them" bullet.

Validation: style lint on changed files clean, internal link check clean (318 files / 2398 links), full npm run build passed (320 pages built).

[hongyi-chen]

Closing this PR for now. Will revisit Local Sandboxes documentation later.