Document enterprise managed settings for sandboxes (#62493)

Co-authored-by: hubwriter <hubwriter@github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Andy Feller <andyfeller@github.com>
Copilot-Session: 39cc466b-6286-4c9e-8aa7-2cc0eb953158
Copilot-Session: 63f86a27-25f1-4d38-a95f-090418d5b523

Author: 5 people

content/copilot/concepts/about-cloud-and-local-sandboxes.md

@@ -51,7 +51,7 @@ To enable local sandboxing inside a {% data variables.copilot.copilot_cli_short
 /sandbox enable
 ```
 
-After you enable local sandboxing, the commands and tools that an agent runs on your behalf—shell commands, file search, and, by default, the MCP and language (LSP) servers the CLI starts—run inside an operating-system-level sandbox, limiting their access to your system. The CLI continues to use local sandboxing whenever you use the CLI in future—for programmatic as well as interactive use—until you run `/sandbox disable` to disable it.
+After you enable local sandboxing, the commands and tools that an agent runs on your behalf—shell commands, file search, and, by default, the MCP and language (LSP) servers the CLI starts—run inside an operating-system-level sandbox, limiting their access to your system. The CLI continues to use local sandboxing whenever you use the CLI in future—for programmatic as well as interactive use—until you run `/sandbox disable` to disable it. If enterprise managed settings require sandboxing, you cannot disable it.
 
 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.
 
@@ -78,11 +78,9 @@ Local sandboxing is available on macOS and Linux, and on Windows Insiders builds
 * **Linux** uses the bubblewrap backend, which requires the `bwrap` command to be installed and available on your `PATH`. If `/sandbox` reports that sandboxing isn't supported on Linux, install bubblewrap.
 * **Windows** uses the ProcessContainer backend.
 
-Because each platform uses a different backend, a few policy options behave differently. Most notably, on Windows the sandbox cannot block individual paths, so any denied-path rules you add are ignored there. Instead of denying a path on Windows, grant access only to the specific directories that {% data variables.product.prodname_copilot_short %} needs, rather than granting a broad directory and then trying to exclude part of it. This keeps a sensitive location out of the sandbox's reach even though denied paths aren't enforced. Denied paths are enforced on macOS and Linux.
-
 ### Enterprise policy enforcement
 
-For organizations and enterprises, local sandbox policies can be centrally configured and enforced using Microsoft Intune and other MDM (mobile device management) platforms. This gives administrators control over how {% data variables.product.prodname_copilot_short %} interacts with local resources across managed devices. See [Deploying MDM-managed settings](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/configure-enterprise-managed-settings#deploying-mdm-managed-settings).
+Enterprises can require local sandboxing and enforce its configuration through server-managed, MDM-managed, or file-based managed settings. See [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/configure-enterprise-managed-settings).
 
 ## Cloud sandboxing
 

content/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/configure-enterprise-managed-settings.md

@@ -24,9 +24,9 @@ The following clients are supported, although not every client supports every pr
 * The {% data variables.copilot.github_copilot_app %}
 * {% data variables.copilot.copilot_cloud_agent %}
 
-These settings apply enterprise-wide and enterprises can customize specific keys to enterprise teams. For each supported key, the `{% data variables.copilot.managed_setting_file %}` value takes precedence over any file-based configuration a user sets in their client.
+These settings apply enterprise-wide and enterprises can customize specific keys to enterprise teams. For most supported keys, the `{% data variables.copilot.managed_setting_file %}` value takes precedence over any file-based configuration a user sets in their client. In {% data variables.copilot.copilot_cli_short %}, managed `sandbox` settings instead define minimum restrictions that users can further tighten but cannot loosen.
 
-Managed settings are loaded locally when the client starts, even if the device has no network connection. This means controls such as suppressing the `allow-all` permission options and restricting plugin configuration still apply before sign in or any server round trip, and remain active when users switch accounts.
+MDM-managed and file-based settings are loaded from the device, so they can apply before sign in or a server round trip and remain active when users switch accounts. Server-managed settings are associated with the user's signed-in account.
 
 ## Defining settings
 
@@ -42,6 +42,8 @@ There are multiple ways to deploy enterprise managed settings. Use the following
 * **MDM-managed**: Best when IT teams need device-group targeting through existing MDM tooling on macOS and Windows. Local clients only.
 * **File-based**: Available on all platforms, and useful when server-managed and MDM-managed deployment are not available, including developer environments such as containers and {% data variables.product.prodname_codespaces %}. Local clients only.
 
+In {% data variables.copilot.copilot_cli_short %}, if a request for server-managed settings fails and no cached response is available, the server-managed policy is unavailable for that session. For restrictions that must remain available without a server response, use MDM-managed or file-based settings.
+
 There are additional considerations if you use a dedicated enterprise for {% data variables.copilot.copilot_business_short %}. See [Guidance for dedicated {% data variables.copilot.copilot_business_short %} enterprises](#guidance-for-dedicated-copilot-business-enterprises).
 
 ## Deploying server-managed settings
@@ -50,7 +52,7 @@ There are additional considerations if you use a dedicated enterprise for {% dat
 1. In the repository, create or update `copilot/{% data variables.copilot.managed_setting_file %}`.
 1. Add your enterprise policy keys and values in JSON format.
 1. Commit and push your changes to the default branch.
-1. Confirm that enterprise users are running a supported client. Updated settings are applied automatically within about an hour, or immediately after the client restarts or the user signs in again.
+1. Confirm that enterprise users are running a supported client. Updated settings are applied automatically within about an hour. Restarting the client or signing in again triggers an immediate refresh.
 
 ## Overriding settings for specific teams
 
@@ -95,8 +97,29 @@ For example, to defer both `model` and `disableBypassPermissionsMode`:
 
 ## Deploying MDM-managed settings
 
-1. Create or update your `{% data variables.copilot.managed_setting_file %}` payload using the same JSON schema used for server-managed settings.
-1. Deploy the payload using your enterprise MDM platform and standard rollout process.
+Native MDM delivery uses the same logical keys and values as server-managed settings, but it does not deploy a `{% data variables.copilot.managed_setting_file %}` file. Instead, your MDM platform deploys individual settings as operating-system-managed string values.
+
+Native MDM delivery is available on Windows and macOS:
+
+| Operating system | Native policy location |
+| --- | --- |
+| Windows | String (`REG_SZ`) values under `HKEY_LOCAL_MACHINE\SOFTWARE\Policies\GitHubCopilot` |
+| macOS | String values in forced managed preferences for the `com.github.copilot` preference domain |
+| Linux | Native MDM delivery is not supported. Use file-based settings instead. |
+
+All native MDM values must be strings. For nested settings, use a dot-separated key such as `permissions.disableBypassPermissionsMode` or `sandbox.enabled`. Store ordinary string values directly. Store booleans, arrays, and objects as JSON text within a string value.
+
+For example:
+
+| Key | Native string value |
+| --- | --- |
+| `permissions.disableBypassPermissionsMode` | `disable` |
+| `sandbox.enabled` | `true` |
+| `enabledPlugins` | `{"PLUGIN-NAME@MARKETPLACE-NAME":true}` |
+
+1. Choose the settings you want to enforce. See [AUTOTITLE](/copilot/reference/enterprise-managed-settings-reference).
+1. Convert each setting to the native key and string value representation.
+1. Deploy the settings to the native policy location using your enterprise MDM platform and standard rollout process.
 1. Assign the policy to the target device groups.
 
     Clients do not need to restart, and check for updated policies on an hourly basis. In {% data variables.product.prodname_vscode_shortname %}, an administrator can force a check for testing by running the `Developer: Sync Account Policy` command.
@@ -105,17 +128,25 @@ For example, to defer both `model` and `disableBypassPermissionsMode`:
 
 ## Deploying file-based settings
 
+Place `{% data variables.copilot.managed_setting_file %}` in the following location:
+
+| Operating system | File location |
+| --- | --- |
+| macOS | `/Library/Application Support/GitHubCopilot/managed-settings.json` |
+| Windows | `%ProgramFiles%\GitHubCopilot\managed-settings.json` |
+| Linux | `/etc/github-copilot/managed-settings.json` |
+
 1. Create or update a `{% data variables.copilot.managed_setting_file %}` file with the policy keys and values you want to enforce.
-1. Distribute the file to managed machines using your standard device management process. Machines that don't receive the file are not restricted by this policy, so file-based deployment only provides coverage for the machines you actively distribute to.
-1. Apply file permissions according to your enterprise security requirements.
+1. Distribute the file to the platform-specific location using your standard device management process. Machines that don't receive the file are not restricted by this policy.
+1. For {% data variables.copilot.copilot_cli_short %} on macOS and Linux, make the file a regular file owned by `root`, and ensure it is not group-writable or world-writable. Do not use a symbolic link. The CLI rejects files that do not meet these requirements.
 1. Ask users to restart supported clients so the updated policy is loaded at startup.
 1. Confirm the settings took effect. See [Verifying the configuration has applied](#verifying-the-configuration-has-applied).
 
 ## Verifying the configuration has applied
 
-Once the configuration is committed, users on a supported client see the specified settings within about an hour, since clients periodically check the server for updated configuration. For server-managed deployments, this includes `copilot/{% data variables.copilot.managed_setting_file %}`, `copilot/{% data variables.copilot.team_mappings_file %}`, and files in `copilot/{% data variables.copilot.team_settings_directory %}`.
+For server-managed deployments, users on a supported client see the specified settings within about an hour. This includes `copilot/{% data variables.copilot.managed_setting_file %}`, `copilot/{% data variables.copilot.team_mappings_file %}`, and files in `copilot/{% data variables.copilot.team_settings_directory %}`. Restarting the client or signing in again triggers an immediate refresh.
 
- Restarting the client or signing in again applies the latest settings immediately.
+For MDM-managed deployments, clients check for updated policies hourly. For file-based deployments, restart the client to load an updated file.
 
 If a user does not see these settings, ensure they receive access to {% data variables.product.prodname_copilot_short %} through your enterprise or one of its organizations. If a user receives a license from multiple billing entities, ensure they have selected your enterprise in the "Usage billed to" dropdown in their [personal {% data variables.product.prodname_copilot_short %} settings](https://github.com/settings/copilot/features).
 
@@ -137,7 +168,7 @@ The main limitation of this method is the {% data variables.product.prodname_ent
 
 ### Using MDM-managed or file-based settings
 
-If you don't want to add a {% data variables.product.prodname_enterprise %} license or create an organization, you can deploy the same settings through MDM (such as Intune or Jamf) or a file-based deployment. These methods use the same JSON schema and don't require an organization or `.github-private` repository. See [Deploying MDM-managed settings](#deploying-mdm-managed-settings) and [Deploying file-based settings](#deploying-file-based-settings). For {% data variables.product.prodname_vscode_shortname %}-specific guidance, see [Deploy Copilot managed settings](https://code.visualstudio.com/docs/enterprise/ai-settings#_deploy-copilot-managed-settings) in the {% data variables.product.prodname_vscode_shortname %} documentation.
+If you don't want to add a {% data variables.product.prodname_enterprise %} license or create an organization, you can deploy the same logical settings through MDM (such as Intune or Jamf) or a file-based deployment. File-based delivery uses the JSON schema directly. Native MDM delivery uses flat keys and string-encoded values. Neither method requires an organization or `.github-private` repository. See [Deploying MDM-managed settings](#deploying-mdm-managed-settings) and [Deploying file-based settings](#deploying-file-based-settings). For {% data variables.product.prodname_vscode_shortname %}-specific guidance, see [Deploy Copilot managed settings](https://code.visualstudio.com/docs/enterprise/ai-settings#_deploy-copilot-managed-settings) in the {% data variables.product.prodname_vscode_shortname %} documentation.
 
 ### Plugin access considerations
 

content/copilot/how-tos/cloud-and-local-sandboxes/configuring-local-sandbox-settings.md

@@ -31,7 +31,7 @@ For a conceptual overview of cloud and local sandboxes for {% data variables.pro
 
 ## Configuring general settings
 
-The **General** tab controls the top-level sandbox behavior.
+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.
 
 | Setting | Description |
 | --- | --- |
@@ -47,7 +47,7 @@ The **General** tab controls the top-level sandbox behavior.
 
 The **Allow sandbox bypass** setting controls what happens when {% data variables.product.prodname_copilot_short %} can't run a command successfully inside the sandbox.
 
-* **On (default)**: If a command fails inside the sandbox, you are prompted to allow {% data variables.product.prodname_copilot_short %} to run the command outside the sandbox. Your response to this prompt applies to this specific attempt to run the command. Optionally, you can choose to disable the sandbox for the rest of the session, or you can enter an instruction for {% data variables.product.prodname_copilot_short %} to work on instead.
+* **On (default)**: If a command fails inside the sandbox, you are prompted to allow {% data variables.product.prodname_copilot_short %} to run the command outside the sandbox. Your response to this prompt applies to this specific attempt to run the command. Optionally, you can choose to disable the sandbox for the rest of the session (if permitted by your enterprise), or you can enter an instruction for {% data variables.product.prodname_copilot_short %} to work on instead.
 * **Off**: If {% data variables.product.prodname_copilot_short %} can't run a command successfully in the sandbox, it stops working on the task and reports the failure.
 
 ## Configuring filesystem settings

content/copilot/how-tos/cloud-and-local-sandboxes/using-local-sandboxing.md

@@ -20,7 +20,7 @@ docsTeamMetrics:
 
 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.
 
-When you enable local sandboxing, {% data variables.copilot.copilot_cli_short %} runs most of the commands and tools it invokes on your behalf inside an operating-system sandbox. After you enable local sandboxing, it is used for all your {% data variables.copilot.copilot_cli_short %} sessions until you disable it, or turn it off for a specific session.
+When you enable local sandboxing, {% data variables.copilot.copilot_cli_short %} runs most of the commands and tools it invokes on your behalf inside an operating-system sandbox. After you enable local sandboxing, it is used for all your {% data variables.copilot.copilot_cli_short %} sessions until you disable it, or turn it off for a specific session. If enterprise managed settings require sandboxing, you cannot disable it.
 
 By default, sandboxed commands and tools can write within your current working directory and temporary folders. Your user profile (home) directory, along with system and tool locations are read-only. Other disk locations are blocked. In a Git repository, access above the current working directory varies by operating system. Access to your local and private network is permitted, as is outbound internet access.
 
@@ -48,6 +48,8 @@ After you enable local sandboxing, it continues to be used for the current and f
 
 ## Disabling local sandboxing
 
+If enterprise managed settings require sandboxing, you cannot disable it, and `/sandbox disable` is refused.
+
 To stop using local sandboxing, enter the following command in an interactive {% data variables.copilot.copilot_cli_short %} session:
 
 ```shell copy
@@ -60,7 +62,7 @@ Your choice of whether to use local sandboxing is saved as the `sandbox.enabled`
 
 ## Using sandboxing for a single session
 
-You can use the `--sandbox` command line option to use sandboxing for a single session, without enabling sandboxing for your other sessions. If sandboxing is already enabled, you can disable it for a single session by using the `--no-sandbox` option.
+You can use the `--sandbox` command line option to use sandboxing for a single session, without enabling sandboxing for your other sessions. If sandboxing is already enabled, you can disable it for a single session by using the `--no-sandbox` option. The `--no-sandbox` option cannot override enterprise managed settings that require sandboxing.
 
 You can combine these options with the `-p` command line option to control sandboxing for programmatic use of the CLI. For example: