GitHub Copilot App Local Sandboxing: Setup and Safe Policies

As coding agents gain permission to edit files, install packages, run tests, and use developer credentials, approval dialogs are no longer a complete safety strategy. A person can approve the wrong command, and an agent can encounter untrusted instructions inside a repository. GitHub's local sandboxing for the Copilot app, announced on September 23, 2026, addresses that problem by constraining agent-run tools at the operating-system level.

한국어: 한국어로 보기

This guide explains what the sandbox restricts, how to enable it per project, how to design filesystem, network, and credential policies, how to confirm that a policy took effect, and how to recover when a legitimate workflow is blocked. The feature is in public preview and is off by default. The steps below are based on GitHub's official documentation rather than claimed hands-on results.

Quick answer: reduce the execution boundary before approving commands

Applies to: Local repository and working tree sessions in the GitHub Copilot app
Controls: Filesystem paths, outbound and local-network access, Git credentials, and GitHub CLI credentials
Default state: Disabled and configured separately for each project
When changes apply: New sessions or an existing session after it restarts
Failure behavior: If the host cannot enforce the requested policy, the sandboxed shell fails instead of silently running without isolation
Cost: GitHub says local sandboxing is included with a standard Copilot seat at no additional charge

Conceptual illustration of a coding agent workspace constrained by filesystem, network, and credential boundaries — A local sandbox separates the agent's workspace from broader filesystem, network, and credential access.

A working tree is not a security sandbox

A working tree separates branches and files so concurrent sessions do not overwrite one another. It does not, by itself, stop an agent-run command from reading another folder in your home directory, reaching a local service, or using stored credentials. Local sandboxing adds that missing boundary around tools invoked during a session.

It is still lighter than a virtual machine or a fully isolated container. GitHub documents that Microsoft eXecution Container (MXC) provides a common interface to operating-system isolation backends. The sandbox limits what a process can read, write, and reach, but it does not place the entire workflow inside a separate VM. For high-risk customer data or untrusted binaries, combine it with separate test identities, secret isolation, repository protections, and a stronger isolated environment when required.

What to decide before turning it on

Install the GitHub Copilot app and confirm that the intended account has Copilot access. GitHub's documentation says the app is available across Copilot plans.
Commit current work or create a dedicated branch. A sandbox limits access; it is not a version-control rollback mechanism.
List folders the agent must not read, such as other client repositories, personal documents, certificates, or exports.
Separate internet access from local-network access. A package registry, a localhost preview server, and an internal LAN service are different requirements.
Decide whether the task really needs git push or gh pr create. If not, disable the corresponding credentials.

Enable local sandboxing for a Copilot app project

Open Settings in the GitHub Copilot app.
Select the project you want to configure.
Under Sandbox, enable Sandbox new sessions.
Review the filesystem, network, and credential settings.
Start a new session, or enter /restart-session to restart an existing session while preserving its history.

GitHub Docs page showing the steps for enabling local sandboxing in a Copilot app project — GitHub's documented path: open app settings, select a project, then enable Sandbox new sessions. Source: GitHub Docs, checked September 29, 2026.

To change an active local session immediately, enter /sandbox on. Use /sandbox off to disable it for that session. After a session starts, these commands create a session-specific override and do not change the default for other sessions. If entered before a session starts, the command can affect the project default inherited by new sessions, so confirm which scope you are changing.

Policy 1: start with the smallest filesystem boundary

By default, a sandboxed app session can read and write its workspace and current working directory. Use three lists to handle anything outside that area.

Setting	Meaning	Good use
Additional read/write	The agent can read and modify the path	A shared build-output directory that must be updated
Additional read-only	The agent can read but not modify it	API schemas, shared documentation, or design tokens
Denied	The agent cannot access it	Other client repos, private keys, backups, and exported data

A more specific denied path remains denied even when a broader parent folder has read or write access. That makes exceptions possible, but complicated overlapping rules are easy to misunderstand. Prefer granting the exact folder a task needs instead of opening a broad parent directory and trying to deny many children.

Policy 2: treat internet and local network as separate permissions

The default policy permits both outbound internet and local-network connections. You can turn them off independently.

Outbound internet is needed for GitHub, package registries such as npm or PyPI, and external APIs.
Local network covers loopback services such as localhost development servers and other private-network hosts.

For documentation changes, static analysis, or tests that use already-installed dependencies, begin with both disabled. If package installation fails, enable outbound internet only. Add local-network access only when the task must reach a preview server, database, or another local service. This incremental approach makes each permission easier to justify.

There is an important Linux limitation. GitHub says the sandbox cannot independently control local-network access for spawned processes such as shell commands and local MCP or LSP servers. The setting still applies to in-process operations, including web requests and remote MCP connections. Do not assume identical enforcement across operating systems.

Policy 3: expose Git credentials only for the required outcome

Authenticated HTTPS Git and GitHub CLI operations are available by default. That supports convenient flows such as pushing a branch and opening a pull request, but it is broader than necessary for analysis or local-only edits.

Prepare a patch for review: Disable both Git and GitHub CLI credentials.
Allow a branch push: Enable Git credentials, but let a person create the pull request.
Automate pull-request creation: Enable both, while retaining protected branches, required reviews, and CI checks.

The sandbox controls whether credentials are available to agent-run tools; it does not replace repository permissions or branch protection. For a broader supply-chain review of plugins and MCP tools, see the Plugin4Shell response guide.

Three practical policy examples

1. Inspect an unfamiliar open-source repository

Goal: Understand the codebase and diagnose a failing test. Keep read/write access inside the workspace, deny nearby private projects and credential directories, and begin with network access disabled. Enable outbound internet only if an official dependency must be installed. Disable Git and GitHub CLI credentials. Review the resulting diff, commands, and unresolved risks before accepting any changes.

2. Fix an internal project with a localhost preview

Goal: Edit application code and verify it against a local development server. Grant read/write access to the workspace and read-only access to a shared API schema. Enable local-network access. Permit outbound internet only when dependencies must be downloaded. If the agent needs to push a branch, enable Git credentials without automatically exposing GitHub CLI credentials.

3. Automate a bounded maintenance pull request

Goal: Handle a dependency update or documentation change with a clearly defined scope. Do not grant write access outside the workspace. Permit the required registry and both credentials only if the session must push and open the PR. State the allowed files, forbidden files, required tests, and verification evidence in the prompt. The validation pattern described in the Unity Codex and Claude Code plugin guide still applies: inspect tests, logs, and the final diff rather than trusting a completion message.

How to verify that the sandbox is actually working

Start a new session after changing project settings, or run /restart-session.
Confirm that the session can read and modify a harmless file inside the allowed workspace.
Use a disposable test directory to confirm that a denied path is blocked. Never test with a real secret.
If networking is disabled, check external package access and localhost access separately.
If credentials are disabled, confirm that authenticated push or gh operations do not succeed.
When the app displays Run outside the sandbox?, inspect the exact command, purpose, and target. Prefer changing the workflow over broadening the policy when possible.

The Copilot app checks host support when the first sandboxed shell starts. If the operating system cannot enforce the requested policy, it reports an unsupported-platform or unsupported-policy error and does not run the command unsandboxed. If you see Sandbox unavailable, fix the reported condition and select Retry sandbox.

Troubleshooting common failures

Package installation cannot reach a registry

Check whether outbound internet is disabled. If it is enabled, identify whether the package manager needs a proxy, registry endpoint, or configuration file. Do not grant read access to the entire home directory when one explicit cache or configuration path is enough.

A localhost preview does not open

Check local-network access and verify that the development server is actually running. On Linux, remember that in-process requests and services spawned by shell, MCP, or LSP processes may not have identical enforcement.

Push or pull-request creation fails

Git credentials and GitHub CLI credentials are separate controls. A git push can require the former, while gh pr create can require the latter. Enable only the required option, restart the session, and retry.

A policy change does not affect the current session

Project-setting changes apply to new or restarted sessions. Use /restart-session to preserve history. Use /sandbox on or /sandbox off only when you intentionally want a session-level change, and do not confuse it with the project default.

Bottom line

The value of Copilot app local sandboxing is not deciding whether an agent is trustworthy. It is limiting the damage an unintended command or untrusted instruction can cause. Begin with the workspace only, minimize network and credential access, and expand one permission at a time when a legitimate requirement appears.

Because the feature is in public preview, menus and operating-system requirements can change. For important repositories, keep using dedicated branches, least-privilege tokens, protected branches, required reviews, and automated tests alongside the sandbox.

Official sources

Sources checked September 29, 2026.

Search This Blog

Stackfinch