GitHub Copilot App Local Sandbox: Setup and Verification

You enable sandboxing, but an existing session keeps its old permissions—or the agent repeatedly asks for access to install packages, reach a local server, or push a branch. The usual problem is not simply whether the sandbox is on; it is how project defaults, session overrides, and the separate file, network, and credential controls interact.

By the end of this guide, you can choose a starting policy for a local repository or worktree, apply changes to the correct session, and verify the boundaries with dummy data. The shortest path is: confirm the session type → enable Sandbox new sessions → narrow the three permission areas → start or restart the session → run safe checks.

GitHub announced this feature on September 23, 2026, and it remains in public preview, so the interface and behavior may change. Keep three boundaries in mind: local sandboxing is off by default, policy is configured per project, and a host that cannot enforce the requested policy fails the sandboxed shell instead of silently running the command without protection.

First confirm that your session is covered

Only local repository and local worktree sessions use this project policy. Cloud sandboxes, remote hosts, and GitHub Copilot CLI follow different isolation or configuration paths, so check the table before changing settings that your target session will never read.

Session type	Covered?	Boundary to remember
Local repository session	Yes	Uses the sandbox settings for the current project
Local working-tree session	Yes	A working tree separates branches and files, but does not restrict access elsewhere on the machine; the sandbox provides that permission boundary
Cloud sandbox session	No	Uses the cloud session’s own isolation
Session running on a remote host	No	The local project policy is not applied to the remote host
GitHub Copilot CLI	Configured separately	Copilot app and Copilot CLI sandbox settings do not replace each other

Enterprise-managed settings can make the effective policy more restrictive than the policy requested in project settings. The project page therefore describes what the app requests, not necessarily the maximum access an organization will permit.

How to enable sandboxing for new sessions

To protect later local sessions, turn on Sandbox new sessions and then start a new session; changing the switch does not update one that is already running. Use these steps:

1. Open the GitHub Copilot app settings.
2. Select the project you want to configure.
3. Find the Sandbox section.
4. Turn on Sandbox new sessions.
5. Start a new local session.

The switch affects only sessions created afterward. It does not modify a session that is already running. Later changes to file, network, or credential policy also apply only to new sessions or after a session restart.

To keep the current conversation history while reloading policy, enter /restart-session in the existing session.

GitHub recommends starting with the default policy for most projects. It supports common development work such as installing dependencies, connecting to a local development server, pushing a branch, and creating a pull request. Tighten it when the project sits next to sensitive folders, does not need network access, or should not use your credentials.

How to limit files, network, and credentials separately

Treat these as three independent controls: restricting files does not disable credentials, and disabling credentials does not protect a sensitive directory that remains readable. Tighten each area according to the task instead of turning everything off at once.

1. Filesystem: decide what can be read and changed

Start with the smallest file scope: keep workspace read/write access and add other paths only when the task truly needs them. A sandboxed session can read and write its workspace and current working directory by default, and project settings add three lists:

• Additional read/write: extra folders that agent-run tools may read and modify.
• Additional read-only: extra folders they may read but not modify.
• Denied: folders they may not access.

A more-specific denied folder remains denied even when a broader parent folder has read or write access. Prefer granting the smallest necessary path instead of opening an entire home directory and depending on many exceptions.

Windows has an important enforcement boundary. You can save a denied path in project settings, but if the active Windows sandbox capabilities cannot guarantee the denial, the command fails with an unsupported-policy message. It does not continue with the path exposed and does not automatically disable the sandbox.

2. Network: separate the internet from the local network

If the task installs dependencies or uses a local development server, do not disable both network paths automatically; decide separately whether outbound internet and the local network are needed. Sandboxed sessions can reach both by default, and you can control:

• Outbound internet: access to GitHub, package registries, and other internet services.
• Local network: loopback and local-network connections, including local development servers.

Network restrictions can affect dependency installation, API calls, preview servers, and any other tool that needs a connection. Treat network denial as a task trade-off, not a cost-free switch.

Linux has a specific limitation: 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 such as web requests and remote MCP connections. On Linux, verify both in-process and spawned-process behavior rather than testing only one path.

3. Credentials: control Git and GitHub CLI separately

For code reading or offline analysis, disable Git and GitHub CLI credentials first; enable them only when the task must push a branch or create a pull request. Authenticated Git and GitHub CLI operations are available inside the sandbox by default, and you can turn off:

• Git credentials: authenticated HTTPS Git operations.
• GitHub CLI credentials: authentication used by GitHub CLI.

Disabling them can prevent actions such as pushing a branch or creating a pull request. Filesystem and credential policy are separate boundaries: even with credentials disabled, use filesystem rules to protect directories that contain keys, configuration, or other sensitive material.

When to change the project, the current session, or one operation

Change project settings when future sessions should inherit the rule, use /sandbox on or /sandbox off for the current session, and run /restart-session after a project-policy change that the active session must reload.

Action	When it takes effect	Effect on other sessions
Change project Sandbox settings	New sessions or a restarted session	Changes the default inherited by later sessions in that project
Enter /sandbox on in an active local session	Immediately, as a persistent override for that session	Does not change the project default for other sessions
Enter /sandbox off in an active local session	Immediately disables sandboxing for that session	Does not change other sessions; commands then have the same file, network, and credential access as your user account
Enter /sandbox on or /sandbox off before a session starts	Changes the project default inherited by new sessions	Affects sessions started from that default afterward
Enter /restart-session	Restarts the current session, keeps its history, and reloads policy	Does not itself edit project policy

When a tool needs access that policy does not allow, the app may show Run outside the sandbox?. Depending on the effective policy, you can cancel, run that operation once outside the sandbox, or disable sandboxing for the rest of the current session. An enterprise owner can prevent users from running tools outside the sandbox.

Disabling through this prompt does not rewrite the project default or the existing session override. The temporary state ends when the session restarts or reattaches. After Sandbox off for this session appears, Re-enable sandbox turns it back on.

A safer decision order is to cancel first and understand why the command needs more access. If the access is a recurring requirement, narrowly update project policy and restart. Use a one-time run outside the sandbox only after reviewing the command, its arguments, and its impact. For an unfamiliar repository or a command assembled dynamically from a prompt, avoid disabling the sandbox for the whole session merely for convenience.

If the host cannot enforce the policy, the command stops

When the operating system cannot enforce a requested rule, the safe result is a failed command—not an automatic downgrade to unsandboxed execution.

The GitHub Copilot app accepts sandbox settings before it knows whether the operating system can enforce all of them. Support is checked when the first sandboxed shell starts.

If the host cannot enforce the requested policy:

• The shell reports an unsupported-platform or unsupported-policy message.
• The command does not continue unsandboxed.
• If the app shows Sandbox unavailable, fix the reported problem and select Retry sandbox.

This is fail-closed behavior, not best-effort execution. Saving settings successfully therefore does not prove that policy is active on the current machine. Start at least one sandboxed shell, confirm that no unsupported message appears, and run a minimal verification.

How to verify the policy with dummy data

GitHub documents the behavior the policy should enforce, but only a check on your own machine can confirm that this operating-system and policy combination works. The procedure below uses disposable folders and dummy files, so you do not need to touch real keys or production configuration.

Create disposable test folders outside the workspace and place only dummy files in them. Do not test with real SSH keys, cloud credentials, or production configuration.

Check	Safe procedure	Expected policy behavior
New-session inheritance	Enable Sandbox new sessions, then create a new local session	The new session uses project policy; an old session does not change automatically
Applying a policy edit	Change one rule and enter /restart-session	The session restarts, keeps history, and reloads policy
Read-only folder	Add a disposable folder to Additional read-only, read a dummy file, then try to create a test file	Reading should work; modification should be blocked
Denied folder	Add another disposable folder to Denied, then try to list or read a dummy file	Access should be blocked even if a broader parent path is allowed
Internet access	Turn off Outbound internet and make a harmless connection check	The external connection should fail; turn it back on and compare
Local network	Turn off Local network and connect to a disposable local test service	Access should follow platform capabilities; account for the Linux spawned-process limitation
Git credentials	Turn off Git credentials and run a non-mutating authentication check in a test repository	Authenticated HTTPS Git operations may be unavailable
GitHub CLI credentials	Turn off GitHub CLI credentials and run a non-mutating check such as gh auth status	GitHub CLI should not receive the previous authentication capability; exact errors can vary
Fail-closed behavior	If unsupported-platform or unsupported-policy appears, check that a target dummy file was not created	The command should not continue unsandboxed or cause the intended side effect

Delete the test folders afterward and restore only the minimum permissions the project actually needs. Do not prove a denial rule by attempting to access a real sensitive directory.

Which starting policy fits your task

Everyday development, an unfamiliar repository, and offline analysis should not share one policy. Keep the capabilities required for normal development, start tighter for unfamiliar code, and disable network and credentials first for offline work.

Everyday development

Enable the sandbox, retain the default network and credential capabilities, add only required external folders, and explicitly deny neighboring sensitive directories. This fits normal work that installs dependencies, runs local services, pushes branches, and opens pull requests.

Reviewing an unfamiliar repository

Give read/write access only to the workspace, make extra reference material read-only, disable Git and GitHub CLI credentials by default, and keep outbound internet off until you understand where the dependencies come from. When temporary access is necessary, open one specific capability rather than immediately using /sandbox off.

Local offline analysis

Disable outbound internet and unneeded credentials, keeping only necessary file access. If local-network isolation also matters, verify spawned-process behavior separately on Linux instead of assuming that one UI switch controls every process identically.

These are not GitHub-named presets. They are starting points assembled from the permission dimensions GitHub exposes. Match the final policy to the repository, operating system, enterprise rules, and actual task.

Mistakes that make the policy ineffective or too broad

The most common errors are treating “settings saved” as “policy enforced” and disabling the whole sandbox after the first denial. The seven cases below either invalidate your test or grant more access than the task needs.

1. Treating a working tree as a security boundary. It separates concurrent branches and files; it does not prevent commands from reaching other locations on the machine.
2. Editing policy and continuing to test an old session. Project changes are not retroactive; start a new session or use /restart-session.
3. Assuming the app and CLI share one sandbox. They are configured separately.
4. Treating a successful save as proof of host support. Enforcement support is checked only when the first sandboxed shell starts.
5. Overlooking what /sandbox off means. Agent-run commands then receive the same access scope as your user account.
6. Assuming network behavior is identical on every platform. Linux has a documented local-network limitation for spawned processes.
7. Using a broad bypass whenever access is denied. Usually it is safer to confirm the need, make the smallest policy adjustment, and restart the session.

What to do next

First confirm that you are using a local repository or local worktree session, then turn on Sandbox new sessions. For everyday development, begin with the default policy and keep only the directories, network paths, and credentials the task needs; for unfamiliar code or offline analysis, start with the tighter scenario policy and add one capability at a time.

After changing project policy, start a new session or run /restart-session, then verify read-only, denied, network, and credential boundaries with disposable data. If you see unsupported-platform, unsupported-policy, or Sandbox unavailable, resolve the compatibility issue instead of using /sandbox off and mistaking an unsandboxed result for a successful sandbox test.

Official references

Use these GitHub pages before and after configuration to confirm the current interface, scope, and failure behavior.

• Configuring local sandboxing in the GitHub Copilot app
• Local sandboxing in the GitHub Copilot app — GitHub Changelog, September 23, 2026