Agent Upstart

Cool things people are building with agents — and practical help getting the most out of them.

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:

Then confirm what the session actually enforces with:

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:

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:

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.

  1. 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.
  2. 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.
  3. 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.
  4. Try a credential operation with credentials off. With Git and gh credentials turned off, a push or a gh pr create from 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.
  5. 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 policy again. 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

Limits

Related playbooks

Sources

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