From 8b3a137084c5df030f555dedfe448e3e62ed923d Mon Sep 17 00:00:00 2001 From: Sarita Iyer <66540150+saritai@users.noreply.github.com> Date: Tue, 22 Sep 2026 20:46:33 +0000 Subject: [PATCH 1/2] Document local sandboxing public preview in the GitHub Copilot app (#63358) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../cloud-and-local-sandboxes.md | 3 +- .../about-cloud-and-local-sandboxes.md | 52 ++++--- .../agents/copilot-cli/about-copilot-cli.md | 3 +- .../understanding-local-sandboxing.md | 3 +- .../concepts/agents/github-copilot-app.md | 2 +- .../configuring-local-sandbox-settings.md | 3 +- ...g-cloud-sandboxes-for-your-organization.md | 4 +- .../using-local-sandboxing.md | 3 +- .../github-copilot-app/agent-sessions.md | 14 +- .../configure-local-sandboxing.md | 132 ++++++++++++++++++ .../how-tos/github-copilot-app/index.md | 1 + .../enterprise-managed-settings.md | 25 ++-- .../slash-commands.md | 1 + .../cli/public-preview-local-sandbox.md | 3 +- data/reusables/cli/public-preview-sandbox.md | 3 +- 15 files changed, 212 insertions(+), 40 deletions(-) create mode 100644 content/copilot/how-tos/github-copilot-app/configure-local-sandboxing.md diff --git a/content/billing/concepts/product-billing/cloud-and-local-sandboxes.md b/content/billing/concepts/product-billing/cloud-and-local-sandboxes.md index 7121d03d3572..bb1eac2d7736 100644 --- a/content/billing/concepts/product-billing/cloud-and-local-sandboxes.md +++ b/content/billing/concepts/product-billing/cloud-and-local-sandboxes.md @@ -10,7 +10,8 @@ category: - Understand product costs --- -{% data reusables.cli.public-preview-sandbox %} +> [!NOTE] +> {% data reusables.cli.public-preview-sandbox %} ## How sandbox usage is measured diff --git a/content/copilot/concepts/about-cloud-and-local-sandboxes.md b/content/copilot/concepts/about-cloud-and-local-sandboxes.md index bd9b9ade2b34..951e7f931b66 100644 --- a/content/copilot/concepts/about-cloud-and-local-sandboxes.md +++ b/content/copilot/concepts/about-cloud-and-local-sandboxes.md @@ -15,7 +15,8 @@ docsTeamMetrics: - copilot-cli --- -{% data reusables.cli.public-preview-sandbox %} +> [!NOTE] +> {% data reusables.cli.public-preview-sandbox %} ## Introduction @@ -24,7 +25,9 @@ docsTeamMetrics: Sandboxing is available in both {% data variables.copilot.copilot_cli %} and the {% data variables.copilot.github_copilot_app %}, but the two surfaces expose it differently: * In {% data variables.copilot.copilot_cli_short %}, you control both local and cloud sandboxing with the commands and settings described in this article. -* In the {% data variables.copilot.github_copilot_app %}, you choose cloud sandboxing when you start a new session, without running any commands. This feature is currently in {% data variables.release-phases.public_preview %} and subject to change. For more information, see [AUTOTITLE](/copilot/how-tos/github-copilot-app/agent-sessions#starting-a-session). +* In the {% data variables.copilot.github_copilot_app %}, you can run a session in a cloud sandbox or 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 [AUTOTITLE](/copilot/how-tos/github-copilot-app/agent-sessions#using-cloud-and-local-sandboxes). + +Local sandbox settings are configured separately in {% data variables.copilot.copilot_cli_short %} and the {% data variables.copilot.github_copilot_app %}. Enabling or configuring local sandboxing in one surface does not change it in the other. With sandboxing, you can choose where {% data variables.product.prodname_copilot_short %} runs: @@ -34,9 +37,11 @@ With sandboxing, you can choose where {% data variables.product.prodname_copilot ## Local sandboxing > [!NOTE] -> Local sandboxing is currently an experimental feature. To use it, start {% data variables.copilot.copilot_cli_short %} with the `‑‑experimental` command line option, or enter `/experimental on` during a session. +> +> * In {% data variables.copilot.copilot_cli_short %}, local sandboxing is currently an experimental feature. To use it, start the CLI with the `‑‑experimental` command line option, or enter `/experimental on` during a session. +> * In the {% data variables.copilot.github_copilot_app %}, local sandboxing is in {% data variables.release-phases.public_preview %} and subject to change. -Local sandboxing lets {% data variables.product.prodname_copilot_short %} run in a sandboxed environment directly on your machine, with restricted access to your filesystem, network connectivity, and system capabilities. You configure local sandboxing in {% data variables.copilot.copilot_cli_short %}, using the commands and settings described in the following sections. +Local sandboxing lets {% data variables.product.prodname_copilot_short %} 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 {% data variables.copilot.copilot_cli_short %} or the {% data variables.copilot.github_copilot_app %}. Local sandboxing is turned off by default. Until you enable it, the shell commands that {% data variables.product.prodname_copilot_short %} 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. @@ -60,11 +65,15 @@ After you enable local sandboxing, the commands and tools that an agent runs on 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. -For more information, see [AUTOTITLE](/copilot/how-tos/cloud-and-local-sandboxes/using-local-sandboxing). +For more information about enabling local sandboxing in {% data variables.copilot.copilot_cli_short %}, see [AUTOTITLE](/copilot/how-tos/cloud-and-local-sandboxes/using-local-sandboxing). + +In the {% data variables.copilot.github_copilot_app %}, project 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 project default. For more information, see [AUTOTITLE](/copilot/how-tos/github-copilot-app/configure-local-sandboxing). ### Configuring local sandboxing -You can use the default local sandboxing behavior, or you can modify what {% data variables.product.prodname_copilot_short %} can access. When you configure local sandboxing, you can control several dimensions of access: +You can use the default local sandboxing behavior, or modify what {% data variables.product.prodname_copilot_short %} can access. The available controls depend on the surface you use. + +In {% data variables.copilot.copilot_cli_short %}, you can control several dimensions of access: * **Filesystem**: Grant read-only or read/write access to specific paths, or deny paths. * **Network**: Allow or block outbound internet access and local network access independently. @@ -73,14 +82,26 @@ You can use the default local sandboxing behavior, or you can modify what {% dat * **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. -For more information, see [AUTOTITLE](/copilot/how-tos/cloud-and-local-sandboxes/configuring-local-sandbox-settings). +For more information about configuring local sandbox settings in {% data variables.copilot.copilot_cli_short %}, see [AUTOTITLE](/copilot/how-tos/cloud-and-local-sandboxes/configuring-local-sandbox-settings). + +In the {% data variables.copilot.github_copilot_app %}, project 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 {% data variables.product.prodname_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 project settings. For more information about configuring the project policy and changing sandboxing for an active local session, see [AUTOTITLE](/copilot/how-tos/github-copilot-app/configure-local-sandboxing). ### 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. {% data variables.copilot.copilot_cli_short %} applies a process-scoped profile to each sandboxed command. Use macOS 15 (Sequoia) or later. {% data variables.copilot.copilot_cli_short %} 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. +* **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** uses the BaseContainer tier of the ProcessContainer backend. {% data variables.copilot.copilot_cli_short %} does not use the AppContainer fallback tiers. If your Windows build cannot supply BaseContainer, {% data variables.copilot.copilot_cli_short %} reports that sandboxing is not supported. To find the supported Windows versions, see [Windows OS support for Copilot sandboxing](https://aka.ms/ghcp-sandbox-os-support). #### Proxy support @@ -88,19 +109,16 @@ Local sandboxing is available on macOS, on Linux, and on recent Windows 11 build The sandbox proxy operates differently on each operating system: * **macOS**: {% data variables.copilot.copilot_cli_short %} does not give the proxy to Seatbelt. It sets `HTTP_PROXY`, `HTTPS_PROXY`, and `ALL_PROXY` in the sandboxed environment instead. Only programs that obey these variables use the proxy. A program that ignores them connects directly. -* **Linux**: bubblewrap enforces the proxy. The sandbox gets a private network namespace, and only the proxy endpoint is permitted. This mode has more requirements. You must have: - * `slirp4netns` on your `PATH`. - * `unshare` and `nsenter` from util-linux 2.35 or later, with `--map-current-user` and `--keep-caps` support. - * `iptables` and `ip6tables`. Use the `nf_tables` backend. The legacy backend also operates, but only if you can write to `/run/xtables.lock`. - - Two more limits apply on Linux. The proxy must have an IPv4 address, because {% data variables.copilot.copilot_cli_short %} refuses a proxy that only IPv6 can reach. The proxy URL must not contain credentials, so give the credentials to the proxy itself. +* **Linux**: bubblewrap enforces the proxy. The sandbox gets a private network namespace, and only the proxy endpoint is permitted. The Linux requirements for outbound traffic listed in [Cross-platform support](#cross-platform-support) also apply when you configure an upstream proxy. The proxy must have an IPv4 address, because {% data variables.copilot.copilot_cli_short %} refuses a proxy that only IPv6 can reach. The proxy URL must not contain credentials, so give the credentials to the proxy itself. +* **Windows**: the proxy is not available. In {% data variables.copilot.copilot_cli_short %}, do not use denied paths either. If a CLI sandbox policy includes either setting, the sandboxed command fails with an error. In the {% data variables.copilot.github_copilot_app %}, you can save denied paths in the project 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. - Also on Linux, bubblewrap cannot control local network access independently of outbound access. Your local network setting therefore does not have a separate effect there. -* **Windows**: the proxy is not available. Do not use denied paths on Windows either. {% data variables.copilot.copilot_cli_short %} cannot enforce these settings, and the sandboxed command fails with an error. +On Linux, bubblewrap cannot control local network access independently for spawned processes, including shell commands and local MCP or LSP servers. In the {% data variables.copilot.github_copilot_app %}, the local network setting still applies to in-process operations, such as web requests and remote MCP connections. #### If your host does not support local sandboxing -{% data variables.copilot.copilot_cli_short %} turns the sandbox off for the session and shows a notice. Shell commands and sandboxed services then run without a sandbox, and your `sandbox.enabled` setting does not change. If your enterprise enforces sandboxing through device-managed settings, the session fails closed instead: sandboxed commands do not run. +In {% data variables.copilot.copilot_cli_short %}, the sandbox is turned off for the session and a notice is displayed. Shell commands and sandboxed services then run without a sandbox, and your `sandbox.enabled` setting does not change. If your enterprise enforces sandboxing through device-managed settings, the session fails closed instead: sandboxed commands do not run. + +In the {% data variables.copilot.github_copilot_app %}, host 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. ### Enterprise policy enforcement diff --git a/content/copilot/concepts/agents/copilot-cli/about-copilot-cli.md b/content/copilot/concepts/agents/copilot-cli/about-copilot-cli.md index 42bf4227d625..7644f7c7f790 100644 --- a/content/copilot/concepts/agents/copilot-cli/about-copilot-cli.md +++ b/content/copilot/concepts/agents/copilot-cli/about-copilot-cli.md @@ -65,7 +65,8 @@ To use the CLI programmatically, include the `-p` or `--prompt` command-line opt ## Running {% data variables.copilot.copilot_cli_short %} commands in a sandbox -{% data reusables.cli.public-preview-sandbox %} +> [!NOTE] +> {% data reusables.cli.public-preview-sandbox %} To prevent {% data variables.product.prodname_copilot_short %} from modifying files you don't want it to touch, you can force agents to run commands within a local sandboxed environment. Alternatively, you can run an entire CLI session in an isolated environment in the cloud. For more information, see [AUTOTITLE](/copilot/concepts/about-cloud-and-local-sandboxes). diff --git a/content/copilot/concepts/agents/copilot-cli/understanding-local-sandboxing.md b/content/copilot/concepts/agents/copilot-cli/understanding-local-sandboxing.md index 274c0199f5f0..8eeb74a27c35 100644 --- a/content/copilot/concepts/agents/copilot-cli/understanding-local-sandboxing.md +++ b/content/copilot/concepts/agents/copilot-cli/understanding-local-sandboxing.md @@ -13,7 +13,8 @@ docsTeamMetrics: - copilot-cli --- -{% data reusables.cli.public-preview-local-sandbox %} +> [!NOTE] +> {% data reusables.cli.public-preview-local-sandbox %} {% data reusables.cli.sandbox-on-windows %} diff --git a/content/copilot/concepts/agents/github-copilot-app.md b/content/copilot/concepts/agents/github-copilot-app.md index d8e5e66b56e5..d1f9212444d1 100644 --- a/content/copilot/concepts/agents/github-copilot-app.md +++ b/content/copilot/concepts/agents/github-copilot-app.md @@ -40,7 +40,7 @@ The {% data variables.copilot.github_copilot_app %} supports the following opera ## What can I do with the {% data variables.copilot.github_copilot_app %}? -* **Parallel workspaces:** Run multiple isolated agent sessions simultaneously, each with a dedicated git worktree and branch. When you start a new agent session you can choose to run it in a cloud-based sandbox (public preview) hosted by {% data variables.product.github %}. For more information, see [AUTOTITLE](/copilot/how-tos/github-copilot-app/agent-sessions#starting-a-session). +* **Parallel workspaces:** Run multiple isolated agent sessions simultaneously, each with a dedicated git worktree and branch. You can run a session in a cloud sandbox, or configure a local sandbox to restrict the resources available to agent-run tools on your machine. For more information, see [AUTOTITLE](/copilot/how-tos/github-copilot-app/agent-sessions#using-cloud-and-local-sandboxes). * **Session modes:** Choose how you work with agents: Interactive (collaborative), Plan (agent plans, you approve), or Autopilot (fully autonomous). You can also select from multiple LLMs and adjust reasoning effort for each session. * **Model selection:** Select from multiple LLMs, including models from your own provider using bring your own key (BYOK), and adjust reasoning effort for each session. * **{% data variables.product.github %} integration:** Browse and find issues, start sessions from them, create and close pull requests, review pull requests, view CI check results, and search across your repositories—all within the app. diff --git a/content/copilot/how-tos/cloud-and-local-sandboxes/configuring-local-sandbox-settings.md b/content/copilot/how-tos/cloud-and-local-sandboxes/configuring-local-sandbox-settings.md index 4ff11183a735..ed07dff20f2a 100644 --- a/content/copilot/how-tos/cloud-and-local-sandboxes/configuring-local-sandbox-settings.md +++ b/content/copilot/how-tos/cloud-and-local-sandboxes/configuring-local-sandbox-settings.md @@ -12,7 +12,8 @@ docsTeamMetrics: - copilot-cli --- -{% data reusables.cli.public-preview-local-sandbox %} +> [!NOTE] +> {% data reusables.cli.public-preview-local-sandbox %} {% data reusables.cli.sandbox-on-windows %} diff --git a/content/copilot/how-tos/cloud-and-local-sandboxes/enabling-or-disabling-cloud-sandboxes-for-your-organization.md b/content/copilot/how-tos/cloud-and-local-sandboxes/enabling-or-disabling-cloud-sandboxes-for-your-organization.md index 9514ea525fb9..fae69f376147 100644 --- a/content/copilot/how-tos/cloud-and-local-sandboxes/enabling-or-disabling-cloud-sandboxes-for-your-organization.md +++ b/content/copilot/how-tos/cloud-and-local-sandboxes/enabling-or-disabling-cloud-sandboxes-for-your-organization.md @@ -13,7 +13,8 @@ category: - Manage cloud and local sandboxes for your organization --- -{% data reusables.cli.public-preview-sandbox %} +> [!NOTE] +> {% data reusables.cli.public-preview-sandbox %} ## About enabling and disabling cloud sandboxes @@ -49,4 +50,3 @@ Enterprise owners can control cloud sandbox access for all organizations in the * [AUTOTITLE](/copilot/concepts/about-cloud-and-local-sandboxes) * [AUTOTITLE](/billing/concepts/product-billing/cloud-and-local-sandboxes) * [AUTOTITLE](/copilot/reference/enterprise-administrators/enterprise-managed-settings#sandbox) - diff --git a/content/copilot/how-tos/cloud-and-local-sandboxes/using-local-sandboxing.md b/content/copilot/how-tos/cloud-and-local-sandboxes/using-local-sandboxing.md index 6bbf5a7a7693..566d5641a123 100644 --- a/content/copilot/how-tos/cloud-and-local-sandboxes/using-local-sandboxing.md +++ b/content/copilot/how-tos/cloud-and-local-sandboxes/using-local-sandboxing.md @@ -12,7 +12,8 @@ docsTeamMetrics: - copilot-cli --- -{% data reusables.cli.public-preview-local-sandbox %} +> [!NOTE] +> {% data reusables.cli.public-preview-local-sandbox %} {% data reusables.cli.sandbox-on-windows %} diff --git a/content/copilot/how-tos/github-copilot-app/agent-sessions.md b/content/copilot/how-tos/github-copilot-app/agent-sessions.md index 2befb73b7a90..6b5863871b9b 100644 --- a/content/copilot/how-tos/github-copilot-app/agent-sessions.md +++ b/content/copilot/how-tos/github-copilot-app/agent-sessions.md @@ -19,7 +19,7 @@ Each session in the {% data variables.copilot.github_copilot_app %} runs in its 1. In the sidebar, next to **Projects**, click {% octicon "plus" aria-label="Start a new session" %}. 1. Choose a project—you can use a folder already on your machine, choose from {% data variables.product.github %}, or clone from a Git URL for repositories hosted outside {% data variables.product.github %} (for example, on Azure DevOps) or for private repositories without app access. -1. From the dropdown under the prompt box, choose where the session should run: in a new working tree, in your local repository, or in a cloud sandbox. Cloud sandboxes for {% data variables.product.prodname_copilot_short %} (public preview) are fully isolated environments hosted by {% data variables.product.github %}. +1. From the dropdown under the prompt box, choose where the session should run: in a new working tree, in your local repository, or in a cloud sandbox. Cloud sandboxes are fully isolated environments hosted by {% data variables.product.github %}. 1. Select a session mode, model, and reasoning effort from the dropdowns below the prompt field. If you choose **Auto** for the model, the app selects the optimal model for your task based on task complexity. 1. Describe the task in the prompt field. You can reference issues with `#`, add files with `@`, or use `/` for commands. @@ -60,6 +60,18 @@ Use **Manage sessions** to view, search, and filter sessions and chats, includin 1. Search or filter to find the sessions or chats you want to manage. 1. Select one or more sessions or chats, then archive or delete them. To restore an archived chat, find the chat, then restore it. +## Using cloud and local sandboxes + +> [!NOTE] +> {% data reusables.cli.public-preview-sandbox %} + +Cloud and local sandboxes protect sessions in different ways: + +* **Cloud sandbox**: Runs the entire session in an isolated environment hosted by {% data variables.product.github %}. Use a cloud sandbox when you want to keep the session off your machine or run several resource-intensive tasks in parallel. Choose the cloud sandbox execution location when starting a session. +* **Local sandbox**: Runs the session on your machine, but restricts the filesystem, network, and credential access available to agent-run tools. Use local sandboxing when the agent needs your local tools or development services, but you want to limit its access to the rest of your machine. Configure the default for new local repository and working tree sessions in the project settings, or use `/sandbox on` or `/sandbox off` to change an active local session. + +Local sandboxing does not apply to cloud sandbox sessions or sessions that run on a remote host. For more information about how both types of sandbox work, see [AUTOTITLE](/copilot/concepts/about-cloud-and-local-sandboxes). To enable and configure local sandboxing, see [AUTOTITLE](/copilot/how-tos/github-copilot-app/configure-local-sandboxing). + ## Using `/security-review` in app sessions > [!NOTE] diff --git a/content/copilot/how-tos/github-copilot-app/configure-local-sandboxing.md b/content/copilot/how-tos/github-copilot-app/configure-local-sandboxing.md new file mode 100644 index 000000000000..f7b9c49116c0 --- /dev/null +++ b/content/copilot/how-tos/github-copilot-app/configure-local-sandboxing.md @@ -0,0 +1,132 @@ +--- +title: Configuring local sandboxing in the GitHub Copilot app +shortTitle: Configure local sandboxing +intro: 'Use the `/sandbox` slash command and project settings in the {% data variables.copilot.github_copilot_app %} to control how local sandboxing restricts filesystem access, network connectivity, and credential use.' +product: '{% data reusables.gated-features.github-app %}
Download {% data variables.copilot.github_copilot_app %} {% octicon "link-external" height:16 %}' +versions: + feature: copilot +contentType: how-tos +category: + - Configure Copilot +--- + +> [!NOTE] +> {% data reusables.cli.public-preview-local-sandbox %} + +## About local sandboxing + +Local sandboxing runs the tools that an agent invokes on your behalf inside an operating-system sandbox. This reduces the potential impact of an unintended command by limiting access to files, network resources, and credentials on your machine. + +You configure local sandboxing separately for each project in the {% data variables.copilot.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. + +For an overview of cloud and local sandboxing for {% data variables.product.prodname_copilot_short %}, see [AUTOTITLE](/copilot/concepts/about-cloud-and-local-sandboxes). + +## Enabling local sandboxing in a project + +Local sandboxing is turned off by default. To enable it for new local sessions in a project: + +1. Open the app settings. +1. Select the project that you want to configure. +1. 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 most projects, start with the default policy. It allows 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. + +In the project settings, you can configure: + +* [**Filesystem access**](#configuring-filesystem-access): Grant additional read-only or read/write access to specific paths, or deny paths. +* [**Network access**](#configuring-network-access): Allow or block outbound internet and local network access. +* [**Credentials**](#configuring-credentials): Choose whether your Git and {% data variables.product.prodname_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, sandboxed sessions can connect to the internet and your local network. In the **Sandbox** section of the project settings, you can change the following settings: + +* **Outbound internet**: Allow connections to internet services, such as {% data variables.product.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, the sandbox cannot control local network access independently 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. + +### Configuring credentials + +By default, authenticated Git and {% data variables.product.prodname_cli %} operations are available inside the sandbox. You can turn off either of the following settings: + +* **Git credentials**: Allow authenticated HTTPS Git operations. +* **{% data variables.product.prodname_cli %} credentials**: Allow {% data variables.product.prodname_cli %} 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: + +```text +/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](https://aka.ms/ghcp-sandbox-os-support). + +If the app displays **Sandbox unavailable**, address the reported problem, then click **Retry sandbox**. + +## Changing sandboxing for a session + +To turn on local sandboxing for an active session, enter: + +```text +/sandbox on +``` + +To turn it off for the session, enter: + +```text +/sandbox off +``` + +During an active local session, the command creates a persistent override for that session and applies it immediately. The override does not change the project default for other sessions. + +If you enter either command before a session starts, the command changes the project default inherited by new sessions. + +When local sandboxing is off, agent-run commands can access the same files, networks, and credentials as your user account. + +You cannot use local sandboxing for a cloud sandbox session or a session that runs on a remote host. + +## Running a tool outside the sandbox + +If a tool needs access that the sandbox policy does not allow, the app can display a **Run outside the sandbox?** prompt. Depending on the effective policy, you can: + +* Cancel the operation. +* Run the operation once outside the sandbox. +* Disable sandboxing for the remainder of the current session and run the operation. + +If you disable sandboxing from this prompt, the app displays **Sandbox off for this session**. Click **Re-enable sandbox** to turn it back on. + +Temporarily disabling sandboxing does not change the project default or the session override. It ends when the session restarts or reattaches. + +An enterprise owner can prevent users from running tools outside the sandbox. For more information, see [AUTOTITLE](/copilot/reference/enterprise-administrators/enterprise-managed-settings#sandbox). diff --git a/content/copilot/how-tos/github-copilot-app/index.md b/content/copilot/how-tos/github-copilot-app/index.md index 4788e81aabaa..ce6ddb5339f5 100644 --- a/content/copilot/how-tos/github-copilot-app/index.md +++ b/content/copilot/how-tos/github-copilot-app/index.md @@ -18,6 +18,7 @@ redirect_from: children: - /customize-github-copilot-app - /agent-sessions + - /configure-local-sandboxing - /working-with-canvas-extensions - /managing-issues-and-pull-requests - /using-automations diff --git a/content/copilot/reference/enterprise-administrators/enterprise-managed-settings.md b/content/copilot/reference/enterprise-administrators/enterprise-managed-settings.md index efdf3aca7709..4f700e8d272a 100644 --- a/content/copilot/reference/enterprise-administrators/enterprise-managed-settings.md +++ b/content/copilot/reference/enterprise-administrators/enterprise-managed-settings.md @@ -32,7 +32,7 @@ For instructions on creating the file, see [AUTOTITLE](/copilot/how-tos/administ | `remoteControl` | Restricts whether sessions hosted on this device can be remotely controlled, based on the controlling client's SSO authorization status for the listed organizations. Doesn't affect the user's ability to remotely control sessions hosted on other devices | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} | {% octicon "x" aria-label="Not supported" %} | | `allowedMcpServers` | Defines an allowlist of MCP servers permitted to run. Any server not matched is blocked. Omit to allow all servers, subject to any deny rules | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | | `deniedMcpServers` | Defines MCP servers that are unconditionally blocked, even if they also match an entry in `allowedMcpServers` | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | -| `sandbox` | Enforces minimum local sandbox restrictions for command execution, filesystem and network access, credentials, and local MCP and LSP servers | {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} | {% octicon "x" aria-label="Not supported" %} | {% octicon "x" aria-label="Not supported" %} | {% octicon "x" aria-label="Not supported" %} | +| `sandbox` | Enforces minimum local sandbox restrictions for command execution, filesystem and network access, credentials, and local MCP and LSP servers | {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} | {% octicon "x" aria-label="Not supported" %} | {% endrowheaders %} @@ -267,22 +267,24 @@ Each entry uses the same `serverName`, `serverUrl`, or `serverCommand` propertie ## `sandbox` -Enforces minimum local sandbox restrictions for {% data variables.copilot.copilot_cli_short %}. Managed sandbox settings impose restrictions rather than defaults: +Enforces minimum local sandbox restrictions for {% data variables.copilot.copilot_cli_short %} and the {% data variables.copilot.github_copilot_app %}. Managed sandbox settings impose restrictions rather than defaults: * For force-on settings, a managed value of `true` enforces the setting. `false` or omission leaves the user's configuration unchanged. * For capability settings, a managed value of `false` prohibits the capability. `true` or omission leaves the user's configuration unchanged. * Managed read/write and read-only path lists restrict user-configured grants, while managed denied paths add to user-configured denials. +In app sessions, the embedded runtime parses, combines, and enforces the complete managed `sandbox` object, including properties that are not available in the app's project settings. The app displays the user's project settings, not the complete effective managed policy, and does not show per-setting managed locks. + The following sub-properties are supported: -* `enabled`: `true` requires sandboxing by default. Users cannot disable it through their configuration or the `--no-sandbox` command line option. If the effective policy permits bypass, a user can still explicitly disable sandboxing for the rest of the current session, either from an active sandbox-bypass permission prompt or by running the `/sandbox disable` command. This session opt-out does not loosen the saved policy. +* `enabled`: `true` requires sandboxing by default. Users cannot disable it through their configuration. In {% data variables.copilot.copilot_cli_short %}, the `--no-sandbox` command line option and `/sandbox disable` command cannot override it. In the {% data variables.copilot.github_copilot_app %}, the project setting and `/sandbox off` command cannot override it. If the effective policy permits bypass, a user can still explicitly disable sandboxing for the rest of the current session from an active sandbox-bypass permission prompt. * `failIfUnavailable`: `true`, combined with `enabled: true`, makes the managed sandbox mandatory. If {% data variables.product.prodname_copilot_short %} cannot validate, compile, or enforce the sandbox policy with an available sandbox backend, it blocks model and tool execution instead of allowing commands to fail or run unsandboxed. This property does not enable sandboxing by itself. -* `allowBypass`: `false` prevents individual commands from running outside the sandbox and prevents users from disabling sandboxing for the rest of the current session, whether from an active sandbox-bypass permission prompt or by running `/sandbox disable`. -* `addCurrentWorkingDirectory`: `false` prevents {% data variables.copilot.copilot_cli_short %} from automatically adding the current working directory to the sandbox's read/write paths. -* `sandboxMcpServers`: `true` requires local MCP servers started by {% data variables.copilot.copilot_cli_short %} to run in the sandbox. Remote MCP servers do not run in the local sandbox. -* `sandboxLspServers`: `true` requires language servers started by {% data variables.copilot.copilot_cli_short %} to run in the sandbox. -* `gitAuth`: `false` prevents {% data variables.copilot.copilot_cli_short %} from injecting a {% data variables.product.github %} token for authenticated Git HTTPS operations in the sandbox. -* `ghAuth`: `false` prevents {% data variables.copilot.copilot_cli_short %} from injecting a {% data variables.product.github %} token for {% data variables.product.prodname_cli %} in the sandbox. +* `allowBypass`: `false` prevents individual commands from running outside the sandbox and prevents users from disabling sandboxing for the rest of the current session from an active sandbox-bypass permission prompt. In {% data variables.copilot.copilot_cli_short %}, it also prevents users from disabling sandboxing with `/sandbox disable`. +* `addCurrentWorkingDirectory`: `false` prevents the runtime from automatically adding the current working directory to the sandbox's read/write paths. +* `sandboxMcpServers`: `true` requires local MCP servers started in the session to run in the sandbox. Remote MCP servers do not run in the local sandbox. +* `sandboxLspServers`: `true` requires language servers started in the session to run in the sandbox. +* `gitAuth`: `false` prevents the runtime from injecting a {% data variables.product.github %} token for authenticated Git HTTPS operations in the sandbox. +* `ghAuth`: `false` prevents the runtime from injecting a {% data variables.product.github %} token for {% data variables.product.prodname_cli %} in the sandbox. * `allowDevToolAccess`: `false` prevents automatic access to development-tool configuration, caches, registries, and toolchains. These locations can contain package registry credentials or tokens. Disabling access can cause package restoration, authenticated registry operations, or builds that use shared caches to fail unless you explicitly grant the required paths. * `userPolicy`: An object that configures filesystem, network, and macOS-specific Seatbelt restrictions. The supported properties are described in the following sections. @@ -300,8 +302,11 @@ Configures network access for sandboxed processes. * `allowOutbound`: `false` blocks outbound network access. * `allowLocalNetwork`: `false` prevents access to the local network. +* `allowedHosts`: An array of hostnames or IP addresses that sandboxed processes are allowed to reach. A non-empty list blocks hosts that do not match. Entries can be exact hostnames, exact IP addresses, `*.example.com` for subdomains, or `*` for every host. +* `blockedHosts`: An array of hostnames or IP addresses that sandboxed processes cannot reach. Blocked hosts take precedence over allowed hosts, and blocking a domain also blocks its subdomains. +* `proxy`: An object that routes sandboxed network traffic through an upstream HTTP proxy. Set `proxy.url` to the proxy URL. Platform support and enforcement vary. -Network behavior varies by operating system. In particular, a proxy is not a complete egress-control boundary because some applications can ignore proxy settings. +Network behavior varies by operating system. In particular, an upstream proxy is not a complete egress-control boundary because some applications can ignore proxy settings. ### `sandbox.userPolicy.seatbelt` diff --git a/content/copilot/reference/github-copilot-app-reference/slash-commands.md b/content/copilot/reference/github-copilot-app-reference/slash-commands.md index ef95e33c8aa7..eebbfcc6cc52 100644 --- a/content/copilot/reference/github-copilot-app-reference/slash-commands.md +++ b/content/copilot/reference/github-copilot-app-reference/slash-commands.md @@ -66,6 +66,7 @@ Some commands require specific context, such as an active session, session chang | `/restart-session` | **Requires an active session.** Restarts the current session and keeps its history. | | `/review` | **Requires an active session.** Reviews the current session's changes. | | `/rubber-duck [PROMPT]` | Requests critique on your approach or implementation by a model other than the one you have used in the session. See [AUTOTITLE](/copilot/how-tos/github-copilot-app/agent-sessions#using-the-rubber-duck-agent). | +| `/sandbox on` or `/sandbox off` | Enables or disables local sandboxing for the current session. If no session is active, changes the selected project's default for new sessions. Local sandboxing is not available for cloud sandbox or remote-host sessions. See [AUTOTITLE](/copilot/how-tos/github-copilot-app/configure-local-sandboxing#changing-sandboxing-for-a-session). | | `/security-review` | **Requires an active session with changes.** Runs a security-focused review against current diffs. See [AUTOTITLE](/copilot/how-tos/github-copilot-app/agent-sessions#using-security-review-in-app-sessions). | | `/skills` | Manages skills; use `/skills reload` to reload skills mid-session. | | `/spar [PROMPT]` | Runs adversarial reasoning to challenge your approach. | diff --git a/data/reusables/cli/public-preview-local-sandbox.md b/data/reusables/cli/public-preview-local-sandbox.md index 1f3bc35b4ddd..4167a20927d3 100644 --- a/data/reusables/cli/public-preview-local-sandbox.md +++ b/data/reusables/cli/public-preview-local-sandbox.md @@ -1,2 +1 @@ -> [!NOTE] -> Local sandboxes for {% data variables.product.prodname_copilot %} are in {% data variables.release-phases.public_preview %} and subject to change. +Local sandboxes for {% data variables.product.prodname_copilot %} are in {% data variables.release-phases.public_preview %} and subject to change. diff --git a/data/reusables/cli/public-preview-sandbox.md b/data/reusables/cli/public-preview-sandbox.md index fee461494b0d..7633a7a94222 100644 --- a/data/reusables/cli/public-preview-sandbox.md +++ b/data/reusables/cli/public-preview-sandbox.md @@ -1,2 +1 @@ -> [!NOTE] -> Cloud and local sandboxes for {% data variables.product.prodname_copilot %} are in {% data variables.release-phases.public_preview %} and subject to change. +Cloud and local sandboxes for {% data variables.product.prodname_copilot %} are in {% data variables.release-phases.public_preview %} and subject to change. From f8999ea3601e7e15574499d9d7c1bf3db9fe04c7 Mon Sep 17 00:00:00 2001 From: Seb Date: Tue, 22 Sep 2026 20:49:03 +0000 Subject: [PATCH 2/2] docs(notifications): update retention period (#63373) Co-authored-by: Ben Ahmady <32935794+subatoi@users.noreply.github.com> Copilot-Session: fb939a70-dd7e-46c2-8022-d75e0d607c00 --- .../concepts/about-notifications.md | 2 +- .../get-started/configuring-notifications.md | 2 +- .../managing-notifications-from-your-inbox.md | 4 ++-- .../triaging-a-single-notification.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/content/subscriptions-and-notifications/concepts/about-notifications.md b/content/subscriptions-and-notifications/concepts/about-notifications.md index acddff2f0221..e0e00c33bbcf 100644 --- a/content/subscriptions-and-notifications/concepts/about-notifications.md +++ b/content/subscriptions-and-notifications/concepts/about-notifications.md @@ -90,7 +90,7 @@ To focus on a group of notifications in your inbox, you can create custom filter ## Notification retention policy -Notifications that are not marked as **Saved** are kept for 5 months. Notifications marked as **Saved** are kept indefinitely. If your saved notification is older than 5 months and you unsave it, the notification will disappear from your inbox within a day. +Notifications that are not marked as **Saved** are kept for 3 months. Notifications marked as **Saved** are kept indefinitely. If your saved notification is older than 3 months and you unsave it, the notification will disappear from your inbox within a day. ## Feedback and support diff --git a/content/subscriptions-and-notifications/get-started/configuring-notifications.md b/content/subscriptions-and-notifications/get-started/configuring-notifications.md index 362701eafc8e..6c927c9b231e 100644 --- a/content/subscriptions-and-notifications/get-started/configuring-notifications.md +++ b/content/subscriptions-and-notifications/get-started/configuring-notifications.md @@ -54,7 +54,7 @@ In addition, you can receive and triage notifications on your mobile device with ### Benefits of using an email client for notifications -One benefit of using an email client is that all of your notifications can be kept indefinitely depending on your email client's storage capacity. Your inbox notifications are only kept for 5 months on {% data variables.product.prodname_dotcom %} unless you've marked them as **Saved**. **Saved** notifications are kept indefinitely. For more information about your inbox's retention policy, see [AUTOTITLE](/subscriptions-and-notifications/concepts/about-notifications#notification-retention-policy). +One benefit of using an email client is that all of your notifications can be kept indefinitely depending on your email client's storage capacity. Your inbox notifications are only kept for 3 months on {% data variables.product.prodname_dotcom %} unless you've marked them as **Saved**. **Saved** notifications are kept indefinitely. For more information about your inbox's retention policy, see [AUTOTITLE](/subscriptions-and-notifications/concepts/about-notifications#notification-retention-policy). Sending notifications to your email client also allows you to customize your inbox according to your email client's settings, which can include custom or color-coded labels. diff --git a/content/subscriptions-and-notifications/how-tos/viewing-and-triaging-notifications/managing-notifications-from-your-inbox.md b/content/subscriptions-and-notifications/how-tos/viewing-and-triaging-notifications/managing-notifications-from-your-inbox.md index 2a83bf76ed23..a967472a7468 100644 --- a/content/subscriptions-and-notifications/how-tos/viewing-and-triaging-notifications/managing-notifications-from-your-inbox.md +++ b/content/subscriptions-and-notifications/how-tos/viewing-and-triaging-notifications/managing-notifications-from-your-inbox.md @@ -36,8 +36,8 @@ You have several options for triaging notifications from your inbox. | Triaging option | Description | |-----------------|-------------| -| Save | Saves your notification for later review. To save a notification, to the right of the notification, click {% octicon "bookmark" aria-label="Save" %}.

Saved notifications are kept indefinitely and can be viewed by clicking **Saved** in the sidebar or with the `is:saved` query. If your saved notification is older than 5 months and becomes unsaved, the notification will disappear from your inbox within a day. | -| Done | Marks a notification as completed and removes the notification from your inbox. You can see all completed notifications by clicking **Done** in the sidebar or with the `is:done` query. Notifications marked as **Done** are saved for 5 months. +| Save | Saves your notification for later review. To save a notification, to the right of the notification, click {% octicon "bookmark" aria-label="Save" %}.

Saved notifications are kept indefinitely and can be viewed by clicking **Saved** in the sidebar or with the `is:saved` query. If your saved notification is older than 3 months and becomes unsaved, the notification will disappear from your inbox within a day. | +| Done | Marks a notification as completed and removes the notification from your inbox. You can see all completed notifications by clicking **Done** in the sidebar or with the `is:done` query. Notifications marked as **Done** are saved for 3 months. | Unsubscribe | Automatically removes the notification from your inbox and unsubscribes you from the conversation until you are @mentioned, a team you're on is @mentioned, or you're requested for review. | Read | Marks a notification as read. To only view read notifications in your inbox, use the `is:read` query. This query doesn't include notifications marked as **Done**. | Unread | Marks notification as unread. To only view unread notifications in your inbox, use the `is:unread` query. | diff --git a/content/subscriptions-and-notifications/how-tos/viewing-and-triaging-notifications/triaging-a-single-notification.md b/content/subscriptions-and-notifications/how-tos/viewing-and-triaging-notifications/triaging-a-single-notification.md index b45026377808..8c51a497e493 100644 --- a/content/subscriptions-and-notifications/how-tos/viewing-and-triaging-notifications/triaging-a-single-notification.md +++ b/content/subscriptions-and-notifications/how-tos/viewing-and-triaging-notifications/triaging-a-single-notification.md @@ -19,7 +19,7 @@ category: To save a single notification to review later, to the right of the notification, click {% octicon "bookmark" aria-label="Save" %}. You can only save one notification at a time. -Saved notifications are kept indefinitely and can be viewed by clicking **Saved** in the sidebar or with the `is:saved` query. If your saved notification is older than 5 months and becomes unsaved, the notification will disappear from your inbox within a day. +Saved notifications are kept indefinitely and can be viewed by clicking **Saved** in the sidebar or with the `is:saved` query. If your saved notification is older than 3 months and becomes unsaved, the notification will disappear from your inbox within a day. ![Screenshot of a single notification from the "Notifications" page. The bookmark icon is highlighted with an orange outline.](/assets/images/help/notifications-v2/save-triaging-option.png)