You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit f71bee7
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: content/copilot/how-tos/administer-copilot/manage-for-enterprise/use-managed-settings/deploy-managed-settings.md
+8Lines changed: 8 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -91,6 +91,14 @@ Place `{% data variables.copilot.managed_setting_file %}` in the following locat
91
91
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.
92
92
1. Ask users to restart supported clients so the updated policy is loaded at startup.
93
93
94
+
## Requiring fresh server-managed settings on startup
95
+
96
+
Use `forceRemoteSettingsRefresh` when a time-sensitive policy change must reach supported clients before {% data variables.product.prodname_copilot_short %} starts. The setting is supported in {% data variables.copilot.copilot_cli_short %}, the {% data variables.copilot.github_copilot_app %}, and {% data variables.product.prodname_vscode_shortname %}.
97
+
98
+
MDM-managed and file-based delivery can apply this requirement before the client signs in for the first time. A server-managed value begins requiring refreshes on subsequent startups after the client has received it once.
99
+
100
+
For client-specific behavior, value formats, and limitations, see [`forceRemoteSettingsRefresh`](/copilot/reference/enterprise-administrators/enterprise-managed-settings#forceremotesettingsrefresh) in the enterprise managed settings reference.
101
+
94
102
## Precedence of deployment methods
95
103
96
104
When multiple settings sources are present, settings earlier in this list take precedence over settings later in the list:
|`forceLoginOrgs`| Pin sign-in to an approved set of {% data variables.product.github %} organizations (an array of organization logins, matched case-insensitively). {% data variables.product.prodname_copilot_short %} only runs for an account belonging to at least one listed organization; a personal account, an account that belongs only to some other enterprise, or BYOK/API-key authentication is refused with an actionable error. Set an empty array to turn the pin off without deleting the key. Deploy this key through the device channel (MDM plist/registry, or `managed-settings.json`) since it must be able to redirect a developer's first sign-in—the server-managed channel only reaches accounts that have already authenticated into the organization. This key fails closed: an unusable value, or a managed policy that can't be read on a known-managed device, blocks all sign-in until fixed. |
668
-
|`forceRemoteSettingsRefresh`| Require a fresh server-managed settings fetch on startup, even when a fresh cached policy exists. The cached entry is still kept as a fallback if the fetch fails. The device (MDM) value takes precedence over a cached server value. |
668
+
|`forceRemoteSettingsRefresh`| Require a fresh server-managed settings fetch on startup, even when a fresh cached policy exists. Cached policy cannot satisfy the freshness requirement. If the fetch fails, affected operations remain restricted until current policy is confirmed. The device (MDM) value takes precedence over a cached server value. |
669
669
|`model`| Set a default model for all users (overridden by the `--model` flag or a resumed-session model). `effortLevel` and `contextTier` set alongside `model` apply the same managed reasoning effort and context tier as the corresponding [repository settings](#repository-settings-githubcopilotsettingsjson) keys, but only when the managed model supports explicit effort/context options. |
670
670
|`permissions`| Set managed permissions, including `disableBypassPermissionsMode`, `deny` / `ask` / `allow` rule arrays, and the `limitTo` domain boundary array. See [Managed permission rules](#managed-permission-rules) and [Domain boundary (`limitTo`)](#domain-boundary-limitto). |
671
671
|`policyHelper`| Register an executable that supplies the lowest-priority managed-settings layer. Fields: `path` (required), plus optional `args`, `timeoutMs`, and `refreshIntervalMs`. If both a device (MDM) and a server policy register a `policyHelper`, the device registration wins. |
|`telemetry`| Configures OpenTelemetry export, routing {% data variables.product.prodname_copilot_short %} usage data to a collector of your choice | {% 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" %} |
34
34
|`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" %} |
36
37
|`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" %} |
37
-
|`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 "check" aria-label="Supported" %} (Agent Host, 1.138.0+) | {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} | {% octicon "x" aria-label="Not supported" %} |
38
+
|`sandbox`| Enforces minimum local sandbox restrictions for command execution, filesystem and network access, credentials, and local MCP and LSP servers. Subject to minimum client version requirements.| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} (Agent Host, 1.138.0+) | {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} | {% octicon "x" aria-label="Not supported" %} |
38
39
39
40
{% endrowheaders %}
40
41
@@ -239,11 +240,11 @@ For example, a team settings file can set `"autoTier": "intelligence"`. If the t
239
240
240
241
## forceRemoteSettingsRefresh
241
242
242
-
Requires a fresh download of server-managed settings at startup in {% data variables.copilot.copilot_cli_short %} and {% data variables.product.prodname_vscode_shortname %}. Set `forceRemoteSettingsRefresh` to `true` to enable this requirement.
243
+
Requires a fresh download of server-managed settings at startup in {% data variables.copilot.copilot_cli_short %}, {% data variables.product.prodname_vscode_shortname %}, and the {% data variables.copilot.github_copilot_app %}. Set `forceRemoteSettingsRefresh` to `true` to enable this requirement.
243
244
244
-
In {% data variables.copilot.copilot_cli_short %}, this skips the normal one-hour cache and prevents fallback to an older cached policy if the download fails. An unsuccessful refresh leaves the policy unconfirmed, so affected operations are restricted. In {% data variables.product.prodname_vscode_shortname %}, {% data variables.product.prodname_copilot_short %} features are blocked until the required refresh succeeds. Users therefore need a network connection when starting the client.
245
+
In {% data variables.copilot.copilot_cli_short %} and the {% data variables.copilot.github_copilot_app %}, this skips the normal one-hour cache and prevents fallback to an older cached policy if the download fails. An unsuccessful refresh leaves the policy unconfirmed, so affected operations are restricted. In {% data variables.product.prodname_vscode_shortname %}, {% data variables.product.prodname_copilot_short %} features are blocked until the required refresh succeeds. Users therefore need a network connection when starting the client.
245
246
246
-
For the requirement to apply from a device's first startup, deliver it through device management or `{% data variables.copilot.managed_setting_file %}`. A server-delivered value can require refreshes on subsequent startups after the client has received it. Policy helper scripts cannot set this key.
247
+
For the requirement to apply from a device's first startup, deliver it through MDM-managed or file-based settings. A server-managed value can require refreshes on subsequent startups after the client has received it. Policy helper scripts cannot set this key.
247
248
248
249
In `{% data variables.copilot.managed_setting_file %}`, use a JSON Boolean, for example `"forceRemoteSettingsRefresh": true`. When configuring {% data variables.copilot.copilot_cli_short %} through the Windows registry or macOS managed preferences, store this value as a string containing `true` or `false`. Do not use a DWORD or native Boolean.
249
250
@@ -458,3 +459,13 @@ In {% data variables.copilot.copilot_cli_short %}, host rules and upstream proxi
458
459
Configures macOS-specific Seatbelt options.
459
460
460
461
*`keychainAccess`: `false` prevents sandboxed processes from accessing the macOS Keychain.
462
+
463
+
### Minimum client version enforcement for `sandbox`
464
+
465
+
When you add the `sandbox` key to managed settings, {% data variables.product.prodname_copilot_short %} enforces a local sandbox for all users in scope. These users must use a {% data variables.product.prodname_copilot_short %} client version that supports local sandbox. Until a user updates their client to at least the minimum supported version, their connections to {% data variables.product.prodname_copilot_short %} are blocked.
466
+
467
+
| Supported client | Minimum version |
468
+
| --- | --- |
469
+
| VS Code |[1.141.0](https://github.com/microsoft/vscode/releases/tag/1.141.0)|
0 commit comments