Claude Code 2.1.238 Gives Self-Hosted Runners Dynamic Proxy Authorization and Graceful Shutdown

Three changes in Claude Code 2.1.238 directly affect how enterprises deploy self-hosted runners: dynamic per-connection proxy authorization, graceful SIGTERM draining, and an expanded headersHelper trust model that now covers plugin marketplace catalog fetches.

None of these appear in the single-line changelog entries. What each one actually changes in production is worth unpacking.

The corporate proxy authentication problem

Enterprise networks routinely sit Claude Code's outbound HTTP traffic behind an authenticated egress proxy. Until 2.1.238, the only way to pass the Proxy-Authorization header to that proxy was to set it as a static environment variable before the runner process started.

That design breaks the moment the corporate proxy starts issuing short-lived credentials — OAuth 2.0 bearer tokens from a PAM system, Kerberos service tickets via SPNEGO, or rotating credentials from a secrets manager like Vault or AWS Secrets Manager. A static env var set at runner startup is stale within minutes.

2.1.238 adds two new flags to claude self-hosted-runner:

--proxy-authorization-command "<shell command>"
--proxy-authorization-file "<path to file>"

--proxy-authorization-command runs the specified command for each new egress connection and uses its stdout as the Proxy-Authorization header value. The command can be anything that emits a header value: a Vault read, an AWS STS call, a custom token endpoint script. The runner runs it per-connection rather than once at startup, which means a 5-minute token TTL on your proxy no longer requires restarting or cycling the runner process.

--proxy-authorization-file reads the value from a file path instead. This covers patterns where an external agent (a sidecar, a credential refresher, or an operator script) writes fresh credentials to a well-known path on disk. The runner reads the file on each connection, so the refresher can update it without touching the runner process.

Before 2.1.238, operators working around this limitation had wrapper scripts that killed and restarted the runner on a credential rotation schedule. That is now unnecessary — and the session continuity improvement is real: a runner restart drops any session that does not checkpoint cleanly.

Graceful shutdown on SIGTERM

--defer-shutdown-max-min <minutes> changes the runner's behavior on SIGTERM. Before this flag, a SIGTERM (typical for container orchestration, systemd stop, or autoscaler drain events) terminated the process immediately. Any attached session that had not reached a natural pause was cut off.

With --defer-shutdown-max-min 5, for example, the runner:

1. Stops accepting new sessions from the server.
2. Continues serving currently attached sessions.
3. Parks whatever is left after the configured minutes.
4. Exits cleanly.

The operator consequence is that Kubernetes terminationGracePeriodSeconds, ECS drain hooks, and systemd service stop timeouts now actually work with Claude Code runners. Before, you needed to set grace period to zero and accept session drops. Now you can set it to match your --defer-shutdown-max-min value and let active coding sessions drain normally.

Teams running Claude Code runners in autoscaled clusters — where nodes cycle on a schedule — will see the most benefit.

headersHelper expansion to marketplace catalog fetches

headersHelper has been in Claude Code for several months as a mechanism for MCP server connections to receive dynamically issued HTTP headers. 2.1.238 extends it to two additional request paths:

• Plugin marketplace catalog fetches: when a url marketplace or a catalog entry defines a headersHelper, the runner executes it to mint HTTP headers for both catalog listing requests and archive (plugin bundle) download requests. Previously, only the initial install step ran a headersHelper; catalog browsing was unauthenticated.
• Trust model change for project-scope helpers: headersHelper defined in a project .mcp.json, inline MCP servers in project or --add-dir agent files, and similar project-level configurations now require the folder's trust dialog to have been accepted before they execute. This prevents a malicious repo from silently running a credential-harvesting script on claude -p.

The first change matters for teams running a private plugin marketplace — an internal catalog of proprietary Claude Code plugins. Before 2.1.238, only the plugin install and update steps could authenticate against that catalog; browsing claude plugin list would hit the catalog endpoint unauthenticated. Now a headersHelper in the marketplace definition handles auth on every request.

The second change is defensive. Project-level headersHelper now inherits the same trust gate as project .mcp.json entries: the user must have already accepted the folder trust dialog. Under claude -p (non-interactive), the credential env vars the helper would have inherited are not passed.

What to watch

• If you run Claude Code self-hosted runners behind a corporate proxy that issues short-lived tokens, update to 2.1.238 and move from the static env var pattern to --proxy-authorization-command pointing at your credential-minting script.
• If you manage a private Claude Code plugin marketplace, verify whether headersHelper on your marketplace entry covers catalog fetches — and test claude plugin list behavior after the update.
• If you use project-scoped headersHelper in any .mcp.json for non-interactive (-p) automation, audit whether those scripts depend on credential env vars from the launching shell. Under 2.1.238 that inheritance is blocked; the script runs from the Claude config directory with a clean env.
• Set --defer-shutdown-max-min to match your orchestration's termination grace period. A mismatch in either direction wastes session time (too high) or still drops sessions (too low).

The 2.1.238 changelog also includes a large batch of Remote Control stability fixes — reconnect after brief network 403s, offline detection within seconds, cross-session ListAgents/SendMessage reaching peers in remote-control server mode. For teams using Claude Code as a remotely orchestrated agent layer, those fixes are worth reviewing in the full changelog.

Claude Code docs →