From cc484864b2f86a5cd1fcc83ac08d2f560e05e1ca Mon Sep 17 00:00:00 2001 From: Parideboy Date: Sun, 23 Aug 2026 18:12:37 +0200 Subject: [PATCH] docs(troubleshooting): note server-managed settings skip custom ANTHROPIC_BASE_URL (#3118) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Description Documents a known Claude Code client-side limitation: server-managed settings (delivered from the claude.ai admin console) are silently skipped whenever `ANTHROPIC_BASE_URL` is non-default — which is exactly the condition Headroom wrapping creates. Fixes #3074 by explaining the root cause is upstream, not a Headroom bug, and pointing affected users at the endpoint-managed alternative. ## Type of Change - [x] Documentation - [ ] Bug fix - [ ] New feature - [ ] Breaking change - [ ] Refactor / chore ## Changes Made - Added a new "Server-managed settings unavailable through custom ANTHROPIC_BASE_URL" section to `docs/content/docs/troubleshooting.mdx`, immediately after the existing "Remote Control unavailable through custom ANTHROPIC_BASE_URL" section (same class of Claude-side gate, same Symptom/Cause/Fix format). - Explains why Headroom has no endpoint to implement here (per Anthropic's docs, Claude Code skips the fetch client-side before any request is sent) and distinguishes this from the unrelated, unaffected OS-level `managed-settings.json` file. - Links to Anthropic's official docs and to #3074. ## Testing - [x] Verified locally - [ ] Added/updated automated tests - [ ] N/A ``` $ python3 -c " import re text = open('docs/content/docs/troubleshooting.mdx', encoding='utf-8').read() headings = re.findall(r'^##\s+.*$', text, re.MULTILINE) start = text.index('## Server-managed settings') end = text.index('## Compression Too Aggressive') section = text[start:end] print('backticks even:', section.count(chr(96)) % 2 == 0) print('brackets balanced:', section.count('[') == section.count(']')) print('parens balanced:', section.count('(') == section.count(')')) " backticks even: True brackets balanced: True parens balanced: True ``` ## Real Behavior Proof - Environment: Docs-only change (MDX prose, no code path). `docs/` npm deps are not installed in this sandbox, so the Next.js docs build (`npm run build`) was not run. - Exact command / steps: Diffed the new section against the file's existing neighboring section (git diff), and ran a Python script validating heading structure and backtick/bracket/paren balance within the new section (shown above). - Observed result: New `##` heading inserted cleanly between the two existing sections with no structural changes elsewhere in the file; markdown syntax (bold labels, inline code, links) mirrors the adjacent "Remote Control" section exactly, and is balanced/well-formed. - Not tested: The actual Next.js docs site build/render (`npm run build` in `docs/`) — no network/npm install available in this sandbox. No functional/runtime behavior is affected by this change. ## Runtime Rollout Safety - Rollout-managed feature(s): None - Minimum rollout channel: N/A - Stable/default behavior changed: No - Kill switch / disable path: N/A - Unsafe override required: No - Qualification impact: None - Rollback path: Revert the commit; no state or config is introduced ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review Co-authored-by: Claude Sonnet 5 --- docs/content/docs/troubleshooting.mdx | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/content/docs/troubleshooting.mdx b/docs/content/docs/troubleshooting.mdx index 22ef73ae8..5b796b371 100644 --- a/docs/content/docs/troubleshooting.mdx +++ b/docs/content/docs/troubleshooting.mdx @@ -223,6 +223,18 @@ See [issue #746](https://github.com/headroomlabs-ai/headroom/issues/746) for the `ENABLE_TOOL_SEARCH` is unaffected and can stay enabled for context-window savings while routing through Headroom. +## Server-managed settings unavailable through custom ANTHROPIC_BASE_URL + +**Symptom**: Settings pushed from **Admin Settings > Claude Code > Managed settings** in the claude.ai console (server-managed settings) don't apply to sessions running through Headroom, even though they apply fine without the proxy. + +**Cause**: This is a Claude-side gate, not a Headroom limitation. Per Anthropic's docs, server-managed settings require a direct connection to `api.anthropic.com`; if `ANTHROPIC_BASE_URL` is set to any non-default host — which is exactly what wrapping via Headroom does — Claude Code skips the settings fetch entirely for that session. The request never reaches Headroom, so there is no endpoint for Headroom to implement or proxy. + +This is separate from the OS-level `managed-settings.json` file (macOS `/Library/Application Support/ClaudeCode/`, Linux `/etc/claude-code/`, Windows `C:\Program Files\ClaudeCode\`): that file is read straight from local disk at startup and is unaffected by `ANTHROPIC_BASE_URL` or Headroom. If that file isn't taking effect, the cause is unrelated to proxying (path, permissions, or JSON syntax) — check `claude --debug-file ` and search the log for `Remote settings`. + +**Fix**: None available on the Headroom side — this is an intentional Anthropic security boundary (a proxy in the path could otherwise forge org policy). If your org relies on server-managed settings, deploy the same policy as [endpoint-managed settings](https://code.claude.com/docs/en/settings#settings-files) (MDM profile, Windows registry, or a local `managed-settings.json`) instead, since those are read locally and unaffected by proxying. + +See [Server-managed settings platform availability](https://code.claude.com/docs/en/server-managed-settings#platform-availability) and [issue #3074](https://github.com/headroomlabs-ai/headroom/issues/3074). + ## Compression Too Aggressive **Symptom**: LLM responses are missing information that was in tool outputs.