Claude apps gateway configuration

Reference for every gateway.yaml option: listener and TLS, OIDC, session, Postgres store, Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, and Microsoft Foundry upstreams, model routing, managed policies, and telemetry.

A Claude apps gateway deployment is configured by one YAML file, conventionally gateway.yaml. The file defines everything the gateway does: where it listens, how developers sign in, where inference goes, and which policies and telemetry apply. This page is the reference for every option in that file.

To write your first one, start from the quickstart, which builds a minimal working config and runs it. Once you have a config you're happy with, the deployment guide covers containerizing and hosting it on Kubernetes, Cloud Run, or your own platform.

The gateway reads the file once, at startup, with claude gateway --config /path/to/gateway.yaml. Every option is validated against a schema at boot, so a malformed config fails at start with a field-level error rather than at first use.

The complete example at the end of this page exercises every section.

File structure

Five sections are required. Every other section is optional, and an omitted section takes its defaults. Unknown keys fail boot, so a typo surfaces as a named error rather than a silently ignored setting.

Required sections:

• listen: bind address, public URL, TLS termination
• oidc: your identity provider (IdP), including issuer, client, claim mapping, and who may sign in
• session: the bearer tokens the gateway mints, with secret and lifetime
• store: PostgreSQL, for device grants and rate-limit counters
• upstreams: where inference goes, whether Anthropic, Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, or Microsoft Foundry

Optional sections:

• admin: Admin API auth and retention for spend limits
• enforcement: spend-limit fail-open or fail-closed behavior
• pricing: contracted rates and a discount multiplier for the spend meter
• models and auto_include_builtin_models: admin-curated model list and per-upstream IDs
• managed: managed settings policies by IdP group
• telemetry: OTLP forwarding to your observability stack
• access_control, limits, timeouts, rate_limits: IP allow/deny, request size caps, upstream time-to-first-byte, and per-IP sign-in limits

Secret expansion

Don't write secrets such as client_secret, jwt_secret, or postgres_url directly in gateway.yaml. Reference them with one of the forms below, and the gateway resolves the value at boot from an environment variable or a file:

Required sections

listen

The listen block controls where the gateway serves: the bind address and port, the externally visible origin, and optional TLS termination.

oidc

The oidc block connects the gateway to your identity provider and decides who can sign in. It names the issuer and OAuth client, maps the claims that carry email and groups, and restricts sign-in by email domain or group.

OpenID Connect (OIDC) is the SSO protocol the gateway uses with your identity provider; see Identity provider setup for what to register on the IdP side.

IdP requests through a forward proxy

The inference upstreams honor HTTPS_PROXY and HTTP_PROXY on every version. The gateway's own requests to the IdP, discovery, JWKS, token, and userinfo, go direct unless you set oidc.use_proxy: true, which requires v2.1.227 or later. When a proxy variable is set, use_proxy is unset, and the issuer isn't covered by NO_PROXY, the gateway keeps those requests direct and logs a notice at boot asking you to choose; use_proxy: false keeps them direct and silences the notice.

With use_proxy: true, the pod resolves each IdP endpoint's hostname itself and asks the proxy to CONNECT to the resolved IP address, so the proxy must accept CONNECT to the IP address of every host the discovery document names, not only the issuer. Use an http:// proxy URL. ca_cert_pem and the SSRF guard apply on the proxied path as well.

session

The session block shapes the bearer tokens the gateway mints after sign-in: the secret that signs them and how long they live.

store

The store block points the gateway at its PostgreSQL database, which holds device grants and rate-limit counters.

For local development, point postgres_url at a throwaway Postgres container, for example docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres.

upstreams

upstreams is an ordered list. The gateway forwards inference to the first upstream that resolves the requested model. On 5xx, 429, 401, 403, 404, or timeout it fails over to the next; other 4xx doesn't, because those errors are attributable to the request rather than the upstream. A 401 or 403 means the gateway's own credential failed against that upstream, and a 404 means that upstream doesn't serve the requested model, so a later upstream in the list still can.

Failover on 404 requires gateway v2.1.198 or later. Earlier releases returned the first 404 to the client even when a later upstream in the list served the model.

Multiple upstreams of the same provider must set a distinct name:.

Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, and Microsoft Foundry clients are built once at startup, and their SDKs refresh credentials internally, so rotating cloud credentials doesn't require a restart. Static Anthropic API keys and bearers are read at startup; see Anthropic API.

Upstream error messages

The gateway returns one upstream's error response, or its own 502, depending on how the upstreams answered:

• An upstream returned a status the gateway doesn't fail over on: that upstream's response. The gateway tries no further upstreams.
• Every upstream the gateway tried failed in a way it fails over on: the last 429. When none returned a 429, the gateway prefers, in order, the last 401 or 403, the last 404, and the last 501. When none returned any of those, the gateway's own 502, all upstreams failed (N attempted), where N counts every entry in upstreams, including entries the gateway skipped because they don't serve the requested model.

When the gateway returns an upstream's response, it keeps the upstream's status code. Whether it keeps the upstream's message depends on the provider. An Anthropic API upstream's error body reaches the developer unchanged.

The Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, and Microsoft Foundry upstreams can name your account IDs, role ARNs, and project IDs in their error text. The gateway records that full text in the operational log. What the developer sees from those upstreams depends on the rejection:

• 400 or 413 in Anthropic's standard error envelope: the upstream's own message, such as prompt is too long. Claude Platform on AWS, Agent Platform, and Microsoft Foundry return this envelope for model API rejections.
• 400 or 413 in the provider's own shape: a capability_rejected: token. When the gateway can't classify the rejection, upstream rejected the request on a 400 or request too large for this upstream on a 413.
• Any other status: generic per-status copy, such as upstream rate limit exceeded on a 429.

For example, the gateway replaces Amazon Bedrock's Input is too long for requested model. with capability_rejected: prompt_too_long. Claude Code compacts automatically on that token, as it does on prompt is too long.

Keeping a cloud upstream's 400 or 413 message, or replacing it with a capability_rejected: token, requires gateway v2.1.233 or later.

Anthropic API

The minimal Anthropic upstream is an API key from the Claude Console:

upstreams:
  - provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}
    # OR an OAuth bearer (e.g. a Workload-Identity-Federation-exchanged token):
    #   oauth_token: ${file:/var/run/secrets/anthropic-oauth-token}
    # base_url: https://api.anthropic.com   # default; override for a forward proxy

The two credential forms differ in the header they send:

• api_key: sends x-api-key. Rotate it in the Claude Console and update the env var.
• oauth_token: sends Authorization: Bearer. Use the bearer form when your org issues short-lived tokens instead of long-lived API keys. The bearer is read once at startup, so refresh by remounting the secret and restarting.

Instead of a static key or bearer, you can use Workload Identity Federation. Create a federation rule by following the Workload Identity Federation guide, then mount your workload's OIDC JWT as a file, such as a Kubernetes projected service-account token or a CI platform's id-token. The gateway exchanges the JWT for a short-lived bearer and refreshes it automatically. The token file is re-read on every exchange, so rotated projected tokens are picked up without a restart.

upstreams:
  - provider: anthropic
    auth:
      federation_rule_id: ${ANTHROPIC_FEDERATION_RULE_ID}
      organization_id: ${ANTHROPIC_ORGANIZATION_ID}
      identity_token_file: /var/run/secrets/anthropic/id-token
      # workspace_id: wrkspc_...       # required if the rule covers >1 workspace
      # service_account_id: svac_...   # optional expected-target check

upstreams:
  - provider: anthropic
    base_url: https://upstream-gateway.internal.example.com
    auth:
      api_key: ${PROXY_KEY}
    forward_user_identity: true        # default false

When the IdP token carries no email, the gateway sends only x-claude-gateway-user-id and omits the two email headers. If your IdP puts the email in a different claim, set oidc.email_claim to that claim.

Set forward_user_identity only on an upstream whose base_url is a proxy you operate. The gateway sends developer emails to whatever server that base_url names. If the base_url is the Anthropic API, which is the default, the gateway refuses to start.

Amazon Bedrock

For the client-side Amazon Bedrock deployment that the gateway replaces or fronts, see Claude Code on Amazon Bedrock. The gateway-side upstream:

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}                           # preferred: AWS default credential chain
    # OR explicit credentials:
    # auth:
    #   aws_access_key_id: ${AWS_AKID}
    #   aws_secret_access_key: ${AWS_SK}
    #   aws_session_token: ${AWS_ST}
    # OR a Bedrock API bearer token:
    # auth:
    #   aws_bearer_token: ${AWS_BEARER_TOKEN}
    # Override the bedrock-runtime endpoint for FIPS or VPC-endpoint deployments:
    # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com

An empty auth block uses the AWS SDK's default credential chain: env vars, ~/.aws/credentials, ECS task role, EC2 instance metadata, or IRSA on EKS. In production, give the gateway pod an IAM role instead of embedding static keys in a container image.

Explicit credentials must be complete: the gateway fails at boot when aws_access_key_id and aws_secret_access_key aren't set together, or when aws_session_token is set without them. Before v2.1.207, a partial auth: block passed validation.

Claude Platform on AWS

Claude Platform on AWS serves the first-party Anthropic API on AWS infrastructure at aws-external-anthropic.<region>.api.aws. It uses first-party model IDs, honors anthropic-beta headers as sent, and serves count_tokens, so none of the Bedrock-specific translation applies. The anthropicAws provider requires Claude Code v2.1.198 or later; earlier gateway releases reject it at boot.

For the client-side deployment of the same platform, see Claude Code on Claude Platform on AWS. The gateway-side upstream:

upstreams:
  - provider: anthropicAws
    region: us-east-1
    workspace_id: wrkspc_...
    auth:
      api_key: ${ANTHROPIC_AWS_API_KEY}   # sent as x-api-key
    # OR SigV4 via the AWS default credential chain:
    # auth: {}
    # OR explicit SigV4 credentials:
    # auth:
    #   aws_access_key_id: ${AWS_ACCESS_KEY_ID}
    #   aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}
    # Override the derived endpoint:
    # base_url: https://aws-external-anthropic.us-east-1.api.aws

The platform runs in a separate AWS account from Amazon Bedrock and signs SigV4 requests for its own service name, aws-external-anthropic, so a Bedrock-scoped IAM role doesn't authorize it. An API key in auth.api_key takes precedence when SigV4 credentials are also set. An empty auth block uses the AWS SDK's default credential chain, the same chain the Amazon Bedrock upstream uses.

Because the platform resolves first-party model IDs, the built-in catalog routes to it with no models: block. When you curate a models: list, key the entry anthropicAws: with the first-party ID.

Google Cloud Agent Platform

For the equivalent client-side setup, see Claude Code on Google Cloud. The gateway-side upstream:

upstreams:
  - provider: vertex
    region: us-east5
    project_id: example-prod
    auth: {}                           # preferred: Application Default Credentials
    # OR a service account key file:
    # auth: { service_account_json: /secrets/sa.json }
    # Override the aiplatform endpoint for Private Service Connect:
    # base_url: https://us-east5-aiplatform.p.googleapis.com

An empty auth block uses Application Default Credentials: GOOGLE_APPLICATION_CREDENTIALS, GCE metadata, or GKE Workload Identity. Service-account JSON key files are supported but discouraged; use Workload Identity or attach a service account to the GCE or Cloud Run instance.

Set region: global to use the global endpoint for Google Cloud's Agent Platform instead of a regional one. Google then routes each request to an available region, so you don't track per-region model availability. Setting a specific region pins every request to it.

Microsoft Foundry

For the client-side Microsoft Foundry deployment, see Claude Code on Microsoft Foundry. The gateway-side upstream:

upstreams:
  - provider: foundry
    resource: example-foundry              # https://example-foundry.services.ai.azure.com
    auth: { use_azure_ad: true }        # preferred: DefaultAzureCredential / Managed Identity
    # OR an API key:
    # auth:
    #   api_key: ${FOUNDRY_API_KEY}

use_azure_ad: true resolves through DefaultAzureCredential: Managed Identity on AKS, ACI, or App Service; the Azure CLI; or environment credentials. API keys work but are project-wide and don't rotate automatically. Microsoft Foundry's endpoint is derived from resource:; set the optional base_url to override it for sovereign clouds such as Azure Government.

Multiple upstreams

The same provider can appear more than once with a distinct name:. This covers different regions, different accounts via different credential chains, provisioned throughput versus on-demand, and cross-provider fallback.

The gateway tries upstreams in order. 5xx, 429, 401, 403, 404, timeouts, and missing-endpoint (501) fail over; other 4xx doesn't.

429 is per-upstream capacity, so provisioned-throughput (PT) exhaustion fails over to on-demand. 404 is per-upstream model availability, so an upstream that hasn't enabled a model doesn't block a later upstream that serves it. An upstream that can't resolve the requested model is skipped without a network round-trip.

This example routes a provisioned-throughput Amazon Bedrock allotment first, overflows to on-demand and a second account, and falls back to the Anthropic API last:

upstreams:
  # Primary: provisioned throughput in your home region.
  - name: bedrock-pt
    provider: bedrock
    region: us-east-1
    auth: {}
  # Overflow: on-demand cross-region.
  - name: bedrock-od
    provider: bedrock
    region: us-west-2
    auth: {}
  # Different account: a separate Bedrock allotment via assumed-role creds.
  - name: bedrock-acct2
    provider: bedrock
    region: us-east-1
    auth:
      aws_access_key_id: ${ACCT2_AKID}
      aws_secret_access_key: ${ACCT2_SK}
  # Last resort: direct Anthropic API.
  - name: anthropic-fallback
    provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}

# Per-upstream model IDs are keyed on the upstream's `name:`.
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    upstream_model:
      bedrock-pt: arn:aws:bedrock:us-east-1:111111111111:provisioned-model/abcdef
      bedrock-od: us.anthropic.claude-opus-4-8
      bedrock-acct2: us.anthropic.claude-opus-4-8
      anthropic-fallback: claude-opus-4-8

Failing over between cloud providers, or to the direct Anthropic API, changes which agreement, geography, and other terms govern the request.

The CLI applies the same feature gating to gateways regardless of which upstream serves a given request, so failover doesn't send a body field an upstream would reject.

Optional sections

admin

Optional. Enables /v1/organizations/spend_limits, which mirrors Anthropic's public Admin API, and per-developer spend enforcement on /v1/messages. See Spend limits for how caps are set and enforced; this section covers the gateway.yaml keys that turn the feature on and tune it.

admin:
  # Named static API keys for the admin endpoints, sent as x-api-key.
  # The id appears in the audit log as admin-key:<id> so each key is
  # attributable. Array for rotation: add the new key, roll clients,
  # remove the old.
  write_keys:
    - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
    - { id: ci,        key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }
  read_keys:
    - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
  # IdP groups granted full admin via the normal gateway JWT (no API key).
  admin_groups: [platform-finops]
  blocked_message: request an increase at https://go.example.com/claude-limits

enforcement

The enforcement block controls how spend-limit checks behave when the store is unavailable.

pricing

The pricing block tells the spend meter what to charge instead of USD list price, so caps and /effective reflect your contracted rates. Amounts stay in USD and remain an estimate, not an invoice. Two prerequisites:

• Claude Code v2.1.227 or later on the gateway server. Earlier versions reject the unknown key at boot.
• An admin: block, because only the spend meter reads pricing. The gateway refuses to start with pricing set and no admin.

pricing:
  multiplier: 0.85
  overrides:
    - upstream: bedrock-eu
      model: claude-sonnet-4-6
      input: 3.30
      output: 16.50
      cache_read: 0.33
      cache_write: 4.125

How the meter matches an override row:

• A row replaces list price for requests that upstream, an upstreams[].name, serves for model. That includes the higher fast mode rate, so fast and standard requests meter at the same four rates.
• A built-in ID such as claude-sonnet-4-6, matched like models[].id, covers every dated form, regional Amazon Bedrock form, or Google Cloud's Agent Platform form the meter prices as that model. Any other string, such as an alias or an inference-profile ARN, matches the ID the client sent or the string sent upstream, case-insensitively.
• Where rows overlap, the meter picks the most specific row rather than the first row: a row whose model is the exact model string sent upstream, then a row matching the exact ID the client sent, then a row naming the built-in model.
• An unknown upstream name fails boot, and so do two rows for one upstream that name the same model, including two spellings of one built-in model. The gateway warns at boot about a row no requestable model can use.
• Web-search requests stay at the $0.01 list price; the multiplier still applies to them.

For per-region rates, give each region its own named upstream and one row per upstream.

models

The models block is an optional admin-curated model list, served at /v1/models and used to translate model IDs per upstream. It is required for non-US Amazon Bedrock regions, Amazon Bedrock provisioned-throughput ARNs, and Microsoft Foundry deployment names.

auto_include_builtin_models: true   # false: expose only the list below
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    # description: optional text shown in clients that surface it
    upstream_model:
      anthropic: claude-opus-4-8
      bedrock: us.anthropic.claude-opus-4-8   # or an inference-profile ARN
      foundry: your-opus-deployment-name

Each key under upstream_model must match the name of a configured upstream, which defaults to the provider name. A key that matches no upstream fails boot, so omit the lines for providers you don't use.

managed

The managed block defines role-based access policies keyed on IdP groups or email domain. Policies are evaluated in order; the first match is selected, then merged onto the match: {} catch-all base described below. They are served per-user at GET /managed/settings with ETag/304 caching.

managed:
  policies:
    # Specific groups first.
    - match: { groups: [eng-contractors] }
      cli:
        availableModels: [claude-sonnet-4-6]
        permissions: { deny: ["WebFetch", "WebSearch"] }
    # Default catch-all last: matches everyone who authenticated.
    - match: {}
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

A match: {} catch-all, conventionally listed last, is treated as a base layer. Every other policy inherits any key it doesn't set from the catch-all, so per-role entries only need to list what differs from the org default. The merge rules depend on the key type:

• Allow-lists: availableModels and permissions.allow. A specific policy's list fully replaces the base's.
• Deny-lists and hook arrays: permissions.deny, permissions.ask, disabledMcpjsonServers, deniedMcpServers, blockedMarketplaces, and every hooks event-type array. These take the union of base and policy, so an org-wide deny or audit hook can't be accidentally dropped by a per-role override.
• Record-typed keys: env, modelOverrides, and skillOverrides. These shallow-merge, so a per-role env block overrides keys it sets and inherits the rest from the base.

availableModels is also enforced server-side at /v1/messages, so a denied model returns 400 regardless of what the client sends.

The gateway validates the model value itself before it relays a request, so a malformed value never reaches an upstream. It rejects the request with a 400 in two cases:

• When the value is missing or empty, the gateway rejects the request with the message model is required. That check requires a gateway running Claude Code v2.1.228 or later.
• When the value is present but isn't a string, the gateway rejects the request with the message model must be a string. Requires a gateway running Claude Code v2.1.221 or later.

An authenticated user who matches no policy gets the gateway's defaults, which means every model in the catalog and no managed settings. Add a match: {} catch-all last if you want a guaranteed default policy.

Matcher values that stop the gateway at boot

At boot, the gateway checks the match block of every policy and the admin_groups list. Any of these values stops the gateway with an error that names the field:

• An empty groups list
• An empty entry in groups or in admin_groups
• An empty email_domain
• An email_domain that contains @, whitespace, or a comma. The gateway trims the value and strips one leading @ before this check. Write one bare domain, such as example.com.

Before v2.1.232, the gateway started with these values. Each value had this effect:

• An empty email_domain: the gateway skipped the domain check, so a policy with an empty email_domain and no groups list matched every authenticated user
• An empty groups list: the policy matched no one
• An email_domain containing @, whitespace, or a comma: the policy matched no one
• An empty entry in groups or in admin_groups: the entry matched a user only when that user's IdP groups claim also contained an empty entry. In admin_groups, that match granted admin access. If your admin_groups list never contained an empty entry, no one gained admin access this way.

What goes in cli

Each cli value is a complete Claude Code managed-settings.json document, the same schema you would deploy via MDM or /etc/claude-code/managed-settings.json, expressed here as YAML. The CLI applies the delivered document at the managed tier, above user and project settings, in place of server-managed settings. It therefore ignores the settings restricted to OS-level policy sources, such as policyHelper and wslInheritsWindowsSettings.

The gateway validates each document against the CLI's settings schema at boot, so an unrecognized top-level key or a recognized key with a malformed value fails boot with an error naming every offending key. Deliberately open parts of the schema still accept arbitrary values, because newer clients may recognize entries the gateway's schema doesn't. These open keys are env, pluginConfigs, and keys nested under permissions.

Because validation uses the schema bundled with the gateway's installed version, putting a top-level settings key introduced by a newer Claude Code release into managed config requires upgrading the gateway first. Smoke-test a new policy on one client before rolling it out.

The full key reference is in Claude Code settings. The keys most operators reach for first:

managed:
  policies:
    - match: {}
      cli:
        # Model access (also enforced server-side at /v1/messages)
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

        # Permission policy
        permissions:
          deny:
            - "WebFetch"
            - "Read(./.env)"
            - "Read(./secrets/**)"
          disableBypassPermissionsMode: disable   # blocks --dangerously-skip-permissions
        allowManagedPermissionRulesOnly: true     # ignore user/project permission rules

        # Environment pushed into the CLI process. DISABLE_UPDATES blocks
        # background and manual updates; DISABLE_AUTOUPDATER stops only
        # background updates.
        env:
          DISABLE_UPDATES: "1"                    # pin versions via your own distribution

        # Org-wide hooks. Hook commands run on developer machines, not the
        # gateway, so the path must exist on every client OS in the policy.
        hooks:
          PostToolUse:
            - matcher: "Edit|Write"
              hooks:
                - { type: command, command: /usr/local/bin/audit-edit.sh }

Because these settings arrive over the network, the CLI shows each developer a security approval dialog before applying the settings listed below:

• hooks
• env variables that require the developer's approval, such as proxy and base-URL variables
• shell-execution settings such as apiKeyHelper and statusLine
• the sandbox binary settings sandbox.bwrapPath, sandbox.socatPath, and sandbox.ripgrep
• managed CLAUDE.md content

Approval memory covers how long an approval lasts and when the dialog appears again.

Claude Code applies some delivered env variables without showing the developer the approval dialog, such as model selection settings and numeric limits. Other delivered variables can require the developer's approval before they take effect; a non-empty proxy, base-URL, or OTEL_EXPORTER_OTLP_ENDPOINT value always does. When a delivered variable needs approval, the dialog names it.

Environment variables and the approval dialog has the details, including four privacy toggles whose delivered value decides whether they need approval. Before v2.1.218, Claude Code applied fewer variables without asking the developer, so more delivered variables triggered the dialog.

The gateway's telemetry configuration pushes OTEL_EXPORTER_OTLP_ENDPOINT, so setting telemetry.forward_to triggers the dialog on each interactive client. The dialog protects the developer's machine from a compromised or hostile gateway, not the organization from the developer.

A non-interactive run with the -p flag can't show the dialog. It applies the pushed settings for that run only and doesn't record them as approved, so the developer's next interactive session still shows the dialog. Before v2.1.207, a non-interactive run saved the settings as approved and no later interactive session showed the dialog for them.

If a developer declines, Claude Code exits that session rather than applying the policy. When you push a new hook, or any env var that triggers the dialog, to a broad policy, Claude Code therefore shows the dialog to every matching developer. It shows the dialog in a running session on the next hourly poll, and otherwise at the developer's next startup.

The cli key was named settings in earlier releases. That spelling is still accepted as an alias, but new deployments should use cli.

Claude Desktop overlay

If your organization also deploys Claude Desktop, the same gateway serves both clients. Point bootstrapUrl, in Claude Desktop's managed configuration, at <listen.public_url>/user/bootstrap. Claude Desktop derives the OAuth issuer from that URL, runs the same device-code sign-in against this gateway, and fetches its configuration from the response.

The gateway derives much of the response from the matched policy's cli block and from top-level gateway config:

• The model list, from availableModels
• Disabled tools, from bare tool-name permissions.deny entries. If you set disabledBuiltinTools in the policy's desktop block, the gateway serves the union of your value and the derived list, so you can disable more tools this way but can't re-enable one you disabled through permissions.deny
• The egress allowlist, from sandbox.network.allowedDomains. If you set coworkEgressAllowedHosts in the policy's desktop block, the gateway uses that value instead of the derived list
• An OTLP endpoint that points at the gateway itself, which fans out to your destinations, included when telemetry forwarding is configured

To set disabledBuiltinTools or coworkEgressAllowedHosts in a policy's desktop block, you need Claude Code v2.1.232 or later on the gateway server.

The gateway omits keys with no Claude Desktop equivalent, such as hooks and scoped permission rules like Bash(npm *), from the bootstrap response.

Add the optional desktop block alongside cli to set Claude Desktop settings directly. Write settings from Claude Desktop's managed configuration reference as flat key names. Leave out keys Claude Desktop reads only from MDM or local files, such as bootstrapUrl; the gateway rejects them at boot. Before v2.1.232, the gateway accepted a fixed list of 11 feature-gate keys, such as chatTabEnabled and disableAutoUpdates, and rejected every other key at boot. Before v2.1.227, the gateway also rejected chatTabEnabled and chatAdvancedFileAnalysisEnabled at boot.

managed:
  policies:
    - match: { groups: [eng-contractors] }
      cli:
        availableModels: [claude-sonnet-4-6]
      desktop:
        isLocalDevMcpEnabled: false
        disableAutoUpdates: true
        banner: { text: "Contractor build: internal use only" }

Every key is optional; Claude Desktop applies its own default for any key you omit. The gateway validates each desktop block at boot against the configuration schema Claude Desktop itself uses, so a mistake surfaces at gateway start as an error naming the key rather than reaching every connected desktop. The gateway fails at boot when a block contains:

• An unknown key
• A recognized key whose value Claude Desktop would reject or silently drop, such as an empty value or a misspelled sub-key inside a nested entry
• A key the gateway computes itself: the inference connection, the model list, and the OTLP relay. Configure those through upstreams, models, and the telemetry section's forward_to.
• A legacy alias of a current key. In the boot error, the gateway names the canonical key to write.

As with the cli block, the gateway validates against the schema bundled with its installed version. To deliver a setting introduced by a newer Claude Desktop release, upgrade the gateway first.

The gateway fills in keys a policy's desktop block doesn't set from the match: {} catch-all's desktop block, the same way it fills in a policy's cli block from the base. If you set disabledBuiltinTools or builtinToolPolicy in both the base and a role policy, the gateway keeps the base's restriction:

• disabledBuiltinTools: the gateway uses the union of the base's list and the policy's list
• builtinToolPolicy: if you set a tool to a value other than allow in the base, the gateway keeps that value even if you set allow for the same tool in a role policy

For every other key, if you set it in the role policy, the gateway uses the role policy's value. The gateway replaces an array or a nested object such as banner whole, so if you set banner.text in a role policy, the gateway drops the base's banner.backgroundColor.

If you don't deploy Claude Desktop, leave desktop out of your policies entirely; the gateway then returns 404 from /user/bootstrap for every user.

Precedence with other managed sources

If a device also has an MDM-delivered policy or a local managed-settings.json, Claude Code doesn't merge the managed sources: gateway-delivered settings rank first, so the local sources supply the policy only when the gateway delivers no policy key. Precedence within the managed tier on the managed settings page has the full ranking and the keys Claude Code reads from every admin source regardless of which source it selected, such as the sandbox lock keys, forceRemoteSettingsRefresh, and the per-variable env merge. A policyHelper configured in an MDM profile or the managed settings file runs only when the gateway delivers no settings; the entry says what its output replaces.

Embedding hosts such as Claude Desktop can supply policy through the SDK managedSettings option. Parent settings from embedding hosts says when Claude Code applies it, and Restrict parent settings lists which allow-direction settings still apply without the allowManaged*Only locks.

Gateway policies apply to every Claude Code invocation on the machine, including non-interactive claude -p runs and sessions spawned by the Agent SDK. If the gateway is unreachable at startup, signed-in sessions exit with an error rather than running without their policy.

telemetry

The CLI sends OpenTelemetry Protocol (OTLP) over HTTP metrics, logs, and, when enabled, traces to the gateway, which relays them verbatim to each configured destination. See Monitoring usage for the metrics and events the CLI emits.

The CLI stamps each export with the authenticated user's identity, read from the gateway-issued JWT: the user.id, user.email, and user.groups attributes. Per-developer cost and usage attribution therefore works with no developer-side configuration.

telemetry:
  forward_to:
    - url: https://otel-collector.internal.example.com
      headers:
        Authorization: ${OTLP_TOKEN}
      # Per-signal opt-in. Default: metrics only.
      metrics: true
      logs: false
      traces: false
    - url: https://api.datadoghq.com/api/v2/otlp
      headers:
        DD-API-KEY: ${DD_API_KEY}

Each forward_to URL must use https://, with one exception for a collector on the gateway's own loopback interface:

• http://localhost:<port> passes config validation, but the SSRF guard blocks every export with ECONNREFUSED_SSRF unless you set CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 in the gateway's environment
• http://127.0.0.1:<port> or http://[::1]:<port> fails boot unless that variable is set

For an in-cluster collector, expose it over HTTPS at its own internal address, or run it as a sidecar with the variable set.

Telemetry is off in the CLI by default. Configuring telemetry.forward_to together with listen.public_url turns it on. The gateway pushes six env vars to every connected client through /managed/settings:

• CLAUDE_CODE_ENABLE_TELEMETRY=1
• OTEL_METRICS_EXPORTER=otlp
• OTEL_LOGS_EXPORTER=otlp
• OTEL_TRACES_EXPORTER=otlp
• OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>
• OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

The pushed endpoint is built from the public URL, so metrics and logs need no OTEL configuration from developers or policies. The pushed configuration is applied at the managed tier, overriding OTEL_* variables a developer sets locally. Whether or not the gateway pushes these variables, a CLI signed in through /login that has OTLP/HTTP export enabled sends its exports to the gateway rather than to a locally configured endpoint, and without a forward_to destination for a signal the gateway accepts and discards it; if you already collect Claude Code telemetry directly, add your collector as a forward_to destination.

Traces additionally require CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 on each client. The gateway doesn't push that variable, so set it through a managed policy's env block. It isn't among the variables Claude Code applies without the developer's approval, so delivering it through a policy is covered by the same security approval dialog that the pushed OTLP endpoint already triggers.

Both protobuf and JSON OTLP encodings are relayed, and any OpenTelemetry-compatible backend works as a destination.

HTTP tuning

Four optional top-level blocks, access_control, limits, timeouts, and rate_limits, tune the HTTP surface. The defaults suit most deployments.

Complete example

This full reference config exercises every core section; the HTTP tuning blocks keep their defaults. Copy it, delete what you don't need, and fill in your values. The config in the Quickstart is a minimal version of this.

# Run with:
#   claude gateway --config gateway.yaml
#
# Operational log verbosity is controlled by the CLAUDE_GATEWAY_LOG_LEVEL
# environment variable (debug | info | warn | error; default info). debug
# also logs the claim names in each id_token, for groups_claim diagnosis.
# It does not affect audit events, which are always emitted.

listen:
  host: 0.0.0.0
  port: 8080
  public_url: https://claude-gateway.internal.example.com
  # Omit the tls block when running behind a TLS-terminating ingress.
  # tls:
  #   cert: /certs/gateway.crt
  #   key: /certs/gateway.key
  # trusted_proxies:
  #   - 10.0.0.0/8

oidc:
  issuer: https://example.okta.com
  client_id: 0oa1example2
  client_secret: ${OIDC_CLIENT_SECRET}
  allowed_email_domains:
    - example.com
  # Required when the issuer is the Okta org server, whose id_tokens
  # can omit email and groups; the gateway fills them from /userinfo.
  userinfo_fallback: true
  # allowed_groups: [claude-code-users]
  # Okta emits groups only when the `groups` scope is requested and the
  # app's groups claim filter allows them. The contractors policy below
  # matches on groups, so the scope is requested here.
  scopes: [openid, profile, email, offline_access, groups]
  # extra_auth_params: { access_type: offline, prompt: consent }  # Google
  # groups_claim: groups          # Entra app roles: use `roles`
  # email_claim: email

session:
  jwt_secret: ${GATEWAY_JWT_SECRET}   # openssl rand -base64 32
  # ttl_hours: 1

store:
  postgres_url: ${GATEWAY_POSTGRES_URL}
  # max_connections: 5

# Enables /v1/organizations/spend_limits (mirrors the Anthropic Admin API)
# and per-developer spend enforcement on /v1/messages. Omit to disable.
# Caps themselves are set via the admin API, not here.
# admin:
#   write_keys:
#     - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
#   read_keys:
#     - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
#   admin_groups: [platform-finops]
#   blocked_message: request an increase at https://go.example.com/claude-limits
#   # audit_retention_days: 365
#   # spend_retention_months: 13
#   # identity_retention_days: 90
#   # group_limit_mode: min

# enforcement:
#   fail_closed_on_error: false

# Meter at contracted rates instead of USD list price. Requires admin:.
# Rates below are placeholders, not real contract prices.
# pricing:
#   multiplier: 0.85
#   overrides:
#     - { upstream: anthropic, model: claude-sonnet-4-6, input: 3.30, output: 16.50, cache_read: 0.33, cache_write: 4.125 }

upstreams:
  - provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}

  # - provider: bedrock
  #   region: us-east-1
  #   auth: {}

  # - provider: anthropicAws
  #   region: us-east-1
  #   workspace_id: wrkspc_...
  #   auth:
  #     api_key: ${ANTHROPIC_AWS_API_KEY}

  # - provider: vertex
  #   region: us-east5
  #   project_id: example-prod
  #   auth: {}

  # - provider: foundry
  #   resource: example-foundry
  #   auth: { use_azure_ad: true }

auto_include_builtin_models: true
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    upstream_model:
      anthropic: claude-opus-4-8
      # bedrock: us.anthropic.claude-opus-4-8
      # anthropicAws: claude-opus-4-8
      # vertex: claude-opus-4-8
      # foundry: <your-opus-deployment-name>
  - id: claude-sonnet-4-6
    label: Claude Sonnet 4.6
    upstream_model:
      anthropic: claude-sonnet-4-6
  - id: claude-haiku-4-5
    label: Claude Haiku 4.5
    upstream_model:
      anthropic: claude-haiku-4-5

managed:
  policies:
    - match: { groups: [contractors] }
      cli:
        availableModels: [claude-haiku-4-5]
        # Constrain the Default picker option to availableModels instead of
        # the tier default, so contractors don't get a 400 on the default.
        enforceAvailableModels: true
        # allow auto-approves these tools; it does not block the rest.
        # Add deny rules to restrict tools.
        permissions: { allow: [Read, Grep] }
    - match: {}
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
        permissions:
          allow: [Read, Grep, Bash, Edit]
          deny: ["WebFetch"]
        env: { HTTP_PROXY: http://proxy.example.com:8080 }

telemetry:
  forward_to:
    - url: https://otel.internal.example.com:4318
      headers:
        Authorization: Bearer ${OTEL_TOKEN}

Client-side managed settings

Everything above configures the gateway server. You point developer machines at the gateway separately, on each device, through Claude Code's managed settings. The gateway can't push the login keys itself, because they're what tell the client where the gateway is.

For the CLI, set these keys in the per-OS managed-settings.json. The two login keys route each developer's /login to your gateway:

{
  "forceLoginMethod": "gateway",
  "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com",
  "parentSettingsBehavior": "merge"
}

parentSettingsBehavior: "merge" keeps Claude Desktop's delivery of the egress allowlist to its embedded Claude Code sessions working; Deliver policy to Claude Desktop sessions explains the mechanism and where the opt-in must sit.

Deploy the managed-settings.json file to each device, typically via your MDM platform. The file path differs by platform:

A registry policy on Windows or a managed-preferences plist on macOS replaces the managed-settings.json file rather than merging with it, apart from the exception keys and cross-source checks above. All three keys in this snippet follow the highest-priority-source rule, so fleets that deliver policy through Group Policy or configuration profiles must put all three in that mechanism instead.

For Claude Desktop, set the bootstrapUrl key in Claude Desktop's own managed configuration to <listen.public_url>/user/bootstrap. The sign-in flow and per-group policy then match the CLI's once a policy opts in server-side with a desktop key; without the opt-in, /user/bootstrap returns 404. See Claude Desktop overlay for the server-side half.

forceLoginGatewayUrl, and the "gateway" value of forceLoginMethod, are honored only from a managed source on the machine: managed-settings.json, the macOS plist or Windows HKLM registry, or a policy helper. A developer setting them in their own ~/.claude/settings.json has no effect, and neither does setting them in the gateway payload.

Related

• Claude apps gateway overview: quickstart and developer connection
• Deployment guide: IdP setup, container image, Kubernetes and Cloud Run, and operations
• Spend limits: per-developer caps and the Admin API