@@ -11,7 +11,7 @@ category:
 ---
 
 > [!NOTE]
-> {% data reusables.cli.public-preview-sandbox %}
+> {% data reusables.cli.public-preview-cloud-sandbox %}
 
 ## How sandbox usage is measured
 
 
@@ -13,28 +13,23 @@ docsTeamMetrics:
   - copilot-cli
 ---
 
-> [!NOTE]
-> {% data reusables.cli.public-preview-local-sandbox %}
-
-{% data reusables.cli.sandbox-on-windows %}
-
 ## Introduction
 
 When you enable local sandboxing, {% data variables.copilot.copilot_cli_short %} runs the commands it invokes on your behalf inside an operating-system sandbox. The sandbox enforces a **filesystem policy**: a set of rules that decide which paths a sandboxed process or operation can read, which it can write, and which it cannot touch at all.
 
 Most of this policy is assembled automatically, so that everyday commands keep working without setup. This article explains how {% data variables.product.prodname_copilot_short %} arrives at the policy, and how to check the access it grants in a particular directory.
 
-For an overview of local sandboxing, including how to turn it on and off, see [AUTOTITLE](/copilot/concepts/about-cloud-and-local-sandboxes) and [AUTOTITLE](/copilot/how-tos/cloud-and-local-sandboxes/using-local-sandboxing).
+For an overview of local sandboxing, including how to turn it on and off, see [AUTOTITLE](/copilot/concepts/about-cloud-and-local-sandboxes) and [AUTOTITLE](/copilot/how-tos/cloud-and-local-sandboxes/using-local-sandboxing). For details of how to configure local sandboxing, see [AUTOTITLE](/copilot/how-tos/cloud-and-local-sandboxes/configuring-local-sandbox-settings).
 
 ## What the policy applies to
 
 The filesystem policy covers the work {% data variables.product.prodname_copilot_short %} does on your behalf, but it is enforced in different ways depending on the kind of work:
 
 * **Shell commands and built-in searches** run as sandboxed child processes, so the operating system enforces the policy directly. The `grep` and `glob` tools, for example, run ripgrep as a sandboxed child process.
-* **Local MCP and language server processes (LSP)** can also run inside the sandbox, so the operating system enforces the policy on them too.
+* **Local MCP and language server processes (LSP)** run inside the sandbox by default, so the operating system enforces the policy on them too. You can change this in the sandbox settings unless a managed policy requires it.
 * **Built-in file-reading and file-editing tools** run as part of {% data variables.copilot.copilot_cli_short %} itself rather than as a sandboxed child process. They check the same filesystem policy before reading or writing a file, but because the operating-system sandbox never sees these operations, the check is a software-only safeguard rather than one the operating system enforces.
-* **Remote MCP servers** run outside your machine, so there is no local child process to sandbox and the filesystem policy does not constrain them.
-* **Subagents** do not act directly; they orchestrate other tools. Whether the policy applies, and how, depends on the tool a subagent invokes.
+* **Remote MCP servers** run outside your machine, so there is no local child process to sandbox and the filesystem policy does not constrain them. Their connections from the CLI can still be restricted by the network policy when **Sandbox MCP servers** is enabled.
+* **Subagents** use other tools to do their work. Whether the policy applies, and how, depends on the tool a subagent invokes.
 
 A sandboxed **process** is therefore constrained by the operating system, while an in-process **operation** enforces the same policy in software—which is why this article refers to a sandboxed process or operation rather than only to commands.
 
@@ -53,7 +48,7 @@ Because access is denied unless granted, {% data variables.product.prodname_copi
 
 ## How the policy is built
 
-Before each sandboxed process starts, {% data variables.copilot.copilot_cli_short %} resolves the effective policy for that process using the current working directory, environment, settings, and automatic grants. This restricts the process to only the access that it needs, and means you don't have to manage these common locations yourself.
+Before each sandboxed process starts, {% data variables.copilot.copilot_cli_short %} resolves the effective policy for that process using the current working directory, environment, settings, and automatic grants. This includes common locations needed by tools, so you don't have to grant each one yourself. Tools can also receive access to selected session files and installed skills they need to use.
 
 ### Your working directory
 
@@ -72,7 +67,11 @@ On macOS, standard system locations are granted read-only permission so that com
 
 ### Package-manager caches
 
-To let installs and builds work inside the sandbox, {% data variables.product.prodname_copilot_short %} also grants access to the caches and registries used by common package managers and toolchains—read-only for most locations, and read/write for selected writable locations, such as build caches and package-manager dependency stores. In the `/sandbox policy` report, this appears as **dev-tool access**.
+When **Allow dev tool access** is enabled, {% data variables.product.prodname_copilot_short %} grants access to the caches and registries used by common package managers and toolchains. Most locations are read-only. Selected locations, such as npm's cache, build caches, and some dependency stores, are writable so installs and builds can work.
+
+These grants depend on the command and the tools detected in your project. They can follow cache locations you have configured outside the usual directories. Some granted configuration files contain registry credentials, and writable caches can be shared with commands you run outside the sandbox. Turn off **Allow dev tool access** if you prefer to grant these locations yourself.
+
+In the `/sandbox policy` report, the **Dev tools** section lists the detected tools and their paths. Selected writable caches are created when a command needs them, so they may not appear in the report before the first use.
 
 ### Git repositories
 
@@ -82,11 +81,11 @@ Because read access spans the whole repository, a sandboxed command can read fil
 
 ## When access rules overlap
 
-Because {% data variables.product.prodname_copilot_short %} grants several locations, and you can add your own, the rules can overlap. When they do, the **more specific path wins**. For example, if `/project` is writable but you mark `/project/secrets` read-only, everything in `/project` stays writable except `/project/secrets`. This is a useful way to protect a sensitive subfolder.
+Because {% data variables.product.prodname_copilot_short %} grants several locations, and you can add your own, the rules can overlap. When read-only and read/write grants overlap, the **more specific path wins**. For example, if `/project` is writable but you mark `/project/secrets` read-only, everything in `/project` stays writable except `/project/secrets`. Denied paths take precedence over both kinds of grant.
 
-Overlaps are also resolved in your favor when a convenience grant would otherwise get in the way. Consider a Python project with a local virtual environment (`.venv`) that appears on your `PATH`. Treating that directory as an ordinary read-only tool location would make it read-only—even though it sits inside your writable project—and a command such as `pip install` could then fail when it tried to update the environment. {% data variables.product.prodname_copilot_short %} resolves this for you: a grant it added automatically (such as a tool directory on `PATH`) gives way to a broader read/write grant that already covers it. So a project-local `.venv`, `node_modules/.bin`, or similar directory stays writable as part of your workspace.
+Discovered tool-directory grants give way to read/write access that already covers them. Consider a Python project with a local virtual environment (`.venv`) that appears on your `PATH`. Treating that directory as an ordinary read-only tool location would make it read-only—even though it sits inside your writable project—and a command such as `pip install` could then fail when it tried to update the environment. {% data variables.product.prodname_copilot_short %} leaves it writable as part of your workspace. Other read-only rules, including ones you configure yourself, are not discarded this way.
 
-Rules that **you** configure are always kept. If you mark a path read-only, or you deny it, that decision stands even when the same path would otherwise be discovered and granted automatically. This gives you a reliable way to protect a sensitive location—for example, denying a `.env` file so that no sandboxed command can read your secrets.
+Rules that **you** configure are not removed just because the same path was discovered automatically. You can use them to restrict access to a sensitive location, such as an existing `.env` file. Missing paths and symbolic links need additional care, as described in [Troubleshooting filesystem access](#troubleshooting-filesystem-access).
 
 ## Checking what the current policy allows
 
@@ -96,16 +95,38 @@ Because the policy is assembled for each directory and command, the simplest way
 /sandbox policy
 ```
 
-{% data variables.product.prodname_copilot_short %} prints the **effective** policy for your current directory: the read/write, read-only, and denied paths that a command launched from here would actually receive, together with the network access and dev-tool access in force. This is the resolved result after the automatic grants and your own settings have been combined and any overlaps resolved—not just a copy of your saved settings.
+{% data variables.product.prodname_copilot_short %} prints the **effective** policy for your current directory. Paths are grouped by source, such as **User-configured paths** and **Dev tools**, and by access level. The report also includes network settings and a **Capabilities** section covering settings such as bypass, MCP/LSP sandboxing, and authentication. This is the result after automatic grants, your settings, and managed restrictions have been combined—not just a copy of your saved settings.
+
+To inspect the developer-tool access for a particular command, add the command after `policy`. For example:
+
+```shell copy
+/sandbox policy npm install
+```
+
+This does not run `npm install`. It shows the tool access the command would receive. The preview creates no directories, including missing denied paths and tool caches.
 
 A few things to keep in mind when you read the report:
 
 * It reflects your **current directory**. Because grants are discovered per directory, the same settings can resolve to different paths depending on where you run.
-* If a path you configured does not exist on disk, it is left out of the policy and noted in a **Notes** section. This explains why a rule you added might appear to have no effect.
+* Check **Notes** for configured paths that could not be included. Missing read/write or read-only grants are omitted. On Linux, missing denied paths are omitted from this preview, but launch preparation creates them before applying the policy. The preview retains them on macOS and on Windows hosts that support denied paths.
 * If sandboxing is turned off, `/sandbox policy` tells you so instead of printing a policy, because no restrictions are in force.
 
 To check only whether sandboxing is currently on, use `/sandbox status`. For more about these commands, see [AUTOTITLE](/copilot/how-tos/cloud-and-local-sandboxes/using-local-sandboxing).
 
+## Troubleshooting filesystem access
+
+If a configured read/write or read-only path does not exist, create it outside the sandbox before starting the command again. A running child process keeps the policy it received at launch. Creating a path later does not add a missing grant to that process. Restart a long-running server if it needs the updated access.
+
+Before a sandboxed process starts, {% data variables.copilot.copilot_cli_short %} creates missing denied paths and their parent directories on your machine. This includes paths intended for files, so a missing `.env` becomes a directory. The directories remain after the process exits.
+
+If a denied path cannot be prepared, the process does not start. The read-only `/sandbox policy` preview does not perform this preparation, which is why missing denied paths are omitted there on Linux. For troubleshooting, see [AUTOTITLE](/copilot/how-tos/cloud-and-local-sandboxes/using-local-sandboxing#troubleshooting-blocked-paths-that-do-not-exist).
+
+A symbolic link inside an allowed directory does not guarantee access to a target outside that directory. If a denial message names such a target, inspect it and grant access only if intended. Adding a resolvable symbolic link itself through `/sandbox config` also adds its current target for read/write or read-only access. Handwritten path rules and automatically discovered developer-tool grants do not automatically add that target.
+
+Denied paths are handled differently from grants: the CLI resolves their written path and current target. On Linux, a denied symbolic link protects its target, but does not reliably prevent the link itself from being replaced. Prefer denying the actual sensitive directory rather than relying on a symbolic-link rule alone.
+
+For network failures, managed restrictions, and bypass choices, see [Troubleshooting blocked commands](/copilot/how-tos/cloud-and-local-sandboxes/using-local-sandboxing#troubleshooting-blocked-commands).
+
 ## Customizing the policy
 
 You can grant extra read/write or read-only paths, deny paths, and change other filesystem behavior, either from the `/sandbox config` dialog or in your settings file. After you make a change, run `/sandbox policy` to confirm the result. For step-by-step instructions, see [AUTOTITLE](/copilot/how-tos/cloud-and-local-sandboxes/configuring-local-sandbox-settings).
 
@@ -67,9 +67,6 @@ To use the CLI programmatically, include the `-p` or `--prompt` command-line opt
 
 ## Running {% data variables.copilot.copilot_cli_short %} commands in a sandbox
 
-> [!NOTE]
-> {% data reusables.cli.public-preview-sandbox %}
-
 To prevent {% data variables.product.prodname_copilot_short %} from modifying files you don't want it to touch, you can force agents to run commands within a local sandboxed environment. Alternatively, you can run an entire CLI session in an isolated environment in the cloud. For more information, see [AUTOTITLE](/copilot/concepts/about-cloud-and-local-sandboxes).
 
 ### Local sandboxing
@@ -78,6 +75,9 @@ You can enable local sandboxing inside a {% data variables.copilot.copilot_cli_s
 
 ### Cloud sandboxing
 
+> [!NOTE]
+> {% data reusables.cli.public-preview-cloud-sandbox %}
+
 You can start a {% data variables.copilot.copilot_cli_short %} session inside an isolated, cloud-hosted environment with cloud sandboxes. This is useful when you want to run code without affecting your local machine, keep a session's state between uses, continue a session from a different machine, or run multiple tasks in parallel. Cloud sandbox policies inherit from {% data variables.copilot.copilot_cloud_agent %} policies, so existing security controls like firewall rules extend to cloud sandboxes without additional setup.
 
 To start a cloud-backed session, run: