sandboxes: document --clone and consolidate workspace isolation

[ndeloof]

Summary

Alternative to #25007 — written against the post-rename CLI (--branch[=NAME] → --clone, boolean) from docker/sandboxes#3055.

Replaces the entire "Branch mode" documentation with "Clone mode":

• --clone instead of --branch=NAME / --branch=auto
• No more host-side branch creation: the user/agent decides whether to git checkout -b ... inside the sandbox
• No more .sbx/<name>-worktrees/... directory (clone lives on the container's overlay filesystem)
• Clone mode is fixed at create time (no run-time branch switching)
• Forge remotes (origin, upstream, …) are propagated from host into the in-container clone so the agent can git push origin against the user's fork as on the host

Keeps the security framing from #25007:

• Source-repository isolation section in security/isolation.md (same diagram and guarantees, terminology updated)
• "Clone mode" section in security/workspace.md calls out that this IS a security boundary, not just a workflow convenience
• Five-layer model in security/_index.md (adds source-repository)

Adds a Cleanup warning in usage.md — sbx rm drops in-container commits that haven't been fetched (git fetch sandbox-<name>) or pushed; the CLI surfaces a runtime warning before deletion.

Files changed

File	Change
usage.md	Branch mode → Clone mode (rewrite), drop .sbx/ worktree section, add propagated remotes, add cleanup warning
security/isolation.md	Add Source-repository isolation section
security/workspace.md	Branch mode stub → Clone mode (boundary)
security/_index.md	4-layer model → 5-layer (source-repository)

Test plan

• Deploy preview renders the updated Git workflow section
• Anchors #clone-mode and #source-repository-isolation resolve
• vale passes (verified locally — zero errors in changed files)
• No remaining --branch references on the sandbox pages

Migration note

Callers that scripted sbx create --branch=feature/x now pass --clone and instruct the agent to create the branch (e.g. via git checkout -b feature/x).

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for docsdocker ready!

Name	Link
🔨 Latest commit	11252fe
🔍 Latest deploy log	https://app.netlify.com/projects/docsdocker/deploys/6a16f2991aedc70008b1e8c0
😎 Deploy Preview	https://deploy-preview-25140--docsdocker.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[docker-agent]

Assessment: 🟢 APPROVE

The PR cleanly documents the --clone mode for Docker Sandboxes, replacing the previous --branch/worktree approach. The changes across all four files are technically accurate, internally consistent, and well-structured.

What was reviewed:

• security/_index.md — 4-layer → 5-layer model (source-repository added)
• security/isolation.md — New "Source-repository isolation" section with diagram
• security/workspace.md — Branch mode stub → Clone mode (security boundary)
• usage.md — Clone mode rewrite, propagated remotes, cleanup warning

No high or medium issues found. Commands, flags (--clone), front matter fields, and cross-references all appear correct. The cleanup > [!WARNING] callout for sbx rm dropping uncommitted in-container commits is accurate and appropriately prominent.

[dvdksn]

I don't know what claude was thinking with this diagram but I guess I'll open inkscape and try to create something legible to replace this.

[ndeloof]

Do we have support for mermaid on docker/docs ?

[dvdksn]

I don't think so atm, but simple to add 👍

[dvdksn]

I'll add it in a separate PR

[dvdksn]

if you lgtm this one and rebase we can add a mermaid diagram here: #25178

[ndeloof]

Done — replaced the ASCII diagram with a ```mermaid flowchart (commit f092685). It renders once the codeblock hook from #25178 lands; validated the syntax against mermaid 11.15.0 in the meantime.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Documentation update replacing the previous --branch (worktree-based) Git workflow with a new --clone mode for Docker Sandboxes, where agents work on a private in-VM Git clone that's exposed as a remote on the host. Also consolidates the standalone "Workspace trust" page into a new "Workspace isolation" section within the existing isolation layers doc.

Changes:

• Replaces --branch/branch mode documentation with --clone/clone mode across usage, security, and getting-started pages.
• Adds a new "Workspace isolation" layer (now five layers total) to the isolation doc and deletes the separate workspace.md page, updating all cross-references.
• Adds a Claude Code "Agents view" section illustrating the parallel subagents + clone mode workflow.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
content/manuals/ai/sandboxes/usage.md	Rewrites Git workflow section: removes branch mode, adds clone mode with fetch/push/parallel-branch workflows and restrictions.
content/manuals/ai/sandboxes/security/workspace.md	Deletes the standalone Workspace trust page (content folded into isolation.md).
content/manuals/ai/sandboxes/security/isolation.md	Adds Workspace isolation layer (direct vs clone), Mermaid diagrams, and enforcement details.
content/manuals/ai/sandboxes/security/defaults.md	Updates link from workspace.md to the new isolation anchor.
content/manuals/ai/sandboxes/security/_index.md	Updates security overview to mention five layers, clone mode, and removes Workspace trust link.
content/manuals/ai/sandboxes/get-started.md	Replaces Workspace trust link with Workspace isolation reference.
content/manuals/ai/sandboxes/agents/claude-code.md	Adds Agents view section combining subagents with clone mode.
content/manuals/ai/sandboxes/_index.md	Removes "workspace trust" from security blurb.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[docker-agent]

Assessment: 🟡 NEEDS ATTENTION

1 high-severity issue (missing redirect) and 2 medium-severity style violations found in the added lines.

[docker-agent]

[HIGH] Missing redirect alias for deleted workspace.md page — will cause 404

security/workspace.md is deleted in this PR but no aliases: entry was added to isolation.md (or any other page) to redirect the old URL.

The old URL /manuals/ai/sandboxes/security/workspace/ will return a 404 after merging. Any existing bookmarks, external links, or search engine results pointing to that page will break.

Fix: Add an aliases: entry to the front matter of isolation.md (or whichever page absorbs the content):

---
title: Isolation layers
weight: 10
aliases:
  - /manuals/ai/sandboxes/security/workspace/
description: ...

[docker-agent]

[MEDIUM] Bold used for emphasis, not for UI elements — violates Docker style guide

The two bold sentence-starters here (**Workspace changes are live on your host in direct mode.** and **Default allowed domains include broad wildcards.**) use bold for emphasis, not to label UI elements.

Docker's STYLE.md is explicit: "Use bold only for UI elements (buttons, menus, field labels). Never use bold for emphasis, product names, or feature names."

Fix: Remove the bold and rely on sentence structure for emphasis, or promote these to ### subheadings if the content warrants it:

Workspace changes are live on your host in direct mode. With the default
direct mount...

[docker-agent]

[MEDIUM] Bold used for technical terms in list items — violates Docker style guide

The list items here use the **Term** description pattern (e.g., **Git hooks**, **CI configuration**, **Build files**, **IDE configuration**) with bold for technical term emphasis, not for UI element names.

Docker's STYLE.md explicitly calls out this pattern as bad practice:

• "Don't use 'Bold: format' for subsection labels"
• "Avoid marketing-style list formatting: Don't use 'Term - Description' format"
• "Use bold only for UI elements"

In-line bold is also used for **do not appear in \git diff` output**`, which is emphasis, not a UI label.

Fix: Remove the bold and use plain text for the terms:

- Git hooks (`.git/hooks/`) run on commit, push, and other Git actions.
  These are inside `.git/` and do not appear in `git diff` output —
  check them separately with `ls -la .git/hooks/`.
- CI configuration (`.github/workflows/`, `.gitlab-ci.yml`) runs on push.

[dvdksn]

The cleanup WARNING under Sandbox lifecycle and the Git remote in usage.md needs an update for the new survivability behavior. With git fetch sandbox-<name> mirroring into refs/sandboxes/<name>/*, fetched branches survive sbx rm, so the current warning ("Any commits you haven't fetched … or pushed to an upstream remote are lost") overstates the risk — only commits that were never fetched are actually lost.

The section should also surface the recovery path: git branch <local-name> refs/sandboxes/<name>/<branch> after sbx rm to restore a deleted sandbox's branch.

[docker-agent]

⏱️ PR Review Timed Out — The review agent hit the 1800 s time limit before completing. This usually happens on large or complex diffs. You can re-trigger with /review — if it times out again, consider splitting the PR into smaller pieces.