About local sandboxing for GitHub Copilot

Local sandboxes provide isolated execution environments that let Copilot safely interact with code, tools, filesystem, and network resources securely on your local machine.

In this article

Introduction

Copilot local sandboxes are the execution platform powering secure sandboxed experiences for GitHub Copilot CLI and the GitHub Copilot app. As Copilot takes more actions on your behalf—running tools, executing commands, and modifying files—sandboxing provides the isolation, portability, and policy controls needed to adopt agentic workflows safely.

Sandboxing is available in both GitHub Copilot CLI and the GitHub Copilot app, but the two surfaces expose it differently:

  • In Copilot CLI, you control local sandboxing with the commands and settings described in this article.
  • In the GitHub Copilot app, you can use local sandboxing for local repository and working tree sessions. Project settings define the default for new local sessions, and you can change sandboxing for an active local session. For more information, see Working with agent sessions in the GitHub Copilot app.

Local sandbox settings are configured separately in Copilot CLI and the GitHub Copilot app. Enabling or configuring local sandboxing in one surface does not change it in the other.

With sandboxing, you can choose where Copilot runs:

  • Local sandboxing: Run Copilot securely on your own machine. The commands that Copilot runs have restricted access to your filesystem, network, and system capabilities. You can use local sandboxing at no extra charge.
  • Cloud sandboxing: Run an entire Copilot session remotely, inside a fully isolated, ephemeral Linux environment hosted by GitHub. Cloud sandboxing is billed based on usage. For more information, see About cloud sandboxes for GitHub Copilot.

Local sandboxing

Local sandboxing lets Copilot run in a sandboxed environment directly on your machine, with restricted access to your filesystem, network connectivity, and system capabilities. You can configure local sandboxing in Copilot CLI or the GitHub Copilot app.

Local sandboxing is turned off by default. Until you enable it, the shell commands that 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 this access to a policy that you control.

How local sandboxing works

Local sandboxing is powered by Microsoft eXecution Container (MXC), a cross-platform technology that provides a common interface to the isolation mechanisms available on each operating system. Copilot CLI declares the sandbox policy it wants to enforce—which paths are readable or writable, whether network access is allowed, and so on—and MXC applies that policy using the appropriate isolation backend for your operating system.

Isolation technologies exist on a spectrum, from strong isolation such as full hypervisors or containers, to lighter-weight isolation such as OS-level process and filesystem containment. Local sandboxing currently sits at the lighter-weight end of this spectrum: it restricts what a process can read, write, and reach on the network, but it does not run your commands inside a separate virtual machine or container. If you want to evaluate whether this level of isolation meets your security requirements, see the microsoft/mxc repository for implementation details.

For more information, see Understanding filesystem policies for local sandboxing in GitHub Copilot CLI.

Enabling local sandboxing

To enable local sandboxing inside a Copilot CLI session, run:

Shell
/sandbox enable

After you enable local sandboxing, the commands and tools that an agent runs on your behalf run inside an operating-system-level sandbox that limits their access to your system. These include shell commands, file search, and, by default, any local MCP and language (LSP) servers. Copilot continues to use local sandboxing, including in future sessions, until you run /sandbox disable to disable it.

If enterprise managed settings require sandboxing, ordinary settings and startup options cannot turn it off. If the effective policy permits sandbox bypass, you can still disable sandboxing for the rest of the current session, either from a bypass permission prompt or by running /sandbox disable. This does not change the saved policy.

The CLI's built-in file tools—first-party commands that are part of the CLI, rather than shell commands like sed—run in-process in the CLI. Because the CLI itself is not sandboxed, the operating-system sandbox never sees the file operations these tools perform and cannot constrain them. Instead, the built-in tools are coded to check the sandbox policy themselves and honor your configured settings on a best-effort basis.

In the GitHub Copilot app, repository settings define the local sandboxing default for new local repository and working tree sessions. You can also change sandboxing for an active local session without changing the repository default.

For more information about enabling local sandboxing in Copilot CLI and the Copilot app, see Using local sandboxing.

Configuring local sandboxing

You can use the default local sandboxing behavior, or modify what Copilot can access. The available controls depend on the surface you use.

In Copilot CLI, you can control several dimensions of access:

  • Filesystem: Grant read-only or read/write access to specific paths, or deny paths.
  • Network: Control outbound internet access and local network access, or allow and deny specific hosts. The restrictions available depend on your operating system.
  • Credentials: Enable Git and GitHub CLI (gh) authentication, or mask additional environment variables. Sandboxed tools receive placeholders, and a local proxy supplies the real credentials only to approved HTTPS destinations.
  • Subprocesses: Choose whether local MCP servers and language servers also run inside the sandbox. Remote MCP servers are never sandboxed.
  • Keychain (macOS): Choose whether the system keychain is reachable from inside the sandbox.
  • Per-command exceptions: Allow or prevent individual commands from running outside the sandbox when they need broader access.

In the GitHub Copilot app, repository settings expose a subset of these controls:

  • Filesystem: Grant additional read-only or read/write access to specific paths, or deny paths.
  • Network: Allow or block outbound internet and local network access.
  • Credentials: Choose whether your Git and GitHub CLI credentials are available inside the sandbox.

The app can also ask you to approve an individual command to run outside the sandbox. You cannot configure whether bypass requests are allowed in the repository settings. For more information about configuring local sandboxing in the app or CLI, see Configuring local sandbox settings.

Cross-platform support

Local sandboxing is available on macOS, on Linux, and on recent Windows 11 builds. Each operating system uses a different isolation backend, so the requirements are different:

  • macOS uses the Seatbelt backend. Copilot CLI applies a process-scoped profile to each sandboxed command. Use macOS 15 (Sequoia) or later. Copilot CLI does not block an older macOS, but the backend is not tested there.
  • Linux uses the bubblewrap backend. Install bubblewrap 0.5.0 or later, and make sure bwrap is on your PATH. If /sandbox reports that your bwrap is too old, upgrade the package. When the sandbox policy permits outbound traffic, you must also have:
    • slirp4netns on your PATH.
    • unshare and nsenter from util-linux 2.35 or later, with --map-current-user and --keep-caps support.
    • iptables, ip6tables, and their restore binaries. Use the nf_tables backend. The legacy backend also operates, but only if you can write to /run/xtables.lock.
    • Access to /dev/net/tun.
  • Windows requires a recent Windows 11 update that supports sandboxing. Support for features such as denied paths, localhost connections, and proxying also depends on your Windows version. If your host cannot support a requested feature, Copilot CLI reports the requirement instead of running the command with weaker restrictions. See Windows update information for Copilot sandboxing.

Proxy support

In Copilot CLI, host rules and HTTP proxy settings use a built-in local proxy. Their enforcement differs by operating system:

  • macOS and Linux: The sandbox restricts outbound connections to the local proxy. Programs that ignore proxy settings cannot connect directly instead. The Linux requirements for outbound traffic listed in Cross-platform support also apply when you configure a proxy.
  • Windows: Proxying and host rules require a supported Windows version and Allow local network to be turned on. On Windows, the sandbox relies on programs honoring the proxy settings. As a result, these controls do not provide the same protection against direct connections as on macOS and Linux.

In the GitHub Copilot app, you can save denied paths in the repository settings. If the active BaseContainer capabilities cannot enforce a denied path, the sandboxed command fails instead of running with a weaker policy or without a sandbox.

On Linux, bubblewrap cannot control local network access independently for spawned processes, including shell commands and local MCP or LSP servers. The local network setting still applies to in-process operations, such as web requests and remote MCP connections, in both the CLI and the app.

If your host does not support local sandboxing

In Copilot CLI, a saved user preference to enable sandboxing is turned off for the current session if the host does not support it. A notice explains that shell commands and services will run without a sandbox. Your saved sandbox.enabled setting remains unchanged. Running /sandbox enable on an unsupported host is refused.

Enterprise settings can change this behavior. On an unsupported host, a server-managed request to enable sandboxing is declined unless effective managed settings also set sandbox.failIfUnavailable to true. Device-managed settings can require sandboxing even on an unsupported host. Commands and services that require sandboxing then fail rather than running without it. When effective managed settings set both sandbox.enabled and sandbox.failIfUnavailable to true, the CLI blocks model requests and tool execution for the session if it cannot enforce sandboxing. These requirements can come from server-managed settings, device-managed settings, or a combination of both.

For the GitHub Copilot app, on a host that does not support local sandboxing, a session configured to use local sandboxing may start normally, but shell commands and other sandboxed processes fail when Copilot attempts to launch them. The GitHub Copilot app preserves the saved preference, and the failed operation reports that sandboxing is not supported on the platform. Device-managed settings may require this fail-closed behavior and can block model and tool execution.

Enterprise policy enforcement

Enterprises can require local sandboxing and enforce its configuration through server-managed, MDM-managed, or file-based managed settings. See Getting started with enterprise-managed settings.

Authentication and access

Sandboxing uses your existing Copilot authentication. If you can sign in to Copilot CLI or the GitHub Copilot app and have access to Copilot, you don't need to configure separate authentication for the sandboxing options available in that surface. You don't need to configure a separate cloud provider, manage API keys, or set up infrastructure.

Billing

Local sandboxing is included in the standard GitHub Copilot seat at no additional cost.

Further reading