Configure server-managed settings changedserver-managed-settings
Nearest release: v2.1.251, published under an hour before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+12added
Lines−11removed
From line
146
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits47to this page, all time
The whole hunk
from line 146, old and new numbered
/
from line 146
146146**Subsequent launches with cached settings:**
147147
148148* Cached settings apply immediately at startup, except for the withheld environment variables described below
149* A cached [`modelPricing`](/docs/en/settings-reference#modelpricing) doesn't apply until the session's fetch confirms the payload. Until then, the cost figures developers see in `/usage` and the status line are at list price
149150* Claude Code fetches fresh settings in the background
150* Cached settings persist through network failures. The withheld environment variables remain withheld until a fetch succeeds
151* Cached settings persist through network failures. Until a fetch succeeds, the withheld environment variables remain withheld and cost figures stay at list price
151152
152153Claude Code withholds several categories of variables in the cached `env` block until the server confirms the payload for the session. This keeps a cached proxy, certificate authority, endpoint, or credential value from redirecting, intercepting, or re-authenticating the settings fetch that confirms the payload. The hardening applies only to the server-fetched settings cache: [endpoint-managed settings](/docs/en/managed-settings#delivery-mechanisms) deployed through MDM or `managed-settings.json` are unaffected. The withholding requires Claude Code v2.1.198 or later; before v2.1.198, the whole cached `env` block applies at startup. The withheld categories include:
153154
from line 267
266267
267268Server-managed settings provide centralized policy enforcement, but they operate as a client-side control, not a security boundary. On unmanaged devices, a user doesn't need admin or sudo access to bypass them.
268269
269| Scenario | Behavior |
270| :--------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
271| User edits the cached settings file | Tampered file applies at startup, and the next server fetch restores the correct settings, except for the [keys that apply only at the next launch](#fetch-and-caching-behavior), such as `model` or a variable added to the `env` block, which stay in effect until relaunch. In Claude Code v2.1.198 or later, the [withheld environment variables](#fetch-and-caching-behavior) in the `env` block don't apply until the server confirms the payload |
272| User deletes the cached settings file | First-launch behavior occurs: Claude Code fetches the settings asynchronously and doesn't enforce server-managed settings until the fetch completes |
273| User runs a modified Claude Code binary | A user who can run a modified client can bypass any client-side control |
274| User runs an older Claude Code version | Versions that predate server-managed settings don't fetch or apply them |
275| API is unavailable | Cached settings apply if available. Without a cache, Claude Code enforces no server-managed settings until the next successful fetch and still applies any [endpoint-managed settings](/docs/en/managed-settings#delivery-mechanisms) on the device. In Claude Code v2.1.198 or later, the [withheld environment variables](#fetch-and-caching-behavior) in the cached `env` block don't apply on fetch failure; the rest of the cache still applies. With `forceRemoteSettingsRefresh: true`, the CLI exits instead of continuing, except for [`claude auth` subcommands](#enforce-fail-closed-startup). Clients signed in through a [Claude apps gateway](#platform-availability) exit at startup without that setting, with the same `claude auth` exemption |
276| User authenticates with a different organization | Settings are not delivered for accounts outside the managed organization |
277| User configures a [third-party model provider](#platform-availability) | Server-managed settings are bypassed. This includes setting `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_MANTLE`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY`, `CLAUDE_CODE_USE_ANTHROPIC_AWS`, or a non-default `ANTHROPIC_BASE_URL` |
278| Network traffic is intercepted or redirected | Disabled TLS validation or intercepted traffic can alter the settings the client receives |
270| Scenario | Behavior |
271| :--------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
272| User edits the cached settings file | Tampered file applies at startup, and the next server fetch restores the correct settings, except for the [keys that apply only at the next launch](#fetch-and-caching-behavior), such as `model` or a variable added to the `env` block, which stay in effect until relaunch. In Claude Code v2.1.198 or later, the [withheld environment variables](#fetch-and-caching-behavior) in the `env` block don't apply until the server confirms the payload. In Claude Code v2.1.242 or later, a cached [`modelPricing`](/docs/en/settings-reference#modelpricing) doesn't apply until the server confirms the payload either, so cost figures are at list price until then |
273| User deletes the cached settings file | First-launch behavior occurs: Claude Code fetches the settings asynchronously and doesn't enforce server-managed settings until the fetch completes |
274| User runs a modified Claude Code binary | A user who can run a modified client can bypass any client-side control |
275| User runs an older Claude Code version | Versions that predate server-managed settings don't fetch or apply them |
276| API is unavailable | Cached settings apply if available. Without a cache, Claude Code enforces no server-managed settings until the next successful fetch and still applies any [endpoint-managed settings](/docs/en/managed-settings#delivery-mechanisms) on the device. In Claude Code v2.1.198 or later, the [withheld environment variables](#fetch-and-caching-behavior) in the cached `env` block don't apply on fetch failure. In Claude Code v2.1.242 or later, a cached [`modelPricing`](/docs/en/settings-reference#modelpricing) doesn't apply on fetch failure either, so cost figures stay at list price until a fetch succeeds. The rest of the cache still applies. With `forceRemoteSettingsRefresh: true`, the CLI exits instead of continuing, except for [`claude auth` subcommands](#enforce-fail-closed-startup). Clients signed in through a [Claude apps gateway](#platform-availability) exit at startup without that setting, with the same `claude auth` exemption |
277| User authenticates with a different organization | Settings are not delivered for accounts outside the managed organization |
278| User configures a [third-party model provider](#platform-availability) | Server-managed settings are bypassed. This includes setting `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_MANTLE`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY`, `CLAUDE_CODE_USE_ANTHROPIC_AWS`, or a non-default `ANTHROPIC_BASE_URL` |
279| Network traffic is intercepted or redirected | Disabled TLS validation or intercepted traffic can alter the settings the client receives |
279280
280281To log edits to local settings files, including `managed-settings.json`, use [`ConfigChange` hooks](/docs/en/hooks#configchange). Claude Code doesn't run them when server-managed settings arrive or refresh, or when an MDM profile or registry policy changes, and a hook can't block a `policy_settings` change.
281282
No line in this hunk matches that.