Playbooks · Coding tasks
Set Copilot's local sandbox boundary first
Written November 2, 2026
Local sandboxing is generally available in the Copilot CLI, app, and VS Code. Set the file, network, and credential policy before the agent runs a command.
What changed
On 7 October 2026, GitHub made local sandboxing for Copilot generally available in three places: the Copilot CLI, the Copilot app, and VS Code sessions using Agent Host, according to the changelog entry. Local sandboxes give Copilot's tools and commands a boundary on your own machine: restricted access to the filesystem, network, credentials and other system capabilities, under policies set by you or your organization. The sandbox is powered by Microsoft eXecution Container (MXC), which turns one sandbox policy into the native controls of Windows, macOS and Linux. It is included with Copilot at no additional cost, and the policy applies to tool execution whichever model Copilot is using.
The important fact about the default is that sandboxing is turned off by default. GitHub's documentation states it plainly: until you enable it, the shell commands Copilot runs execute directly on your machine with the same access as your user account — they can read, write and delete wherever you can, reach any network your machine can reach, and use your credentials without restriction. Enabling local sandboxing constrains that access to a policy you control. Set the policy before the first agent run on a repository you have not worked in, or before the first run that will touch credentials. After a credential has been visible to an agent-run command, setting the boundary does not take it back.
A sandbox boundary is not an approval system. Approvals decide whether an action runs automatically or needs your confirmation; sandboxing restricts what the file system and network resources a supported operation can reach. The two are separate layers, and turning one on does not turn on the other. If you want per-request approval as well, that is a separate decision, covered in the assisted-permissions page linked at the end. This page covers the boundary: what the agent's commands can reach, on each surface you use.
Check which surface you use
Local sandbox settings are configured separately in each surface. Enabling or configuring sandboxing in one does not change it in another, so check each surface you actually run Copilot in, and set the boundary in each. The three surfaces the changelog names are the Copilot CLI, the Copilot app, and VS Code sessions using Agent Host. The sections below take them in that order. If your organization manages Copilot settings, some or all of these settings may be controlled by enterprise managed settings, and a managed value cannot be weakened from your own settings. A setting labelled as managed in the interface is not yours to change; ask your administrator.
Copilot CLI: enable it, then tighten the defaults
In a Copilot CLI session, enable sandboxing with:
/sandbox enable
Then confirm what the session actually enforces with:
/sandbox status
The status command is the reliable check, because a saved preference to enable sandboxing is turned off for the current session if the host cannot support it, with a notice. The status line in the CLI also shows sandbox enabled when sandboxing is being used. To see the effective policy — the paths, network settings and capabilities that result once your settings, the automatic grants and any managed policy are combined — run /sandbox policy, optionally with a command after it, such as /sandbox policy npm install, to preview what that command would be allowed without running it. Open the full configuration with /sandbox, which has four tabs: General, Credentials, Filesystem and Network.
The defaults, as GitHub's guide and the configuration guide state them, are generous enough to keep ordinary development working, and that is the point to check:
- Filesystem. Sandboxed commands can write within the current working directory and temporary folders. In a Git repository, the repository's Git metadata is also writable, while the rest of the repository above the working directory is readable but not writable. Selected system and developer-tool locations are readable, and some build and package caches are writable. The rest of the machine is blocked unless you grant access. The Allow dev tool access setting is on by default: it grants read access to developer-tool configuration and caches, including package-manager registries and the tokens they store, plus write access to shared build caches. Turn it off if a task does not need those locations, and grant narrower paths explicitly instead.
- Network. Outbound internet access is on by default. Local network access is off by default. Add host rules to allow or deny specific hosts; once you add an allow rule, hosts that do not match it are blocked. Deny takes precedence over allow.
- Credentials. Authentication for Git and GitHub CLI (
gh) is on by default. Sandboxed commands receive placeholder credentials, and a local proxy supplies the real ones only to approved HTTPS destinations — forgh, onlygithub.com,api.github.comanduploads.github.com. Turn off either credential setting for a task that does not need to push, pull over HTTPS, or create a pull request. You can also mask additional environment variables, such as API tokens, so sandboxed tools receive placeholders and the proxy supplies the real value only to the hosts you name. Masking does not hide secrets in credential files, other environment variables, or remote MCP authentication. - Bypass. Allow sandbox bypass is on by default. When a command is blocked, Copilot can ask you to approve running it outside the sandbox. An approved bypass skips credential masking and the sandbox proxy: the command runs with its ordinary environment, which can contain real secret values. Turn bypass off if you want blocked commands to stay blocked, so the only way forward is to adjust the policy or take a different approach.
For a single session without changing saved settings, start the CLI with copilot --sandbox -p "prompt". The opposite flag, --no-sandbox, cannot override an enterprise policy that requires sandboxing. Platform requirements apply: on Linux, bubblewrap 0.5.0 or later and slirp4netns on your path; on Windows, Windows 11 version 25H2 with update KB5124010 or later, or version 26H1 with update KB5124006 or later, with support for the BaseContainer tier. On a host that cannot enforce the policy, the CLI reports the requirement instead of running the command with weaker restrictions.
Copilot app: set it per repository
In the Copilot app, sandboxing is configured per repository or local folder, and it applies to local repository and working tree sessions. It does not apply to cloud sandbox sessions or sessions that run on a remote host. To enable it for new local sessions in a repository or folder, open Settings in the app sidebar, select the repository or folder under Repositories, and turn on Sandbox new sessions under Sandbox. The setting applies to new sessions; it does not change a session that is already running. Changes to filesystem, network and credential settings likewise apply to new sessions or when an existing session restarts.
The app exposes a subset of the CLI controls. In repository settings you can configure: filesystem access (additional read/write, additional read-only, and denied folders, with a more-specific denied folder winning over a broader granted parent); network access (outbound internet and local network, both on by default in the app — unlike the CLI, where local network is off by default); and credentials (whether Git credentials and GitHub CLI credentials are available inside the sandbox, both on by default). Start from the default policy for most repositories — it allows the access needed for installing dependencies, connecting to a local development server, pushing a branch and creating a pull request — and add restrictions where the repository sits next to sensitive folders, does not need network access, or should not use your credentials. On Windows, a denied path that the host cannot guarantee fails the command instead of running it with the path accessible.
VS Code: turn the setting on where the session runs
In VS Code, sandboxing for Copilot harness sessions is controlled by the chat.agent.sandbox.enabled setting, which accepts on or off and defaults to off. Configure it on the machine where the session runs its commands — for a remote session, the remote machine's settings and platform decide. In settings JSON:
{ "chat.agent.sandbox.enabled": "on" }
Start a new Copilot harness session after turning it on, then inspect the effective policy with /sandbox policy in the session. The settings, as the VS Code documentation lists them, mirror the CLI's dimensions under different names: chat.agent.sandbox.network.allowNetwork defaults to true, so turning sandboxing on does not block outbound network access by default — configure network access separately if outbound connections must be restricted. chat.agent.sandbox.network.allowLocalNetwork defaults to false. chat.agent.sandbox.credentials.authenticategit and chat.agent.sandbox.credentials.authenticategh both default to true. chat.agent.sandbox.fileSystem.allowDevToolAccess defaults to true and grants read access to tool directories, toolchain directories and developer-tool configuration and caches, including registry tokens. chat.agent.sandbox.allowUnsandboxedCommands defaults to true, permitting requests to run outside the sandbox after confirmation. Set each one deliberately for the task, rather than leaving every default in place.
Two VS Code behaviours are worth knowing before relying on the boundary there. First, sandboxing is independent of the permission level: it continues to restrict processes when you select Allow all. Second, the settings apply to Copilot harness sessions that use the default tools in the shared runtime; the managed-server controls cover servers started or managed by Agent Host, the process that runs the session, and do not cover servers you start independently. Platform prerequisites are macOS 15 or later with Seatbelt, glibc-based Linux or WSL2 with bubblewrap 0.5.0 or later plus slirp4netns and compatible iptables tools, and Windows 11 with BaseContainer and the required updates. If an operating-system dependency is unavailable, the command does not silently run without the sandbox.
Run one command that should be denied
Before trusting the boundary on real work, check it with a command that should fail. Use a throwaway target, not a real credential or a real project file.
- Preview the policy first. Run
/sandbox policy(CLI or VS Code session) and read the effective paths and network settings. If the policy shows a path or host as allowed that you meant to deny, fix the setting before running anything. - Try a read outside the working directory. Ask Copilot to read a file in a folder you denied, or in a folder you never granted. The command should be blocked by the sandbox. Note whether the denial names the sandbox or fails some other way: a failure for another reason is not evidence the boundary held.
- Try a network connection you denied. If you added a deny rule for a host, ask Copilot to fetch from it. The connection should be refused. On Windows, remember that proxying and host rules rely on programs honouring the proxy settings, so a program that ignores them can connect directly — the docs state this limit plainly, and it is a reason to check the result rather than assume the rule held.
- Try a credential operation with credentials off. With Git and
ghcredentials turned off, a push or agh pr createfrom inside the sandbox should not succeed. If it does, credentials are still reaching the sandbox through some other route, and the boundary is not what the settings say it is. - Grant only what the task needs, then re-check. If a legitimate command is blocked, add the narrowest grant that lets it run — one path, one host — and run
/sandbox policyagain. Do not answer a blocked command with a bypass approval unless you have read what broader access the retry requests: an approved bypass runs outside the sandbox with real secret values in the environment.
What can go wrong
- Setting the boundary in one surface and using another. CLI, app and VS Code settings are separate. A boundary set in the CLI does not fence an app session, and neither fences a VS Code session.
- Leaving every default on. The defaults keep builds working: outbound internet open, dev-tool access on, Git and
ghcredentials on, bypass on. A boundary left at defaults stops a command rewriting your home directory. It does not stop it reading registry tokens or reaching any host on the internet. - Approving a bypass without reading it. A bypass runs the command outside the sandbox, with credential masking and the proxy skipped. Approving it for one blocked command is a decision to run that command unsandboxed, not a fix to the policy.
- Changing settings mid-session and expecting them to apply. In the app, policy changes apply to new sessions or on restart. In the CLI, a session opened before
/sandbox enableneeds restarting or its own/sandbox enable. The saved setting and the running session are not the same thing;/sandbox statussays what the running session enforces. - Assuming the sandbox is a virtual machine. GitHub's documentation places local sandboxing at the lighter-weight end of the isolation spectrum: it restricts what a process can read, write and reach, but does not run commands inside a separate virtual machine or container. It does not replace the isolation of cloud sessions or dev containers for work that needs it.
Limits
- This page states the policy dimensions and defaults as GitHub's documentation states them. It does not report a denied-command test: the check above is written for the reader to run, in their own sessions, on their own machine.
- The CLI's built-in file tools run in the CLI process itself, which is not sandboxed. They check the sandbox policy in code, on a best-effort basis, rather than being constrained by the operating-system sandbox. Remote MCP servers are never sandboxed. Local MCP and language servers are sandboxed by default where the surface supports it.
- On Windows, host rules and proxying rely on programs honouring the proxy settings, and credential masking needs a Windows version that supports host loopback plus local network turned on. On Linux, sandboxed processes cannot connect directly to servers on the computer's localhost; the local network setting still applies through the built-in local proxy and to in-process operations.
- Cloud sandbox sessions are a different thing from local sandboxing: they run remotely in an isolated Linux environment hosted by GitHub and are billed based on usage. The settings on this page do not govern them.
Related playbooks
- Copilot CLI 1.0.109: CIDR sandbox rules
- Check your Codex and Claude Code config for relay tampering: base URL, sandbox, and credentials you did not set
- Run Copilot as the agent in JetBrains Air
- Foundry Local runs Qwen3.8-27B on your GPU
Sources
- https://github.blog/changelog/2026-10-07-local-sandboxing-for-github-copilot-now-generally-available/
- https://docs.github.com/copilot/concepts/security-governance-and-network-settings/about-cloud-and-local-sandboxes?utm_source=changelog-cta-cloud-local-sandbox-documentation&utm_medium=changelog&utm_campaign=oct-7-event-oct-2026
- https://docs.github.com/en/copilot/how-tos/cloud-and-local-sandboxes/configuring-local-sandbox-settings
- https://docs.github.com/en/copilot/how-tos/cloud-and-local-sandboxes/using-local-sandboxing
- https://code.visualstudio.com/docs/agents/run/agent-sandboxing
Back to: Coding playbooks hub · Also: Decide whether Copilot's assisted permissions should approve anything for you · Check your Codex and Claude Code config for relay tampering: base URL, sandbox, and credentials you did not set · Run a reasoning task on a schedule with GitHub Agentic Workflows: one Markdown file, one reviewed pull request