What does GitHub Copilot local sandboxing protect?

It limits the filesystem paths, network destinations, credentials, and subprocess capabilities available to agent-run commands. It reduces the blast radius of a bad command, but it is lighter-weight isolation than a virtual machine.

Is Copilot local sandboxing enabled by default?

No. GitHub says local sandboxing is off by default. Teams should enable it in project settings for new app sessions or with the sandbox command in Copilot CLI, then verify the effective policy.

Can a sandboxed Copilot session use Git and GitHub CLI?

Yes, if the authentication settings permit it. GitHub can inject a token for authenticated HTTPS Git and export GH_TOKEN for GitHub CLI without exposing the normal credential store.

Does the local sandbox isolate remote MCP servers?

No. Remote MCP servers run outside the local machine, so the local operating-system sandbox does not constrain them. Their permissions, data handling, and authentication require separate controls.

Should teams allow sandbox bypass?

Only when the workflow needs it and the reviewer can understand the requested command. High-risk repositories should disable bypass through managed policy so failed commands stop instead of requesting unsandboxed execution.

How can I verify which paths Copilot can access?

In Copilot CLI, run /sandbox status to confirm that sandboxing is active and /sandbox policy to inspect the resolved read-write, read-only, denied, network, and developer-tool permissions.

Is local sandboxing equivalent to a cloud sandbox?

No. Local sandboxing uses operating-system containment on your machine. A cloud sandbox runs the session in an isolated, ephemeral Linux environment hosted by GitHub and keeps it away from the local host.

GitHub Copilot Local Sandboxing Guide for Coding

GitHub Copilot local sandboxing puts an operating-system policy between a coding agent and the rest of a developer's machine. The policy can restrict writable files, readable files, outbound internet access, local network access, Git credentials, GitHub CLI credentials, local MCP servers, and language servers. That makes it useful for routine repository work where an agent needs local tools but should not inherit every permission held by the logged-in user.

The feature needs a careful rollout. GitHub describes local sandboxing as lighter-weight isolation than a virtual machine or container, and the underlying Microsoft eXecution Container project warns that its preview policies may still be overly permissive. A sensible security position is to treat the sandbox as a blast-radius control, then keep least-privilege credentials, branch protection, code review, and secret scanning around it.

What GitHub Shipped

GitHub announced local sandboxing for local repository and working-tree sessions in the Copilot app on 23 September 2026. The app can apply a project-level default to new sessions, while /sandbox on and /sandbox off change the active session. GitHub also documents local sandboxing for Copilot CLI, where the commands differ slightly.

App sessions and CLI sessions are separate

The Copilot app and Copilot CLI expose related controls but should not be treated as one shared configuration surface. In the app, project settings determine whether new local sessions start sandboxed. In the CLI, /sandbox enable, /sandbox disable, /sandbox status, and /sandbox policy manage and inspect the CLI's effective state.

Document both paths if your team uses both products. A secure app default does not prove that a CLI session is constrained, and a hardened CLI configuration does not automatically describe the behavior of a new app session.

The setting affects session boundaries

Project-setting changes apply to new or restarted app sessions. That detail matters during rollout. If a developer changes a project's filesystem or network rules and then continues an old session, the old process may still be operating under the earlier policy.

Treat a sandbox policy edit like a configuration deployment. End or restart the affected sessions, run a harmless verification command, and record the resulting policy state before asking the agent to resume work.

Unsupported enforcement should fail closed

GitHub's launch note says that if the operating system cannot enforce a requested configuration, the sandboxed shell fails instead of silently running without the sandbox. That is the right failure mode. Your validation should confirm the failure remains visible in agent output and CI-style logs rather than being dismissed as an ordinary tool error.

The Boundary You Actually Get

Local sandboxing restricts processes on the developer's existing machine. It is not a disposable VM, and it does not move the repository or commands to a different trust domain. GitHub's conceptual documentation places it at the lighter end of the isolation spectrum.

OS containment, not a separate machine

GitHub uses Microsoft eXecution Container, or MXC, as the cross-platform layer. MXC maps a common policy to operating-system-specific containment mechanisms on macOS, Linux, and supported Windows builds. The goal is consistent policy intent even though the enforcement backend differs by platform.

The practical benefit is low setup cost and access to the developer's installed compilers, package managers, and local services. The trade-off is that a local containment bug can expose the host in a way that a well-separated remote environment would not.

Child processes and in-process tools differ

GitHub's documentation draws an important line between sandboxed child processes and built-in file operations. Shell commands, searches that launch child processes, and opted-in local MCP or language servers can receive operating-system enforcement. Some built-in file-reading and editing tools run inside the CLI process and check the policy in software because the OS sandbox cannot see those operations.

That does not make the feature useless. It does mean a threat model must distinguish a kernel-enforced denial from a best-effort check in application code. Teams handling sensitive source, signing keys, or production credentials should account for both paths.

Remote MCP servers sit outside the boundary

A remote MCP server is not a process on the local machine. The local sandbox cannot restrict what that service does with data sent to it or which external systems it can reach. Review the server's scopes, retention, authentication, and tool descriptions separately.

This is especially important when an agent can combine local code context with a remote tool. Local path restrictions may prevent reading a secret, but they do not stop the model from sending permitted source files to a remote service if the workflow and server allow it.

Build a Threat Model Before a Policy

Begin with assets and actions rather than toggles. List what the agent must read, what it must modify, which services it must call, and which credentials it must exercise. Anything outside that list should be denied or withheld.

Protect the developer's home directory

The highest-value accidental exposure often lives outside the repository: SSH keys, cloud configuration, browser profiles, shell history, password-manager integration, local database files, and environment files from unrelated projects. A repository-scoped write grant is much safer than inheriting the developer's full home-directory access.

Pay attention to paths that tools discover indirectly. Build systems read global caches, package managers inspect user-level configuration, and Git can consult credential helpers. Grant the narrow cache or configuration path that the task needs instead of granting the entire parent directory.

Protect the repository from destructive writes

Even inside the selected project, the agent does not need equal access everywhere. Generated output and source files may be writable, while deployment keys, production configuration, compliance evidence, and protected fixtures should be read-only or denied.

Repository access also includes .git. Removing working-directory access can break status, diff, add, and commit operations unless .git is granted explicitly. Decide whether the agent needs to commit, then encode that decision rather than discovering it halfway through a task.

Model data exfiltration alongside deletion

Filesystem write protection cannot stop a process from reading an allowed file and sending it over an allowed network connection. If source code or customer data is sensitive, network policy belongs in the same threat model as path policy.

Local network access deserves its own review. An agent that can reach localhost, RFC 1918 addresses, or internal DNS may encounter unauthenticated development databases, metadata endpoints, admin consoles, or services that were never designed for an untrusted caller.

Configure Filesystem Access Deliberately

GitHub supports read-write, read-only, and denied path rules. The effective policy combines saved settings, automatically discovered paths, the working directory, system needs, and managed enterprise settings.

Use the repository as the main write root

For a normal implementation task, write access should usually cover the checked-out repository and a task-specific temporary location. Dependency caches can be read-write when they materially reduce build time, but they should not become a shortcut to the whole home directory.

A representative policy might look conceptually like this:

read-write:
  /work/service-api
  /tmp/copilot-service-api

read-only:
  /opt/homebrew
  /Users/developer/.npm

denied:
  /work/service-api/.env
  /Users/developer/.ssh
  /Users/developer/.aws

The actual interface uses absolute paths and includes a directory's subtree. Wildcards are not supported, so review the full scope of every parent directory you add.

Prefer read-only for tools and shared inputs

Compilers, SDKs, reference repositories, shared fixtures, and documentation normally need read access. Marking them read-only prevents an agent-run installer or cleanup command from changing a shared dependency in place.

Some tools will fail when they cannot update a cache. When that happens, redirect the cache to a task-specific writable directory. Expanding the shared directory to read-write is faster in the moment but weakens isolation for every command in the session.

Deny secrets inside otherwise allowed trees

A broad repository grant can be narrowed with a denied child path. Use that for .env files, private keys, production Terraform state, signing material, or exported customer data that happens to live beneath the working directory.

Then test the rule. Ask the agent to list the parent directory, read an ordinary file, and attempt to read the denied file. The expected result is successful normal work and an explicit access failure for the protected asset.

Treat Network Access as a Separate Permission

GitHub exposes independent controls for outbound internet connections and the local network. Both are allowed by default in the documented CLI configuration, so enabling the sandbox without reviewing network settings may leave a large exfiltration path.

Block the local network unless the task needs it

Most code-editing work does not require LAN access. Tests that call a local database, container, or development server are the main exception. Keep local access off for documentation, static analysis, refactoring, and many unit-test tasks.

When a task does need a local service, prefer a dedicated instance with test data and low-privilege credentials. Do not let the convenience of localhost turn a developer's machine into an implicit trusted network for the agent.

Limit outbound traffic by workflow

Package installation, API documentation lookup, and remote test environments may require internet access. A blanket outbound allowance is simple, but it also lets any permitted process call arbitrary hosts.

GitHub supports an HTTP proxy setting. On Windows the sandbox can enforce proxy routing, while GitHub notes that Linux and macOS proxy behavior is cooperative and depends on tools honoring standard proxy environment variables. A proxy still helps with logging and allowlists, but its strength varies by platform.

Separate fetch and execution phases

One practical pattern is to download and verify dependencies before the agent session, then run the agent with outbound traffic disabled. Another is to permit network access during a controlled bootstrap step and restart the session under a tighter policy for code execution.

This makes the network rule easier to audit. It also reduces the chance that a test script, package lifecycle hook, or compromised dependency can make an unexpected call during the main editing phase.

Control Git and GitHub Credentials

Git credentials turn a filesystem-capable agent into an actor that can read private repositories or push changes. GitHub separates authenticated Git and gh access so teams can decide which capability the task needs.

Prefer injected, scoped tokens

The documented "Authenticate git" option injects a GitHub token for authenticated HTTPS Git. "Authenticate gh" exports GH_TOKEN so GitHub CLI can work without reading its normal configuration directory or operating-system keychain.

That design is preferable to exposing a developer's credential store. It still requires scope discipline. A token able to administer repositories or modify workflows creates far more risk than a read-only token or one limited to a single repository.

Keep macOS keychain access off by default

GitHub lists keychain access as a separate macOS setting and documents it as off by default. Leave it off unless a required tool cannot use an injected or task-specific credential.

Opening the system keychain to a session can expose credentials unrelated to the repository. If you must enable it, use a dedicated keychain or developer account with narrowly scoped entries and restart the session when the task ends.

Split read, write, and release duties

An agent can often clone, inspect, edit, and test without permission to push. Let a human or a tightly controlled automation perform the final push. Release signing, package publishing, production deployment, and secrets rotation should be separate workflows with their own approval and audit trail.

This separation limits the effect of a prompt injection or incorrect plan. The agent can prepare a valid change without holding the credential needed to make the change public or operational.

Sandbox MCP and Language Servers

Local MCP servers and language servers are executable processes with the same potential to read files or make network calls as shell commands. GitHub's CLI configuration can run both inside the sandbox, and the documented defaults enable that containment.

Keep subprocess sandboxing enabled

A language server routinely reads large parts of a repository. An MCP server might wrap a database, browser, cloud CLI, or internal API. Leaving either outside the sandbox creates a path around the restrictions applied to the agent's shell.

Test the server under the intended policy. Some language servers write indexes in the home directory, and some MCP servers expect unrestricted configuration access. Redirect their state to approved paths rather than exempting the whole process.

Review tool permissions at the service layer

Process isolation does not replace application authorization. A sandboxed database MCP server can still execute every query allowed by its database credential. A sandboxed cloud tool can still delete resources if its token permits deletion.

Use read-only service accounts for investigation tasks, separate staging from production, and require human confirmation for destructive tools. The sandbox limits host access; the service credential limits remote access.

Treat tool output as untrusted input

Repository files, issue descriptions, dependency metadata, and MCP results can contain instructions aimed at the model. Sandboxing limits the damage an induced command can cause, but it does not stop the model from selecting a harmful permitted action.

Keep approval gates for high-impact tools and validate outputs before feeding them into another command. A local sandbox is most effective when paired with a disciplined tool policy.

Decide What Bypass Means

GitHub can prompt when a command fails inside the sandbox and request permission to run that attempt outside it. The documented CLI setting allows bypass by default. Enterprise policy can disable the option.

A bypass is a privilege escalation

The prompt should be reviewed as a security decision, not as a routine retry button. Examine the exact command, its working directory, environment, inputs, and reason for failure. If the task needs a new path or network permission, updating the saved policy may be safer and more auditable than an unrestricted one-off run.

Avoid approving commands that expand another interpreter, shell substitution, downloaded script, or package lifecycle hook without inspecting the resolved behavior. The visible top-level command may hide the operation that needed broader access.

Disable bypass for sensitive repositories

Repositories containing production infrastructure, identity code, payment logic, or customer data should fail when the policy is insufficient. An explicit failure forces the team to revisit the task design and leaves a clearer audit trail.

GitHub documents sandbox.allowBypass as an enterprise-managed setting. Setting it to false prevents individual unsandboxed approvals and session-wide disablement. This is a reasonable baseline for regulated or high-impact work.

Log exceptions and remove them

If the organization permits bypass, record the command, approver, repository, justification, and outcome. Review recurring exceptions. Repetition usually means the policy is missing a legitimate requirement or the workflow is relying on a tool that does not fit the intended boundary.

Do not let temporary exceptions become invisible operating procedure. Either narrow and codify the needed grant or redesign the step.

Roll Out with Policy Profiles

One policy will not fit documentation edits, dependency upgrades, integration tests, and release work. Define a small set of reviewed profiles based on task risk and required capability.

A useful three-profile model

An edit profile can allow repository writes, deny secrets, block local network access, and block outbound traffic. A build profile can add selected caches and outbound package registries. An integration profile can reach named test services with low-privilege credentials.

Release work should remain outside normal agent sessions or use a dedicated, isolated environment. Avoid creating a "full access" profile that merely recreates the developer account's permissions.

Pilot on representative repositories

Choose a frontend project, a backend service, and a repository with native tooling. Run common tasks: install, lint, unit test, integration test, Git diff, and pull-request preparation. Record failures by missing filesystem, network, credential, or subprocess permission.

This produces a realistic policy without starting from unrestricted access. It also exposes platform differences before an organization-wide mandate interrupts normal work.

Make the secure path the easy path

Set the project default so new local app sessions start sandboxed. Provide a short verification checklist and explain how to request a policy change. Developers will work around controls that fail opaquely or require repeated manual repair.

The goal is predictable containment, not maximum denial. A narrow policy that supports the normal workflow will survive better than an unusable policy that everyone learns to bypass.

Verify the Effective Policy

Saved configuration is only an input. GitHub's /sandbox policy command reports the resolved policy after automatic grants, current directory, user rules, and managed settings are combined.

Check status and policy at session start

For Copilot CLI, use:

/sandbox status
/sandbox policy

The first command confirms whether the current session is sandboxed. The second shows readable, writable, denied, network, and developer-tool access. Capture that output for high-risk changes or regulated evidence.

For the Copilot app, confirm the project default before creating a session and verify the active session indicator after it starts. Remember that changing the default does not retroactively rewrite an already running process.

Run negative tests

A positive test proves the agent can work. A negative test proves the boundary exists. Try to read a denied secret, write to a read-only reference path, reach a blocked internet host, and connect to a blocked local service.

Failures should be explicit and should not trigger an unnoticed unsandboxed retry. Re-run the tests after application upgrades, operating-system updates, and policy changes.

Re-test every supported operating system

MXC uses different backends across platforms, and GitHub's Windows support requires recent builds. A policy name that looks identical may have different enforcement details or preview limitations.

Maintain a small conformance suite for macOS, Linux, and Windows systems your organization supports. If a platform cannot meet the required boundary, route that work to a cloud sandbox or another controlled execution environment.

Choose Local or Cloud Sandboxing

Local sandboxing is a good fit when the task depends on local tools, large existing caches, hardware, or development services. Cloud sandboxing is better when the session should have no path to the developer machine or when several isolated tasks must run in parallel.

Use local for low-latency development

Repository-scoped edits, local builds, and tests against disposable development services benefit from the developer machine's speed and existing setup. A strict local policy can reduce risk without paying the startup and data-transfer costs of remote execution.

Keep sensitive credentials and unrelated repositories outside the allowed tree. The local choice should follow from a clear need for local resources, not from habit.

Use cloud for stronger separation

GitHub describes cloud sandboxes as isolated, ephemeral Linux environments. They separate agent execution from the local host and can be preferable for untrusted repositories, dependency inspection, or tasks that require broad command execution.

Cloud execution has its own policy, billing, identity, and data-transfer considerations. It also may not reproduce a developer's operating system or local service topology. Decide by workload rather than treating one option as a universal replacement for the other.

Escalate high-risk work beyond preview controls

The public-preview status matters. MXC's repository warns that its early policies may be overly permissive and says profiles should not yet be treated as security boundaries. Organizations with a requirement for strong isolation should use a VM, hardened container boundary, ephemeral runner, or cloud sandbox designed to meet that requirement.

Local sandboxing still adds useful defense in depth. It should sit below code review and service authorization, not carry the entire security claim.

Monitor and Audit Agent Sessions

A sandbox policy is more useful when teams can show that it was active and understand when it blocked or permitted an operation. Build lightweight operational evidence into the rollout.

Record configuration versions

Store approved project policy templates in version control where possible. Record the Copilot app or CLI version, operating system, policy revision, repository, and session start time for sensitive work.

This helps incident response distinguish an agent mistake inside an intended boundary from a session that started before a policy change or ran with bypass enabled.

Watch for repeated denials

Denials are useful signals. A burst of access attempts against unrelated paths can indicate a broad tool assumption, a compromised dependency, a prompt injection, or an agent plan that does not match the task.

Do not automatically suppress every denial as noise. Group them by tool and workflow, then either fix the tool's configuration or investigate why the access was attempted.

Keep repository protections in place

Branch protection, required reviews, status checks, signed releases, dependency review, secret scanning, and environment approvals remain relevant. Sandboxing changes where commands can act; it does not decide whether the resulting code is correct or safe to merge.

For teams building a wider agent governance program, pair this boundary with the evaluation approach in Coding Agent Evals with Harbor and Vercel Sandbox and isolated preview practices from Cloudflare Worker Previews for Coding Agents.

A Deployment Checklist

Use this checklist before making sandboxed local sessions the default:

Inventory the files, networks, credentials, and subprocesses needed by common tasks.
Set repository write access and deny secrets inside allowed trees.
Make shared tools and reference data read-only.
Block local network access unless a named development service is required.
Limit outbound traffic or route it through a reviewed proxy where enforcement supports it.
Prefer injected Git and gh tokens over credential-store access.
Keep keychain access disabled and use low-privilege service accounts.
Sandbox local MCP and language servers, then test their state paths.
Disable bypass for sensitive repositories through managed policy.
Restart sessions after policy changes and inspect the effective policy.
Run negative tests on every supported operating system.
Preserve branch, review, scanning, and deployment protections.

The most useful first production step is small: enable sandboxing for one representative project, deny its secrets, block the local network, and run the team's normal test sequence. The failures will reveal the true dependency surface. Turn those findings into a narrow profile, verify it with /sandbox policy, and only then expand the rollout.