configuration-reference changedmanaged-agents/self-hosted/configuration-reference
Recorded here
Lines+316added
Lines−0removed
From line
—
no hunk to open at
First seen
12 Nov 2026
this site's first read of the page
Recorded edits1to this page, all time
## Where settings go ### Pass a credential to the Compose stack ## How to read the tables ## Server and logging ## Database ## Inference provider ### Cloud providers ### Model gateway ### Short-lived gateway tokens ## Single sign-on ### Issuer entries ## Secret manager ### HashiCorp Vault ## Agent identity ## Egress gateway ## MCP servers ## Git repositories ## Web tools and skills ## Limits, timeouts, and scheduling ## Models and compaction ### Model entries ## Console on your server
The whole hunk
316 lines, new page
/
lines
A whole new page. There's nothing to diff it against, so here is what it says.
---
title: Configuration reference
url: https://platform.claude.com/docs/en/managed-agents/self-hosted/configuration-reference
description: See where the settings of a self-hosted Claude Managed Agents server go, and look up each setting's key, environment variable, default, and purpose.
---
<Note>
To request access to self-hosted Claude Managed Agents, contact your Anthropic account team.
</Note>
This page shows where the settings of a self-hosted Claude Managed Agents server go, and lists them. To set up a feature, see [Single sign-on](https://platform.claude.com/docs/en/managed-agents/self-hosted/configure), [Agent identity and credentials](https://platform.claude.com/docs/en/managed-agents/self-hosted/agent-identity), and [Inference provider](https://platform.claude.com/docs/en/managed-agents/self-hosted/inference-provider).
## Where settings go
The server reads its settings from one YAML file, and its credentials from its environment.
* **Docker Compose:** The file is `compose.config.yaml`, beside `docker-compose.yml` in the extracted archive. Edit it, then run `docker compose restart cma-server` from that directory.
* **Kubernetes:** The file is the `server.config` value of the server Helm chart. Edit it in your values file, run `helm upgrade`, and then restart the servers with `kubectl -n cma-server rollout restart deployment -l anthropic.com/role=server`. See [Deploy on Kubernetes](https://platform.claude.com/docs/en/managed-agents/self-hosted/kubernetes).
If the server rejects a setting that the self-hosted pages show, [upgrade the server](https://platform.claude.com/docs/en/managed-agents/self-hosted/upgrade). `cma-server.example.yaml`, at the top of the archive, annotates the common keys.
Credentials never go in the file. The server reads them from environment variables, or from the identity that your cloud attaches to the host.
### Pass a credential to the Compose stack
In the Compose stack, the server container receives only the variables in the `environment:` list of the `cma-server` service in `docker-compose.yml`. To pass another one:
1. Add its name to that list, and set its value in `.env`.
2. If the credential is a file, put the file beside `docker-compose.yml`, and add a line such as `- ./gcp-key.json:/etc/cma-server/gcp-key.json:ro` to the `x-server-mounts` list in `docker-compose.yml`. The path after the first colon is the file’s path inside the container. Use that path as the variable’s value in `.env`, or as the value of the setting that names the file.
3. Run `docker compose up -d`. A restart doesn’t reread `.env`.
An upgrade replaces `docker-compose.yml`, so repeat these edits in the new release’s file before you start its stack.
## How to read the tables
Each setting has a key in the [settings file](https://platform.claude.com/docs/en/managed-agents/self-hosted/configuration-reference#where-settings-go), and most settings also have an environment variable. A variable overrides the file, and the file overrides the default. The server doesn’t start if its settings file has an unknown key, and the error says where the key is.
* **Keys:** Each dot in a key is a level of nesting in the file. For example, `server.addr` is the `addr` key in the `server` section.
* **Variables:** A variable’s name is `CMA_` and then the key in capitals, with two underscores in place of each dot.
* **File only:** The setting has no variable.
* **Environment only:** The server doesn’t start if the setting is in the file.
* **`bedrock` only, and similar labels:** The setting works only with that provider, store, or secret manager. If you set it while you use a different one, the server doesn’t start.
* **Lists:** A list is a YAML list in the file, and a comma-separated string in a variable.
* **Durations:** A duration is a number with a unit, such as `30s`, `5m`, or `1h`.
* **Integers:** An integer is plain digits, with no sign, leading zero, or underscore.
At startup, the server logs the settings that you set and most defaults, each with where its value came from, such as `server.addr=0.0.0.0:8400 (file)`. It logs `***` in place of a secret, except a server API key that it generated itself.
## Server and logging
| Setting<br />Environment variable | Default | Description |
| --------------------------------------------------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `server.addr`<br />`CMA_SERVER__ADDR` | `127.0.0.1:8400` | The address that the server listens on. |
| `server.api_key`<br />`CMA_SERVER__API_KEY` | None | The [server API key](https://platform.claude.com/docs/en/managed-agents/self-hosted#the-three-credentials). Required with `store.backend: postgres`, unless `auth.refuse_server_api_key` is `true`. With `memory`, the server generates a key if you set none, and logs it at startup. |
| `server.id_marker`<br />`CMA_SERVER__ID_MARKER` | `local` | What follows the prefix in each ID that the server creates. `local` gives `sesn_local_01…`, and `none` gives `sesn_01…`, as on the hosted service. |
| `server.shutdown_delay`<br />`CMA_SERVER__SHUTDOWN_DELAY` | `0s` | How long the server keeps serving after a stop signal, while its readiness probe answers `not_ready`. The maximum is `5m`. |
| `server.max_connections`<br />`CMA_SERVER__MAX_CONNECTIONS` | `0` | The most connections that the server holds open at once on `server.addr`. `0` means no limit. At the limit, a new connection waits until another closes or its client gives up. Event streams, worker polls, and health probes all count. On Kubernetes, the kubelet restarts a pod whose probes wait too long. |
| `logging.format`<br />`CMA_LOGGING__FORMAT` | `text` | The log format, `text` or `json`. |
| `logging.level`<br />`CMA_LOGGING__LEVEL` | `info` | The lowest level that the server logs. The values are `debug`, `info`, `warn`, and `error`. |
| `logging.errors`<br />`CMA_LOGGING__ERRORS` | `false` | Whether the log includes the error messages of `4xx` and `5xx` responses. A message can quote a value that the client sent. |
| `health.check_interval`<br />`CMA_HEALTH__CHECK_INTERVAL` | `60s` | How often the server checks its inference credential for the readiness probe. The minimum is `5s`. |
| `health.upstream_affects_readiness`<br />`CMA_HEALTH__UPSTREAM_AFFECTS_READINESS` | `true` | Whether the readiness probe answers `503` while the inference provider rejects the server’s credential. |
## Database
Every setting in this table except `store.backend` applies only with `store.backend: postgres`.
| Setting<br />Environment variable | Default | Description |
| ------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `store.backend`<br />`CMA_STORE__BACKEND` | `memory` | Where the server keeps its data. The values are `memory`, which a restart erases, and `postgres`. |
| `store.database_url`<br />`CMA_STORE__DATABASE_URL` | None | The PostgreSQL connection string. Required with `postgres`. |
| `store.control_database_url`<br />`CMA_STORE__CONTROL_DATABASE_URL` | The value of `store.database_url` | The connection string for the server’s own upkeep connections, such as its heartbeat. |
| `store.listen_database_url`<br />`CMA_STORE__LISTEN_DATABASE_URL` | The value of `store.database_url` | The connection string for the one connection on which the server listens for notifications. A connection pooler in transaction mode can’t carry that connection. |
| `store.migrate_database_url`<br />`CMA_STORE__MIGRATE_DATABASE_URL` | The value of `store.database_url` | The connection string that the server’s `migrate` command uses. A connection pooler in transaction mode can’t carry that connection. |
| `store.pool_max_conns`<br />`CMA_STORE__POOL_MAX_CONNS` | `24` | The most database connections that one server’s pool opens. The minimum is `4`. |
| `store.event_poll_interval`<br />`CMA_STORE__EVENT_POLL_INTERVAL` | `25ms` | How often each server asks the database for the latest events in the sessions that its clients are streaming. An event that another server recorded waits at most about this long to reach the stream. |
| `store.credentials_encryption_key`<br />`CMA_STORE__CREDENTIALS_ENCRYPTION_KEY`<br />Environment only | None | The key that encrypts stored credentials in the database, as 32 random bytes in base64. The Docker Compose and Kubernetes installs set it. The server doesn’t start without it, unless `store.allow_unencrypted_credentials` is `true`. |
| `store.allow_unencrypted_credentials`<br />`CMA_STORE__ALLOW_UNENCRYPTED_CREDENTIALS` | `false` | Whether the server can start without `store.credentials_encryption_key`. Without the key, it stores credentials in the database in plain text. `true` has no effect if `git.allowed_hostnames` lists a host, or if you install with Docker Compose or the server Helm chart. |
| `store.credentials_encryption_keys_retiring`<br />`CMA_STORE__CREDENTIALS_ENCRYPTION_KEYS_RETIRING`<br />Environment only | None | Earlier encryption keys that the server can still decrypt with during a key rotation. This setting needs `store.credentials_encryption_key`. |
## Inference provider
To set up a provider, see [Inference provider](https://platform.claude.com/docs/en/managed-agents/self-hosted/inference-provider).
| Setting<br />Environment variable | Default | Description |
| -------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inference.provider`<br />`CMA_INFERENCE__PROVIDER` | `anthropic` | Where the server sends model calls. The values are `anthropic`, `bedrock`, `vertex`, `foundry`, and `gateway`. |
| `inference.headers`<br />File only | None | Request headers that the server adds to every model call, as a map of header name to value. Quote every value. The server refuses to start on an unquoted value that YAML doesn’t read as text, such as `true` or `0042`. With `gateway`, a value can also be `{ from: request_id }` or `{ from: session_id }`. |
| `inference.model_fallback`<br />`CMA_INFERENCE__MODEL_FALLBACK` | `true` | `anthropic` only. Whether model calls ask for [server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback). Those calls carry a `fallbacks` field and the header `anthropic-beta: server-side-fallback-2026-07-01`. A proxy that you name in `ANTHROPIC_BASE_URL` might reject the field or the header. If it answers with a `400` or a `422`, the server sends the call again without them. |
| `inference.metadata.user_id`<br />`CMA_INFERENCE__METADATA__USER_ID` | None | `anthropic` and `foundry` only, or `gateway` with `format: anthropic-messages`. One identifier that the server sends as `metadata.user_id` with every model call. The startup log prints it. Without this setting, the server sends the label `cma-server`. You can’t turn `metadata.user_id` off. If the provider or a proxy rejects it, every model call fails. See [What leaves your network](https://platform.claude.com/docs/en/managed-agents/self-hosted-data-and-access#what-leaves-your-network). |
### Cloud providers
| Setting<br />Environment variable | Default | Description |
| -------------------------------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inference.region`<br />`CMA_INFERENCE__REGION` | None | `bedrock` and `vertex` only. The AWS Region, or the location in Google Cloud’s Agent Platform. Required with `vertex`. Without it, `bedrock` uses the Region that the AWS SDK’s default chain finds. |
| `inference.project_id`<br />`CMA_INFERENCE__PROJECT_ID` | None | `vertex` only. The Google Cloud project that the calls are made in. Required unless the Google credential names a project. |
| `inference.api`<br />`CMA_INFERENCE__API` | `invoke_model` | `bedrock` only. The Amazon Bedrock API that carries the calls, `invoke_model` or `messages`. `messages` is the endpoint that [Claude in Amazon Bedrock (`bedrock-mantle`)](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) describes. With it, the server’s AWS role needs `bedrock-mantle:CreateInference` in place of `bedrock:InvokeModel` and `bedrock:InvokeModelWithResponseStream`. |
| `inference.list_models`<br />`CMA_INFERENCE__LIST_MODELS` | `true` | `bedrock` only. Whether the server reads Amazon Bedrock’s lists of Claude models. With those lists, agents can use a model that came out after your server’s release. |
| `inference.model_id_prefix`<br />`CMA_INFERENCE__MODEL_ID_PREFIX` | `us.anthropic.` | `bedrock` only. The text that the server puts before each model ID. With `inference.api: messages`, the default is `anthropic.`. |
| `inference.model_id_overrides`<br />File only | None | `bedrock`, `vertex`, and `foundry` only. A map of model ID to the exact ID that the provider expects. With `foundry`, that ID is a deployment name. |
| `inference.foundry.resource`<br />`CMA_INFERENCE__FOUNDRY__RESOURCE` | None | `foundry` only. The name of the Foundry resource. Set this or `inference.foundry.base_url`, not both. |
| `inference.foundry.base_url`<br />`CMA_INFERENCE__FOUNDRY__BASE_URL` | None | `foundry` only. By default, calls go to `https://<resource>.services.ai.azure.com/anthropic`. To reach the resource at another address, such as a proxy, set that URL here instead. It ends in `/anthropic`. |
### Model gateway
These settings apply only with `inference.provider: gateway`. See [Model gateway](https://platform.claude.com/docs/en/managed-agents/self-hosted/inference-provider#model-gateway).
| Setting<br />Environment variable | Default | Description |
| ----------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `inference.gateway.url`<br />`CMA_INFERENCE__GATEWAY__URL` | None | Required. The URL that receives model calls. With `bedrock-invoke` and `vertex-raw-predict`, `{model}` marks where the model ID goes. With `vertex-raw-predict`, the URL must end in `/{model}:rawPredict`. |
| `inference.gateway.format`<br />`CMA_INFERENCE__GATEWAY__FORMAT` | None | Required. The request format that the gateway accepts: `bedrock-invoke`, `anthropic-messages`, or `vertex-raw-predict`. |
| `inference.gateway.model_map`<br />File only | None | Required. A map of each model ID that agents can name to the ID that the gateway expects. Quote every value, as for `inference.headers`. |
| `inference.gateway.streaming`<br />`CMA_INFERENCE__GATEWAY__STREAMING` | `false` | Whether the server sends the format’s streamed call, so that replies arrive as the model produces them. With `bedrock-invoke`, that call goes to the same URL with `-with-response-stream` appended. With `vertex-raw-predict`, that call goes to the same URL with `:streamRawPredict` in place of `:rawPredict`. Leave `:rawPredict` in `inference.gateway.url`. |
| `inference.credentials.supplier`<br />`CMA_INFERENCE__CREDENTIALS__SUPPLIER` | None | Required. Where the gateway’s credential comes from. `env` means one long-lived key, `oauth_exchange` means short-lived tokens, and `azure` means Microsoft Entra ID tokens issued to the server’s own Azure identity. |
| `inference.credentials.env.var`<br />`CMA_INFERENCE__CREDENTIALS__ENV__VAR` | None | Required with `env`. The name of the environment variable that holds the key. |
| `inference.credentials.azure.scope`<br />`CMA_INFERENCE__CREDENTIALS__AZURE__SCOPE` | None | Required with `azure`. The scope that the server requests tokens for: the application ID URI or the application ID of your gateway’s app registration, followed by `/.default`. |
| `inference.credentials.send_as.header`<br />`CMA_INFERENCE__CREDENTIALS__SEND_AS__HEADER` | `Authorization` | The request header that carries the credential. |
| `inference.credentials.send_as.scheme`<br />`CMA_INFERENCE__CREDENTIALS__SEND_AS__SCHEME` | `Bearer` | The word that precedes the credential in the header. Under any header other than `Authorization`, the default is no scheme. |
| `inference.credentials.renew_before`<br />`CMA_INFERENCE__CREDENTIALS__RENEW_BEFORE` | `90s` | With `oauth_exchange`, how early the server replaces a token. It stops using a cached token this long before the token expires, and gets another one for the next model call. Keep the value below your tokens’ lifetime. The server refuses any token that is valid for less than this value. |
### Short-lived gateway tokens
These settings apply only with `inference.credentials.supplier: oauth_exchange`. See [Short-lived tokens](https://platform.claude.com/docs/en/managed-agents/self-hosted/inference-provider#short-lived-tokens). The `exchange` settings are optional as a group. Without them, the server sends the gateway what the callback returns.
| Setting<br />Environment variable | Default | Description |
| ----------------------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inference.credentials.assertion.url`<br />`CMA_INFERENCE__CREDENTIALS__ASSERTION__URL` | None | Required. The URL of the HTTP callback that returns a signed assertion. |
| `inference.credentials.assertion.auth.type`<br />`CMA_INFERENCE__CREDENTIALS__ASSERTION__AUTH__TYPE` | None | Required. How the server authenticates to the callback, `mtls` or `bearer_file`. |
| `inference.credentials.assertion.auth.cert_file`<br />`CMA_INFERENCE__CREDENTIALS__ASSERTION__AUTH__CERT_FILE` | None | Required with `mtls`. The path of the server’s client certificate. |
| `inference.credentials.assertion.auth.key_file`<br />`CMA_INFERENCE__CREDENTIALS__ASSERTION__AUTH__KEY_FILE` | None | Required with `mtls`. The path of the client certificate’s private key. |
| `inference.credentials.assertion.auth.token_file`<br />`CMA_INFERENCE__CREDENTIALS__ASSERTION__AUTH__TOKEN_FILE` | None | Required with `bearer_file`. The path of a file that holds the bearer token. |
| `inference.credentials.assertion.auth.ca_file`<br />`CMA_INFERENCE__CREDENTIALS__ASSERTION__AUTH__CA_FILE` | None | The path of a PEM file with the certificate authorities that the server trusts for the callback. |
| `inference.credentials.assertion.forward_metadata`<br />`CMA_INFERENCE__CREDENTIALS__ASSERTION__FORWARD_METADATA` | None | The session metadata keys whose values the server sends to the callback. They arrive as `session.metadata` in the request body. The values are whatever the API caller wrote, so check them against your own records. |
| `inference.credentials.exchange.token_url`<br />`CMA_INFERENCE__CREDENTIALS__EXCHANGE__TOKEN_URL` | None | Required for an exchange. The OAuth token endpoint where the server exchanges the assertion for a token. |
| `inference.credentials.exchange.grant_type`<br />`CMA_INFERENCE__CREDENTIALS__EXCHANGE__GRANT_TYPE` | None | Required for an exchange. The `grant_type` that the server sends, such as `urn:ietf:params:oauth:grant-type:jwt-bearer`. |
| `inference.credentials.exchange.encoding`<br />`CMA_INFERENCE__CREDENTIALS__EXCHANGE__ENCODING` | `form` | How the server encodes the exchange request, `form` or `multipart`. |
| `inference.credentials.exchange.expiry`<br />`CMA_INFERENCE__CREDENTIALS__EXCHANGE__EXPIRY` | `expires_in` | Where the server reads the token’s lifetime. `expires_in` means the earlier of the response’s `expires_in` and the token’s `exp` claim. `jwt_exp` means the `exp` claim alone. |
| `inference.credentials.exchange.headers`<br />File only | None | Extra request headers for the token endpoint, as a map of header name to value. Quote every value, as for `inference.headers`. |
| `inference.credentials.exchange.ca_file`<br />`CMA_INFERENCE__CREDENTIALS__EXCHANGE__CA_FILE` | None | The path of a PEM file with the certificate authorities that the server trusts for the token endpoint. |
## Single sign-on
To set up sign-in, see [Single sign-on](https://platform.claude.com/docs/en/managed-agents/self-hosted/configure).
| Setting<br />Environment variable | Default | Description |
| ------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auth.issuers`<br />File only | None | The OpenID Connect issuers whose tokens the server accepts. See [Issuer entries](https://platform.claude.com/docs/en/managed-agents/self-hosted/configuration-reference#issuer-entries). |
| `auth.refuse_server_api_key`<br />File only | `false` | Whether the server refuses the server API key on every route. `true` needs at least one issuer. Every admin CLI command that takes the key then fails. |
### Issuer entries
Each entry of `auth.issuers` takes these fields:
| Field | Default | Description |
| ----------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name` | None | Required. A label for the issuer in log lines. The server also records it as part of the creator of each resource. |
| `issuer_url` | None | Required. The issuer’s URL, exactly as in the `iss` claim of its tokens. The server fetches signing keys from this host and from the `jwks_uri` host that the issuer’s discovery document names. If your network limits outbound connections, admit both hosts. |
| `audiences` | None | Required. The values that a token’s `aud` claim can carry. If applications forward tokens that they already hold, list each application’s client ID. |
| `roles` | None | A list of `group` and `role` pairs. A group matches exactly, or as a pattern in which `*` stands for any run of characters and `?` for one character. A role is `admin`, `developer`, or `user`. The highest matching role wins. Set `roles`, `default_role`, or both. |
| `default_role` | None | The role of a caller whose groups match no `roles` entry. Set it only if everyone who can get a token for this audience should have access. |
| `subject_claim` | `sub` | The claim that identifies the caller. A name that starts with `/` is a JSON Pointer into nested claims. |
| `stable_subject` | `false` | Applies only if `subject_claim` names a claim other than `sub` or `oid`. Set `true` to confirm that your provider never changes a person’s value of that claim and never gives it to someone else. The server doesn’t check this. With `false`, [agent tokens](https://platform.claude.com/docs/en/managed-agents/self-hosted/configuration-reference#agent-identity) omit the `actor_sub` and `actor_iss` claims. |
| `groups_claim` | `groups` | The claim that lists the caller’s groups. A name that starts with `/` is a JSON Pointer into nested claims. |
| `jwks_file` | None | The path of a JSON Web Key Set file. The server reads signing keys from it and never contacts the issuer. |
| `login_client_id` | None | The client ID of the application that [terminal login](https://platform.claude.com/docs/en/managed-agents/self-hosted/configure#let-developers-log-in-from-a-terminal) uses. Only one issuer can set it. |
| `login_scopes` | `[openid]` | The scopes that the login requests. This field needs `login_client_id`. |
## Secret manager
To set up a store, see [Secret manager](https://platform.claude.com/docs/en/managed-agents/self-hosted/agent-identity#secret-manager).
| Setting<br />Environment variable | Default | Description |
| ----------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `secret_store.type`<br />`CMA_SECRET_STORE__TYPE` | None | The secret manager that holds vault credentials. The values are `aws_secrets_manager`, `gcp_secret_manager`, `azure_key_vault`, and `hashicorp_vault`. Without it, vault credentials stay in the database. |
| `secret_store.prefix`<br />`CMA_SECRET_STORE__PREFIX` | None | Required with `secret_store.type`. The start of the name of every secret that the server creates. It must end with `/` for `aws_secrets_manager` and `hashicorp_vault`, with `-` or `_` for `gcp_secret_manager`, and with `-` for `azure_key_vault`. |
| `secret_store.region`<br />`CMA_SECRET_STORE__REGION` | None | `aws_secrets_manager` only, and required there. The AWS Region that holds the secrets. |
| `secret_store.project`<br />`CMA_SECRET_STORE__PROJECT` | None | `gcp_secret_manager` only, and required there. The ID of the Google Cloud project that holds the secrets. |
| `secret_store.vault_url`<br />`CMA_SECRET_STORE__VAULT_URL` | None | `azure_key_vault` only, and required there. The key vault’s URL, such as `https://my-vault.vault.azure.net`. |
### HashiCorp Vault
These settings apply only with `secret_store.type: hashicorp_vault`. Set exactly one login method: `token_file`, `kubernetes`, or `approle`.
| Setting<br />Environment variable | Default | Description |
| -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `secret_store.address`<br />`CMA_SECRET_STORE__ADDRESS` | None | Required. The Vault server’s `https://` URL. |
| `secret_store.namespace`<br />`CMA_SECRET_STORE__NAMESPACE` | None | The Vault Enterprise namespace that holds the mount and the login method. |
| `secret_store.mount`<br />`CMA_SECRET_STORE__MOUNT` | `secret` | The path of the KV version 2 secrets engine. |
| `secret_store.ca_cert_file`<br />`CMA_SECRET_STORE__CA_CERT_FILE` | None | The path of a PEM file with the certificate authority that signed Vault’s certificate. |
| `secret_store.token_file`<br />`CMA_SECRET_STORE__TOKEN_FILE` | None | The path of a file with a Vault token that another process, such as Vault Agent, keeps current. |
| `secret_store.kubernetes.role`<br />`CMA_SECRET_STORE__KUBERNETES__ROLE` | None | Required with `kubernetes`. The Vault role that the server logs in as. Bind it to the server’s service account. |
| `secret_store.kubernetes.mount_path`<br />`CMA_SECRET_STORE__KUBERNETES__MOUNT_PATH` | `kubernetes` | Where Vault mounts the Kubernetes login method. |
| `secret_store.kubernetes.service_account_token_file`<br />`CMA_SECRET_STORE__KUBERNETES__SERVICE_ACCOUNT_TOKEN_FILE` | `/var/run/secrets/kubernetes.io/serviceaccount/token` | The path of the service account token that the server presents at each login. |
| `secret_store.approle.role_id`<br />`CMA_SECRET_STORE__APPROLE__ROLE_ID` | None | Required with `approle`. The ID of the AppRole role that the server logs in as. |
| `secret_store.approle.secret_id_file`<br />`CMA_SECRET_STORE__APPROLE__SECRET_ID_FILE` | None | Required with `approle`. The path of a file with the role’s `secret_id`. |
| `secret_store.approle.mount_path`<br />`CMA_SECRET_STORE__APPROLE__MOUNT_PATH` | `approle` | Where Vault mounts the AppRole login method. |
## Agent identity
To set up agent tokens, see [Agent identity](https://platform.claude.com/docs/en/managed-agents/self-hosted/agent-identity#agent-identity). Any setting in this table turns the feature on. The server then needs `agent_identity.issuer` and exactly one place for the signing key: `key_file`, `key_secret`, or `kms_key`.
| Setting<br />Environment variable | Default | Description |
| ----------------------------------------------------------------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent_identity.issuer`<br />`CMA_AGENT_IDENTITY__ISSUER` | None | The `https://` URL that agent tokens carry as their `iss` claim. |
| `agent_identity.key_file`<br />`CMA_AGENT_IDENTITY__KEY_FILE` | None | The path of the PEM private key that signs the tokens. |
| `agent_identity.key_secret`<br />`CMA_AGENT_IDENTITY__KEY_SECRET` | None | The name of the secret that holds the PEM private key in your secret manager, without `secret_store.prefix`. |
| `agent_identity.kms_key.provider`<br />`CMA_AGENT_IDENTITY__KMS_KEY__PROVIDER` | None | The key management service that holds the signing key, `aws_kms` or `gcp_kms`. |
| `agent_identity.kms_key.key`<br />`CMA_AGENT_IDENTITY__KMS_KEY__KEY` | None | Required with `kms_key.provider`. The key’s ARN for `aws_kms`, or the resource name of one key version for `gcp_kms`. |
| `agent_identity.published_key_files`<br />`CMA_AGENT_IDENTITY__PUBLISHED_KEY_FILES` | None | The paths of extra PEM public keys for the key set. The server publishes these keys but never signs with them. Use this setting when you rotate the signing key. |
| `agent_identity.token_lifetime`<br />`CMA_AGENT_IDENTITY__TOKEN_LIFETIME` | `5m` | The time from a token’s `iat` claim to its `exp` claim. A token already sent stays valid until its `exp`. The minimum is `limits.mcp_call_timeout` plus `1m`, and the maximum is `15m`. |
| `agent_identity.jwks_uri`<br />`CMA_AGENT_IDENTITY__JWKS_URI` | `<issuer>/.well-known/jwks.json` | The URL that the issuer’s discovery document gives for the key set. Set it only if you host the key set somewhere other than under the issuer URL. |
| `agent_identity.direct.audiences`<br />File only | None | The receivers that can get a token. Each entry has an `audience` URL and `urls`, the URL prefixes of that receiver’s MCP servers. |
| `agent_identity.actor.enabled`<br />`CMA_AGENT_IDENTITY__ACTOR__ENABLED` | `true` | Whether the server adds the `actor_sub` and `actor_iss` claims to the token of a tool call. `actor_sub` is the subject of the caller that created the session. `actor_iss` is the `issuer_url` of the `auth.issuers` entry that the caller signed in through. Neither claim means that the caller approved the call. |
## Egress gateway
To set up the gateway, see [Environment variable credentials](https://platform.claude.com/docs/en/managed-agents/self-hosted/agent-identity#environment-variable-credentials). Set the other settings in this table only with `egress.gateway_enabled: true`. Without it, the server doesn’t start if any of them is set.
| Setting<br />Environment variable | Default | Description |
| ----------------------------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `egress.gateway_enabled`<br />`CMA_EGRESS__GATEWAY_ENABLED` | `false` | Whether the server works with the egress gateway and accepts `environment_variable` vault credentials. |
| `egress.allowed_hostnames`<br />`CMA_EGRESS__ALLOWED_HOSTNAMES` | None | The exact public hostnames that sandboxes can reach through the gateway. An entry with no port, such as `api.example.com`, allows port 443 for `https` URLs and port 80 for `http` URLs. An entry with a port, such as `api.example.com:8443`, allows that port alone. |
| `egress.swap_header_names`<br />`CMA_EGRESS__SWAP_HEADER_NAMES` | `Authorization` | The request headers in which the gateway can put a credential’s value. A list of your own replaces the default, so include `Authorization` in it. |
| `egress.gateway_listen`<br />`CMA_EGRESS__GATEWAY_LISTEN` | `:8410` | The address of the server’s second listener, which serves only the gateway. The default listens on every interface. |
| `egress.gateway_key_file`<br />`CMA_EGRESS__GATEWAY_KEY_FILE` | None | Required. The path of a file with the key that the gateway presents to the server. |
| `egress.ca_cert_file`<br />`CMA_EGRESS__CA_CERT_FILE` | None | Required. The path of the PEM certificate of the gateway’s certificate authority. |
| `egress.gateway_proxy_address`<br />`CMA_EGRESS__GATEWAY_PROXY_ADDRESS` | None | Required. The `host:port` at which sandboxes reach the gateway’s proxy port. |
## MCP servers
See [MCP servers need an allowlist entry](https://platform.claude.com/docs/en/managed-agents/self-hosted/differences#mcp-servers-need-an-allowlist-entry).
| Setting<br />Environment variable | Default | Description |
| --------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------- |
| `mcp.allowed_hostnames`<br />`CMA_MCP__ALLOWED_HOSTNAMES` | None | The exact hostnames of the MCP servers that the server can connect to. Without it, the server connects to none. |
| `mcp.private_hostnames`<br />File only | None | The hostnames from `mcp.allowed_hostnames` that can resolve to a private address. |
| `mcp.max_result_bytes`<br />`CMA_MCP__MAX_RESULT_BYTES` | `102400` (100 KiB) | The most bytes of one MCP tool result that the model sees. The minimum is `1024`. |
## Git repositories
See [Git repositories need an allowlist entry](https://platform.claude.com/docs/en/managed-agents/self-hosted/differences#git-repositories-need-an-allowlist-entry).
| Setting<br />Environment variable | Default | Description |
| --------------------------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `git.allowed_hostnames`<br />`CMA_GIT__ALLOWED_HOSTNAMES` | None | The Git hosts that a session’s repositories can be on. Hostnames match exactly, with no wildcards, and an entry doesn’t cover its subdomains. An entry allows port 443, or the one port that it names, as in `git.example.com:8443`. Without this setting, the server accepts no repositories. |
| `git.private_hostnames`<br />File only | None | The hostnames from `git.allowed_hostnames` that resolve to a private address, written without a port. For any other hostname, the server connects only to its public addresses. |
| `git.allowed_push_refs`<br />`CMA_GIT__ALLOWED_PUSH_REFS` | None | The branches that agents can push to, each under `refs/heads/`. An entry that ends in `/` allows every branch under it. Any other entry allows that one branch. Without this setting, agents can’t push. |
| `git.commit_author_name`<br />`CMA_GIT__COMMIT_AUTHOR_NAME` | `Claude` | The author name on the agent’s commits. Set it together with `git.commit_author_email`. |
| `git.commit_author_email`<br />`CMA_GIT__COMMIT_AUTHOR_EMAIL` | `[email protected]` | The author email address on the agent’s commits. Set it together with `git.commit_author_name`. |
| `git.max_concurrent_transfers`<br />`CMA_GIT__MAX_CONCURRENT_TRANSFERS` | `32` | The most Git requests that one server carries at once. The minimum is `1`. |
| `git.max_session_transfer_bytes`<br />`CMA_GIT__MAX_SESSION_TRANSFER_BYTES` | `8589934592` (8 GiB) | The most Git traffic, in bytes, that one server carries for one session, uploads and downloads together. The count restarts at zero each time a sandbox picks up the session. At the limit, the server refuses the session’s next Git requests with a `403`. `0` means no limit. Otherwise, the minimum is `1048576`. |
| `git.max_push_bytes`<br />`CMA_GIT__MAX_PUSH_BYTES` | `2147483648` (2 GiB) | The most bytes that one push can send. The minimum is `1048576`. |
These limits apply to Git repositories:
* **Protocols:** The server doesn’t support SSH or Git LFS, and it refuses redirects, such as the one for a renamed repository.
* **Tokens:** The Git host must accept the token as the password of HTTP Basic authentication, under the username `x-access-token`.
* **URLs:** A repository URL has one owner and one repository name, so you can’t use a repository in a GitLab subgroup.
* **Hosts:** For a URL on a host that `git.allowed_hostnames` doesn’t list, the server returns a `400`. The error message says that the URL must be on `github.com`, even if you list other hosts.
* **Pushes:** The server always refuses a push that deletes a branch, or that changes anything other than a branch, such as a tag.
## Web tools and skills
See [Web tools need a server setting](https://platform.claude.com/docs/en/managed-agents/self-hosted/differences#web-tools-need-a-server-setting).
| Setting<br />Environment variable | Default | Description |
| ----------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `web_tools.enabled`<br />`CMA_WEB_TOOLS__ENABLED` | `false` | Whether agents can use the `web_search` and `web_fetch` tools. If you set another `web_tools` setting, the default is `true`. |
| `web_tools.allowed_domains`<br />`CMA_WEB_TOOLS__ALLOWED_DOMAINS` | None | The only domains that agents can read through the web tools. An entry covers its subdomains. |
| `web_tools.blocked_domains`<br />`CMA_WEB_TOOLS__BLOCKED_DOMAINS` | None | Domains that no agent can read through the web tools. Set this or `web_tools.allowed_domains`, not both. |
| `web_tools.max_content_tokens`<br />`CMA_WEB_TOOLS__MAX_CONTENT_TOKENS` | None | The most tokens of one fetched page that `web_fetch` returns to the model. |
| `skills.max_name_chars`<br />`CMA_SKILLS__MAX_NAME_CHARS` | `64` | The longest `name` that a `SKILL.md` file can have. The maximum is `255`. |
| `skills.max_description_chars`<br />`CMA_SKILLS__MAX_DESCRIPTION_CHARS` | `1024` | The longest `description` that a `SKILL.md` file can have. |
## Limits, timeouts, and scheduling
| Setting<br />Environment variable | Default | Description |
| ------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `limits.max_active_sessions`<br />`CMA_LIMITS__MAX_ACTIVE_SESSIONS` | `64` | `store.backend: memory` only. The most sessions that run a turn at once. `0` means no limit. |
| `limits.max_live_subagent_threads`<br />`CMA_LIMITS__MAX_LIVE_SUBAGENT_THREADS` | `25` | The most subagent threads that one session can hold at once. A thread counts until it’s archived or terminated, so an idle thread counts. At the limit, the agent can’t start another subagent. The minimum is `1`, and the maximum is `4000`. |
| `scheduler.max_concurrent_turns`<br />`CMA_SCHEDULER__MAX_CONCURRENT_TURNS` | `64` | `store.backend: postgres` only. The most turns that one server runs at once. The minimum is `1`. The server keeps extra slots for subagent turns alone. Their number is a quarter of this value, and at least `4`. With the default, one server can run 64 turns plus 16 subagent turns. |
| `scheduler.claim_poll_interval`<br />`CMA_SCHEDULER__CLAIM_POLL_INTERVAL` | `1s` | `store.backend: postgres` only. How often a server with a free turn slot looks in the database for waiting work. The minimum is `50ms`. |
| `scheduler.sandbox_claim`<br />`CMA_SCHEDULER__SANDBOX_CLAIM` | `immediate` | When a worker can start a session’s sandbox. `immediate` means as soon as the session is created, so the first tool call waits least. `tool_call` means at the session’s first tool call that needs the sandbox, so a session that makes none uses no sandbox. |
| `limits.model_call_timeout`<br />`CMA_LIMITS__MODEL_CALL_TIMEOUT` | `20m` | How long one model call can run, retries included, before the server cancels it. |
| `limits.stream_idle_timeout`<br />`CMA_LIMITS__STREAM_IDLE_TIMEOUT` | `5m` | How long a model call’s response can deliver nothing before the server gives up that attempt. |
| `limits.mcp_call_timeout`<br />`CMA_LIMITS__MCP_CALL_TIMEOUT` | `4m` | How long one MCP tool call can run before the server gives it up. |
## Models and compaction
| Setting<br />Environment variable | Default | Description |
| ------------------------------------ | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `models.settings`<br />File only | None | Changes to the server’s built-in model catalog, keyed by model ID. See [Model entries](https://platform.claude.com/docs/en/managed-agents/self-hosted/configuration-reference#model-entries). |
| `compaction.triggers`<br />File only | About 90% of each model’s context window | The context size, in tokens, at which a turn on a model compacts its history, keyed by model ID. The minimum is `50000`. Each model must support compaction. |
### Model entries
Each entry of `models.settings` changes a model in the catalog or adds one. For a model in the catalog, a field that you leave out keeps its built-in value.
| Field | Description |
Cut at 300 lines. The page has the rest.
No line in this hunk matches that.