Configuring local sandbox settings

About local sandbox configuration

You can use the settings in the GitHub Copilot app or the /sandbox slash command in Copilot CLI to grant extra paths, adjust network access, or turn sandboxing on or off.

Local sandboxing limits access to files, network resources, and credentials on your machine, reducing the potential impact of an unintended command. Settings are configured separately in the Copilot app and Copilot CLI. Changing them in one does not change them in the other.

For a conceptual overview of cloud and local sandboxes for Copilot, see AUTOTITLE. For detailed instructions on using local sandboxing, see AUTOTITLE.

Prerequisites

• Windows: Local sandboxing on Windows requires Windows 11 version 25H2 with update KB5124010 or later, or Windows 11 version 26H1 with update KB5124006 or later, with support for the BaseContainer tier of the ProcessContainer backend.
• Linux: Bubblewrap (bwrap) version 0.5.0 or later, and slirp4netns must be installed and available on your PATH.

Configuring the Copilot app

You configure local sandboxing separately for each project in the GitHub Copilot app. The configuration applies to local repository and working tree sessions. It does not apply to cloud sandbox sessions or sessions that run on a remote host.

A working tree keeps the branches and files for concurrent sessions separate, but it does not restrict what a command can access elsewhere on your machine. Local sandboxing provides that additional protection.

Enabling local sandboxing for a project

Local sandboxing is turned off by default unless enterprise managed settings require it. The sandbox settings are not available for remote-only projects. To enable sandboxing for new local sessions in a project:

1. In the app sidebar, open Settings.
2. Under "Projects," select the project that you want to configure.
3. Under "Sandbox," turn on Sandbox new sessions.

The setting applies to new sessions in the project. It does not change a session that is already running. For details of how to turn on local sandboxing for the current session, see AUTOTITLE.

For most projects, you can start with the default sandboxing policy. This allows access needed for common development tasks such as installing dependencies, connecting to a local development server, pushing a branch, and creating a pull request. Add restrictions when the project is next to sensitive folders, does not need network access, or should not use your credentials.

Configuring the sandbox policy for a project

A sandbox policy is a set of rules that controls which files, networks, and credentials agent-run tools can access. The project settings describe the policy that the app requests when a sandboxed session starts. The effective policy can be more restrictive, for example, when enterprise managed settings apply.

The "Configured policy summary" shows your selected folder, network, and credential settings. It does not confirm that the sandbox is running or show every restriction that applies. Changes are saved automatically.

In the project settings, you can configure:

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

Configuring filesystem access

By default, a sandboxed session has read/write access to its workspace and current working directory. You can grant access to additional folders or prevent access to specific folders.

In the "Sandbox" section of the project settings, configure any of the following lists:

• Additional read/write: Folders that agent-run tools can read and modify.
• Additional read-only: Folders that agent-run tools can read but not modify.
• Denied: Folders that agent-run tools cannot access.

To add a folder, click Add folder for the appropriate list, then choose the folder. To remove a folder, click the delete icon next to its path.

A more-specific denied folder remains denied when a broader parent folder has read or write access.

On Windows, you can save a denied path in the project settings. If the active Windows sandbox capabilities cannot guarantee the denial, a sandboxed command fails with an unsupported-policy message. The command does not run with the denied path accessible or without a sandbox.

Configuring network access

By default, both network settings are turned on in the app. In the "Sandbox" section of the project settings, you can change the following settings:

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

Network restrictions can affect package installation, API calls, preview servers, and other tools that need a network connection.

On Linux, sandboxed processes cannot connect directly to servers on your computer's localhost. The local network setting still controls requests through the built-in local proxy, as well as in-process operations such as web requests and remote MCP connections.

The operating-system limitations described in Configuring network settings also apply to the app. Unlike the app's Local network setting, the CLI's Allow local network setting is turned off by default.

Configuring credentials

By default, authenticated Git and GitHub CLI operations are available inside the sandbox. You can turn off either of the following settings:

• Git credentials: Allow authenticated HTTPS Git operations.
• GitHub CLI credentials: Allow GitHub CLI (gh, not copilot) to authenticate.

Turning off credential access can prevent operations such as pushing a branch or creating a pull request from inside the sandbox.

Applying policy changes

Changes to filesystem, network, and credential settings apply to new sessions or when an existing session restarts. They do not change the policy of a currently running session.

To restart a session while keeping its history, enter:

/restart-session

The app accepts sandbox settings before checking whether your operating system can enforce them. Support is checked when the first sandboxed shell starts. If the host cannot enforce the requested policy, the shell fails with an unsupported-platform or unsupported-policy message and does not run unsandboxed. To find the currently supported Windows versions, see Windows OS support for Copilot sandboxing.

If the app displays Sandbox unavailable, address the reported problem, then click Retry sandbox.

Configuring Copilot CLI

Use the /sandbox slash command to configure local sandboxing in the CLI. A managed setting is labeled (managed) in the /sandbox interface and can't be changed.

Opening the sandbox configuration

1. Start a Copilot CLI session.

2. Enter the /sandbox slash command.

   This opens an interactive configuration interface with four tabs: General, Credentials, Filesystem, and Network. Use Tab to switch between tabs. Press Esc to save your changes and close the configuration. If you are in a path, host-rule, or masked-variable list, press Esc first to return to its tab.

Configuring general settings

The General tab controls the top-level sandbox behavior. When enterprise managed settings enforce a value, the dialog labels the setting as (managed) and prevents you from changing it.

Allowing sandbox bypass

The Allow sandbox bypass setting controls whether Copilot can ask for permission to retry a blocked command with broader access.

• On (default): For supported sandbox denials, the CLI offers an approval prompt describing the command and the proposed retry. Approval applies to that attempt. You can also choose to disable sandboxing for the rest of the session, if your enterprise permits it, or give Copilot another instruction.
• Off: The command remains blocked. You can adjust settings you control or ask Copilot to take a different approach.

A bypass only removes Copilot's own sandbox limits, not your operating system's. The command still runs under your normal account, so it gains no administrator or root access and cannot reach anything your system already blocks.

On supported Windows hosts, an approved retry can first relax file and process restrictions while keeping network restrictions in place. Its result is labeled "sandbox relaxed." If the command is still blocked, the CLI can then use the full bypass described in the same approval prompt. That result is labeled "sandbox bypassed."

If enterprise managed settings set sandbox.allowBypass to false, you cannot approve individual commands to run outside the sandbox or disable sandboxing for the rest of the session. If managed settings require sandboxing but the effective policy permits bypass, you cannot turn sandboxing off through ordinary settings, but you can disable it for the rest of the current session—either from an active bypass permission prompt or by running /sandbox disable—without loosening the saved policy.

Configuring authentication settings

The Credentials tab controls authentication for Git and GitHub CLI, and lets you configure masked environment variables. Sandboxed processes receive placeholder values. A local proxy supplies the real credentials only in HTTPS request headers sent to approved destinations. As on the other tabs, an enterprise-managed value is shown as (managed) and can't be changed.

On macOS, keychain access is turned off by default. To allow sandboxed commands to use the system keychain, set sandbox.userPolicy.seatbelt.keychainAccess to true in your personal settings.json file. This option is not available through /sandbox or /settings.

Masking environment variables

Use masked environment variables to let sandboxed tools authenticate to an API without receiving the real token. Masking applies to the selected variables in commands, local MCP servers, and language servers that run inside the sandbox. Git and gh authentication use masking automatically when their authentication settings are on. You do not need to add entries for them.

Before you configure masking, set the environment variable in the environment used to start Copilot CLI. The value must be non-empty. Missing variables stay absent, and empty values are not masked.

Masking is active only while local sandboxing is enabled. Adding a masked variable does not enable sandboxing.

1. Enter /sandbox enable to enable local sandboxing.
2. Enter /sandbox status and confirm that sandboxing is enabled for the current session before continuing.
3. Enter /sandbox, then open the Credentials tab.
4. Select Masked environment variables and press Enter.
5. Press A to add an entry.
6. In Variable, type the variable name, such as EXAMPLE_API_TOKEN, then press Enter. Do not enter the secret value.
7. In Inject hosts, type a comma-separated list of hosts that can receive the real value, such as api.example.com, then press Enter. Use hostnames or wildcard subdomains such as *.example.com. Do not include a URL scheme, path, port, or bare *.
8. Press Esc to return to the Credentials tab.
9. On Windows, credential masking requires a Windows version that supports the sandbox’s local proxy. Go to the Network tab, and enable Allow local network. This also permits private-network access, subject to your configured host restrictions.
10. Press Esc to save and close the configuration.

To edit an entry, select it and press Enter. To remove it, press X. The editor stores only variable names and destination hosts. It does not read or display secret values.

You can also configure entries under sandbox.credentials.envVars in your personal settings.json file. For example, this entry lets the proxy supply EXAMPLE_API_TOKEN only to api.example.com:

{
  "sandbox": {
    "enabled": true,
    "credentials": {
      "envVars": {
        "EXAMPLE_API_TOKEN": {
          "injectHosts": ["api.example.com"]
        }
      }
    }
  }
}

Adding an injection host does not allow network access to it. Your network settings must also permit the connection. Exact hostnames match only that host. *.example.com matches subdomains, but not example.com itself.

Masking requires a variable to remain in the child process's environment. Do not list a variable you want to mask in --secret-env-vars. That option removes named variables from command and MCP server environments instead of making them available as placeholders.

Configuring filesystem settings

The Filesystem tab controls which directories and files the sandboxed process can access.

By default, Copilot is granted read/write permission to everything in and below the current working directory. If you are in a Git repository, Copilot is also granted:

• Read/write permission to everything in and below the repository's .git directory.
• Read permission for everything else in the repository above the current working directory. The working directory itself stays read/write, because the more specific grant wins where the two overlap.

Adding filesystem path rules

You can specify paths that you want to add to the sandbox. This allows you to grant read-only or read/write access to directories and files outside the working directory. You can also deny access, to exclude directories and files from the sandbox.

1. In the Filesystem tab, select User-configured paths and press Enter.
2. Press A to add a new path rule.
3. Type a file or directory path. Use an absolute path—for example, /Users/octocat/projects/app on macOS or Linux, or C:\Users\octocat\projects\app on Windows. Then press Enter.

1. Use the left and right arrow keys on your keyboard to navigate between the permissions options: Read/Write, Read-Only, Denied. Then press Enter to select an option.

If the path itself is a symbolic link, selecting Read/Write or Read-Only also adds its current target when the CLI can resolve it. This does not automatically grant access to targets of other links inside an allowed directory.

After you have added filesystem paths, you can edit or delete them.

1. Use the up and down arrow keys to select a path.
2. Press Enter to edit the path, or X to delete it.
3. Press Esc to return to the Filesystem tab. Press Esc again to save and close the configuration.

On Windows, denied paths require a version that supports this restriction. If the host cannot enforce them, the command fails with an explanation rather than running with weaker protection.

Configuring network settings

The Network tab controls whether sandboxed processes can make network connections.

Local network access behaves differently on each operating system:

The setting also applies to the CLI's built-in web requests on every platform. If Sandbox MCP servers is enabled, it applies to remote MCP connections too. Allowing local access lets the built-in web_fetch tool reach localhost, but does not remove its separate restrictions on other private-network addresses.

Credential masking uses a local proxy even when you have not configured a remote proxy or host rules. This includes automatic masking for Git and gh authentication, which is enabled by default, and masked environment variables.

When a local proxy is active on macOS, turning local access on lets a command listen on a port, but does not let it connect directly to that port itself. A server listening on all network interfaces can be reachable from other devices on your network. On Windows, do not assume a server inside a proxied sandbox is reachable from the host's localhost.

Allowing or blocking specific hosts

Use host rules to restrict which destinations sandboxed commands can reach. Host rules are active only while sandboxing and outbound connections are enabled.

You can specify hostnames, wildcard subdomain patterns, or individual IPv4 or IPv6 addresses. IP address ranges in CIDR notation, such as 203.0.113.0/24, are not supported.

1. On the Network tab, select Proxy and blocking and press Enter. Then select Host rules and press Enter.
2. Press a to add a rule.
3. Type a hostname, wildcard subdomain pattern, or individual IP address. For example, use example.com, *.example.com, 203.0.113.10, or 2001:db8::10. Do not include a URL scheme, path, or port. Press Enter.
4. Use the left and right arrow keys to choose Allow or Deny, then press Enter to add the rule to the list. New rules default to Deny.
5. Press Esc to return to Proxy and blocking, then press Esc again to return to the Network tab. Press Esc once more to save your changes and close the configuration.

To change a rule, select it and press Enter. To remove it, press x. Rules marked (managed) cannot be edited or removed. Changes are saved when you close the configuration.

When choosing rules, keep the following in mind:

• An allowed hostname matches that hostname only. Use *.example.com to match its subdomains, but not example.com itself. Use * to match every host.
• A denied domain also denies its subdomains. For example, denying example.com blocks both example.com and api.example.com.
• Deny takes precedence over Allow.
• Once you add an Allow rule, hosts that do not match an allowed entry are blocked, except for the automatic localhost entries described below. With no allow rules, other hosts remain allowed unless a deny rule or another network restriction blocks them.
• With at least one Allow rule, turning on both Allow outbound connections and Allow local network also permits localhost, 127.0.0.1, and ::1. These entries are added to the effective allowlist without changing your saved rules. Explicit Deny rules and enterprise allowlists can still block them.
• Enterprise rules can only narrow your allowlist, never widen it. A host is allowed only when both your rules and the enterprise rules permit it. If none of the hosts you allow are also allowed by the enterprise rules, nothing is left to permit. Every host is then denied. This is the one case where adding an Allow rule ends in a fully closed list. Copilot shows this state in the sandbox dialog and in the policy details.

Host rules use a local proxy, even if you have not configured an HTTP proxy. On macOS and Linux, the sandbox forces every connection through this proxy, so a program cannot avoid your host rules by connecting directly. On Windows, the sandbox relies on programs honoring the proxy settings. As a result, programs that ignore the proxy settings on Windows can connect directly and get around your host rules.

Routing traffic through an HTTP proxy

To send the sandbox's outbound traffic through a proxy server:

1. On the Network tab, select Proxy and blocking and press Enter. Then select Remote proxy and press Enter.
2. Enter the proxy URL, and optionally a Username and Password.

To remove the proxy, clear the URL.

Keep the following in mind:

• The proxy applies only while Allow outbound connections is turned on. If you turn outbound connections off, the proxy is kept in your settings but stays inactive.
• Use an HTTP or HTTPS URL without embedded credentials. Enter credentials in the separate Username and Password fields. On Linux, use an IPv4 address or a hostname with IPv4 support rather than an IPv6-only address.
• The CLI stores a literal password in your operating system's credential store when available, with a local file fallback. Your settings file holds a reference to the stored secret, not the password.
• You can enter ${VAR} or $VAR as the entire Password value to use an environment variable instead. The variable must be available to the CLI. If it is unset, no password is supplied, and a proxy that requires authentication can reject the request.
• The CLI connects through a built-in local proxy, which keeps the upstream proxy credentials out of sandboxed child processes. Host rules also apply when you use an upstream proxy.
• On macOS and Linux, sandboxed programs cannot bypass the proxy by connecting directly. On Windows, the sandbox relies on programs honoring the proxy settings. Windows also requires a supported version and Allow local network, which permits private-network access as well.
• Your organization can enforce the proxy URL through managed settings. When it does, the URL is shown as (managed), but you can still provide your own username and password.

Enabling and disabling the sandbox quickly

You can toggle the sandbox on or off without opening the full configuration interface:

• Enable: Enter /sandbox enable in the Copilot CLI session.
• Disable: Enter /sandbox disable in the Copilot CLI session.

Ordinarily, these commands change the saved Enable sandbox setting. If managed settings require sandboxing and permit bypass, /sandbox disable instead turns sandboxing off only for the current session. Running /sandbox enable restores it for that session.

Viewing your current sandbox settings

Settings are stored in settings.json under the sandbox key in your Copilot CLI configuration directory. Sandbox settings are not supported in repository-level settings files. Enterprise managed settings can restrict your choices. For more information about the configuration directory, see AUTOTITLE.

You can view your current sandbox settings from within a Copilot CLI session.

1. Enter /settings.
2. Press / to search for settings.
3. Type sandbox to filter the list of settings.

The steps above show your saved settings. 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—enter /sandbox policy. You can add a command, such as /sandbox policy npm install, to inspect its developer-tool access without running it. For more information, see AUTOTITLE.

Further reading

• AUTOTITLE
• AUTOTITLE
• AUTOTITLE