---
title: Referência de configuração
url: https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/configuration-reference
description: Veja onde ficam as configurações de um servidor Claude Managed Agents auto-hospedado e consulte a chave, a variável de ambiente, o padrão e a finalidade de cada configuração.
---
Para solicitar acesso ao Claude Managed Agents auto-hospedado, entre em contato com a equipe da sua conta na Anthropic.
Esta página mostra onde ficam as configurações de um servidor Claude Managed Agents auto-hospedado e as lista. Para configurar um recurso, consulte [Single sign-on](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/configure), [Identidade e credenciais do agente](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/agent-identity) e [Provedor de inferência](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/inference-provider).
## Onde ficam as configurações
O servidor lê suas configurações de um arquivo YAML e suas credenciais do seu ambiente.
* **Docker Compose:** O arquivo é o `compose.config.yaml`, ao lado do `docker-compose.yml` no arquivo compactado extraído. Edite-o e depois execute `docker compose restart cma-server` a partir desse diretório.
* **Kubernetes:** O arquivo é o valor `server.config` do Helm chart do servidor. Edite-o no seu arquivo de values, execute `helm upgrade` e, em seguida, reinicie os servidores com `kubectl -n cma-server rollout restart deployment -l anthropic.com/role=server`. Consulte [Implantar no Kubernetes](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/kubernetes).
Se o servidor rejeitar uma configuração que as páginas de auto-hospedagem mostram, [atualize o servidor](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/upgrade). O `cma-server.example.yaml`, no nível superior do arquivo compactado, anota as chaves comuns.
As credenciais nunca ficam no arquivo. O servidor as lê de variáveis de ambiente ou da identidade que a sua nuvem associa ao host.
### Passar uma credencial para a stack do Compose
Na stack do Compose, o contêiner do servidor recebe somente as variáveis da lista `environment:` do serviço `cma-server` no `docker-compose.yml`. Para passar outra:
1. Adicione o nome dela a essa lista e defina o valor dela no `.env`.
2. Se a credencial for um arquivo, coloque o arquivo ao lado do `docker-compose.yml` e adicione uma linha como `- ./gcp-key.json:/etc/cma-server/gcp-key.json:ro` à lista `x-server-mounts` no `docker-compose.yml`. O caminho após os primeiros dois-pontos é o caminho do arquivo dentro do contêiner. Use esse caminho como o valor da variável no `.env`, ou como o valor da configuração que nomeia o arquivo.
3. Execute `docker compose up -d`. Uma reinicialização não relê o `.env`.
Uma atualização substitui o `docker-compose.yml`, então repita essas edições no arquivo da nova versão antes de iniciar a stack dela.
## Como ler as tabelas
Cada configuração tem uma chave no [arquivo de configurações](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/configuration-reference#where-settings-go), e a maioria das configurações também tem uma variável de ambiente. Uma variável substitui o arquivo, e o arquivo substitui o padrão. O servidor não inicia se o arquivo de configurações tiver uma chave desconhecida, e o erro informa onde a chave está.
* **Chaves:** Cada ponto em uma chave é um nível de aninhamento no arquivo. Por exemplo, `server.addr` é a chave `addr` na seção `server`.
* **Variáveis:** O nome de uma variável é `CMA_` seguido da chave em maiúsculas, com dois sublinhados no lugar de cada ponto.
* **Somente arquivo:** A configuração não tem variável.
* **Somente ambiente:** O servidor não inicia se a configuração estiver no arquivo.
* **Somente `bedrock` e rótulos semelhantes:** A configuração funciona somente com esse provedor, armazenamento ou gerenciador de segredos. Se você a definir enquanto usa um diferente, o servidor não inicia.
* **Listas:** Uma lista é uma lista YAML no arquivo e uma string separada por vírgulas em uma variável.
* **Durações:** Uma duração é um número com uma unidade, como `30s`, `5m` ou `1h`.
* **Inteiros:** Um inteiro é composto apenas de dígitos, sem sinal, zero à esquerda ou sublinhado.
Na inicialização, o servidor registra no log as configurações que você definiu e a maioria dos padrões, cada uma com a origem do seu valor, como `server.addr=0.0.0.0:8400 (file)`. Ele registra `***` no lugar de um segredo, exceto uma chave de API do servidor que ele mesmo gerou.
## Servidor e logging
| Configuração
Variável de ambiente | Padrão | Descrição |
| --------------------------------------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `server.addr`
`CMA_SERVER__ADDR` | `127.0.0.1:8400` | O endereço em que o servidor escuta. |
| `server.api_key`
`CMA_SERVER__API_KEY` | Nenhum | A [chave de API do servidor](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted#the-three-credentials). Obrigatória com `store.backend: postgres`, a menos que `auth.refuse_server_api_key` seja `true`. Com `memory`, o servidor gera uma chave se você não definir nenhuma e a registra no log na inicialização. |
| `server.id_marker`
`CMA_SERVER__ID_MARKER` | `local` | O que vem após o prefixo em cada ID que o servidor cria. `local` gera `sesn_local_01…`, e `none` gera `sesn_01…`, como no serviço hospedado. |
| `server.shutdown_delay`
`CMA_SERVER__SHUTDOWN_DELAY` | `0s` | Por quanto tempo o servidor continua atendendo após um sinal de parada, enquanto sua “readiness probe” (sonda de prontidão) responde `not_ready`. O máximo é `5m`. |
| `server.max_connections`
`CMA_SERVER__MAX_CONNECTIONS` | `0` | O máximo de conexões que o servidor mantém abertas ao mesmo tempo em `server.addr`. `0` significa sem limite. No limite, uma nova conexão aguarda até que outra seja fechada ou até que seu cliente desista. Streams de eventos, polls de workers e sondas de integridade, todos contam. No Kubernetes, o kubelet reinicia um pod cujas sondas esperam tempo demais. |
| `logging.format`
`CMA_LOGGING__FORMAT` | `text` | O formato do log, `text` ou `json`. |
| `logging.level`
`CMA_LOGGING__LEVEL` | `info` | O nível mais baixo que o servidor registra no log. Os valores são `debug`, `info`, `warn` e `error`. |
| `logging.errors`
`CMA_LOGGING__ERRORS` | `false` | Se o log inclui as mensagens de erro das respostas `4xx` e `5xx`. Uma mensagem pode citar um valor que o cliente enviou. |
| `health.check_interval`
`CMA_HEALTH__CHECK_INTERVAL` | `60s` | Com que frequência o servidor verifica sua credencial de inferência para a sonda de prontidão. O mínimo é `5s`. |
| `health.upstream_affects_readiness`
`CMA_HEALTH__UPSTREAM_AFFECTS_READINESS` | `true` | Se a sonda de prontidão responde `503` enquanto o provedor de inferência rejeita a credencial do servidor. |
## Banco de dados
Todas as configurações desta tabela, exceto `store.backend`, se aplicam somente com `store.backend: postgres`.
| Configuração
Variável de ambiente | Padrão | Descrição |
| ------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `store.backend`
`CMA_STORE__BACKEND` | `memory` | Onde o servidor mantém seus dados. Os valores são `memory`, que uma reinicialização apaga, e `postgres`. |
| `store.database_url`
`CMA_STORE__DATABASE_URL` | Nenhum | A string de conexão do PostgreSQL. Obrigatória com `postgres`. |
| `store.control_database_url`
`CMA_STORE__CONTROL_DATABASE_URL` | O valor de `store.database_url` | A string de conexão para as conexões de manutenção do próprio servidor, como seu heartbeat. |
| `store.listen_database_url`
`CMA_STORE__LISTEN_DATABASE_URL` | O valor de `store.database_url` | A string de conexão para a única conexão em que o servidor escuta notificações. Um “connection pooler” (agrupador de conexões) em modo de transação não pode transportar essa conexão. |
| `store.migrate_database_url`
`CMA_STORE__MIGRATE_DATABASE_URL` | O valor de `store.database_url` | A string de conexão que o comando `migrate` do servidor usa. Um connection pooler em modo de transação não pode transportar essa conexão. |
| `store.pool_max_conns`
`CMA_STORE__POOL_MAX_CONNS` | `24` | O máximo de conexões de banco de dados que o pool de um servidor abre. O mínimo é `4`. |
| `store.event_poll_interval`
`CMA_STORE__EVENT_POLL_INTERVAL` | `25ms` | Com que frequência cada servidor pede ao banco de dados os eventos mais recentes nas sessões que seus clientes estão transmitindo por streaming. Um evento que outro servidor registrou espera no máximo aproximadamente esse tempo para chegar ao stream. |
| `store.credentials_encryption_key`
`CMA_STORE__CREDENTIALS_ENCRYPTION_KEY`
Somente ambiente | Nenhum | A chave que criptografa as credenciais armazenadas no banco de dados, como 32 bytes aleatórios em base64. As instalações Docker Compose e Kubernetes a definem. O servidor não inicia sem ela, a menos que `store.allow_unencrypted_credentials` seja `true`. |
| `store.allow_unencrypted_credentials`
`CMA_STORE__ALLOW_UNENCRYPTED_CREDENTIALS` | `false` | Se o servidor pode iniciar sem `store.credentials_encryption_key`. Sem a chave, ele armazena as credenciais no banco de dados em texto simples. `true` não tem efeito se `git.allowed_hostnames` listar um host, ou se você instalar com o Docker Compose ou com o Helm chart do servidor. |
| `store.credentials_encryption_keys_retiring`
`CMA_STORE__CREDENTIALS_ENCRYPTION_KEYS_RETIRING`
Somente ambiente | Nenhum | Chaves de criptografia anteriores com as quais o servidor ainda pode descriptografar durante uma rotação de chaves. Esta configuração precisa de `store.credentials_encryption_key`. |
## Provedor de inferência
Para configurar um provedor, consulte [Provedor de inferência](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/inference-provider).
| Configuração
Variável de ambiente | Padrão | Descrição |
| -------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inference.provider`
`CMA_INFERENCE__PROVIDER` | `anthropic` | Para onde o servidor envia as chamadas de modelo. Os valores são `anthropic`, `bedrock`, `vertex`, `foundry` e `gateway`. |
| `inference.headers`
Somente arquivo | Nenhum | Cabeçalhos de requisição que o servidor adiciona a cada chamada de modelo, como um mapa de nome de cabeçalho para valor. Coloque cada valor entre aspas. O servidor se recusa a iniciar com um valor sem aspas que o YAML não lê como texto, como `true` ou `0042`. Com `gateway`, um valor também pode ser `{ from: request_id }` ou `{ from: session_id }`. |
| `inference.model_fallback`
`CMA_INFERENCE__MODEL_FALLBACK` | `true` | Somente `anthropic`. Se as chamadas de modelo solicitam [fallback no lado do servidor](https://platform.claude.com/docs/pt-BR/build-with-claude/refusals-and-fallback#server-side-fallback). Essas chamadas carregam um campo `fallbacks` e o cabeçalho `anthropic-beta: server-side-fallback-2026-07-01`. Um proxy que você nomeia em `ANTHROPIC_BASE_URL` pode rejeitar o campo ou o cabeçalho. Se ele responder com um `400` ou um `422`, o servidor envia a chamada novamente sem eles. |
| `inference.metadata.user_id`
`CMA_INFERENCE__METADATA__USER_ID` | Nenhum | Somente `anthropic` e `foundry`, ou `gateway` com `format: anthropic-messages`. Um identificador que o servidor envia como `metadata.user_id` com cada chamada de modelo. O log de inicialização o exibe. Sem esta configuração, o servidor envia o rótulo `cma-server`. Você não pode desativar `metadata.user_id`. Se o provedor ou um proxy o rejeitar, todas as chamadas de modelo falham. Consulte [O que sai da sua rede](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-data-and-access#what-leaves-your-network). |
### Provedores de nuvem
| Configuração
Variável de ambiente | Padrão | Descrição |
| -------------------------------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inference.region`
`CMA_INFERENCE__REGION` | Nenhum | Somente `bedrock` e `vertex`. A região da AWS, ou a localização no Google Cloud’s Agent Platform. Obrigatória com `vertex`. Sem ela, `bedrock` usa a região que a cadeia padrão do AWS SDK encontra. |
| `inference.project_id`
`CMA_INFERENCE__PROJECT_ID` | Nenhum | Somente `vertex`. O projeto do Google Cloud em que as chamadas são feitas. Obrigatório, a menos que a credencial do Google nomeie um projeto. |
| `inference.api`
`CMA_INFERENCE__API` | `invoke_model` | Somente `bedrock`. A API do Amazon Bedrock que transporta as chamadas, `invoke_model` ou `messages`. `messages` é o endpoint que [Claude no Amazon Bedrock (`bedrock-mantle`)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-amazon-bedrock) descreve. Com ele, a função AWS do servidor precisa de `bedrock-mantle:CreateInference` no lugar de `bedrock:InvokeModel` e `bedrock:InvokeModelWithResponseStream`. |
| `inference.list_models`
`CMA_INFERENCE__LIST_MODELS` | `true` | Somente `bedrock`. Se o servidor lê as listas de modelos Claude do Amazon Bedrock. Com essas listas, os agentes podem usar um modelo lançado depois da versão do seu servidor. |
| `inference.model_id_prefix`
`CMA_INFERENCE__MODEL_ID_PREFIX` | `us.anthropic.` | Somente `bedrock`. O texto que o servidor coloca antes de cada ID de modelo. Com `inference.api: messages`, o padrão é `anthropic.`. |
| `inference.model_id_overrides`
Somente arquivo | Nenhum | Somente `bedrock`, `vertex` e `foundry`. Um mapa de ID de modelo para o ID exato que o provedor espera. Com `foundry`, esse ID é um nome de implantação. |
| `inference.foundry.resource`
`CMA_INFERENCE__FOUNDRY__RESOURCE` | Nenhum | Somente `foundry`. O nome do recurso Foundry. Defina este ou `inference.foundry.base_url`, não ambos. |
| `inference.foundry.base_url`
`CMA_INFERENCE__FOUNDRY__BASE_URL` | Nenhum | Somente `foundry`. Por padrão, as chamadas vão para `https://.services.ai.azure.com/anthropic`. Para acessar o recurso em outro endereço, como um proxy, defina essa URL aqui. Ela termina em `/anthropic`. |
### Gateway de modelo
Estas configurações se aplicam somente com `inference.provider: gateway`. Consulte [Gateway de modelo](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/inference-provider#model-gateway).
| Configuração
Variável de ambiente | Padrão | Descrição |
| ----------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `inference.gateway.url`
`CMA_INFERENCE__GATEWAY__URL` | Nenhum | Obrigatória. A URL que recebe as chamadas de modelo. Com `bedrock-invoke` e `vertex-raw-predict`, `{model}` marca onde fica o ID do modelo. Com `vertex-raw-predict`, a URL deve terminar em `/{model}:rawPredict`. |
| `inference.gateway.format`
`CMA_INFERENCE__GATEWAY__FORMAT` | Nenhum | Obrigatória. O formato de requisição que o gateway aceita: `bedrock-invoke`, `anthropic-messages` ou `vertex-raw-predict`. |
| `inference.gateway.model_map`
Somente arquivo | Nenhum | Obrigatória. Um mapa de cada ID de modelo que os agentes podem nomear para o ID que o gateway espera. Coloque cada valor entre aspas, como em `inference.headers`. |
| `inference.gateway.streaming`
`CMA_INFERENCE__GATEWAY__STREAMING` | `false` | Se o servidor envia a chamada com streaming do formato, para que as respostas cheguem à medida que o modelo as produz. Com `bedrock-invoke`, essa chamada vai para a mesma URL com `-with-response-stream` acrescentado. Com `vertex-raw-predict`, essa chamada vai para a mesma URL com `:streamRawPredict` no lugar de `:rawPredict`. Mantenha `:rawPredict` em `inference.gateway.url`. |
| `inference.credentials.supplier`
`CMA_INFERENCE__CREDENTIALS__SUPPLIER` | Nenhum | Obrigatória. De onde vem a credencial do gateway. `env` significa uma chave de longa duração, `oauth_exchange` significa tokens de curta duração, e `azure` significa tokens do Microsoft Entra ID emitidos para a própria identidade Azure do servidor. |
| `inference.credentials.env.var`
`CMA_INFERENCE__CREDENTIALS__ENV__VAR` | Nenhum | Obrigatória com `env`. O nome da variável de ambiente que contém a chave. |
| `inference.credentials.azure.scope`
`CMA_INFERENCE__CREDENTIALS__AZURE__SCOPE` | Nenhum | Obrigatória com `azure`. O escopo para o qual o servidor solicita tokens: o URI de ID da aplicação ou o ID da aplicação do registro de aplicação do seu gateway, seguido de `/.default`. |
| `inference.credentials.send_as.header`
`CMA_INFERENCE__CREDENTIALS__SEND_AS__HEADER` | `Authorization` | O cabeçalho de requisição que transporta a credencial. |
| `inference.credentials.send_as.scheme`
`CMA_INFERENCE__CREDENTIALS__SEND_AS__SCHEME` | `Bearer` | A palavra que precede a credencial no cabeçalho. Em qualquer cabeçalho diferente de `Authorization`, o padrão é nenhum esquema. |
| `inference.credentials.renew_before`
`CMA_INFERENCE__CREDENTIALS__RENEW_BEFORE` | `90s` | Com `oauth_exchange`, com que antecedência o servidor substitui um token. Ele para de usar um token em cache esse tempo antes de o token expirar e obtém outro para a próxima chamada de modelo. Mantenha o valor abaixo do tempo de vida dos seus tokens. O servidor recusa qualquer token que seja válido por menos do que esse valor. |
### Tokens de gateway de curta duração
Estas configurações se aplicam somente com `inference.credentials.supplier: oauth_exchange`. Consulte [Tokens de curta duração](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/inference-provider#short-lived-tokens). As configurações de `exchange` são opcionais como grupo. Sem elas, o servidor envia ao gateway o que o callback retorna.
| Configuração
Variável de ambiente | Padrão | Descrição |
| ----------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `inference.credentials.assertion.url`
`CMA_INFERENCE__CREDENTIALS__ASSERTION__URL` | Nenhum | Obrigatória. A URL do callback HTTP que retorna uma asserção assinada. |
| `inference.credentials.assertion.auth.type`
`CMA_INFERENCE__CREDENTIALS__ASSERTION__AUTH__TYPE` | Nenhum | Obrigatória. Como o servidor se autentica no callback, `mtls` ou `bearer_file`. |
| `inference.credentials.assertion.auth.cert_file`
`CMA_INFERENCE__CREDENTIALS__ASSERTION__AUTH__CERT_FILE` | Nenhum | Obrigatória com `mtls`. O caminho do certificado de cliente do servidor. |
| `inference.credentials.assertion.auth.key_file`
`CMA_INFERENCE__CREDENTIALS__ASSERTION__AUTH__KEY_FILE` | Nenhum | Obrigatória com `mtls`. O caminho da chave privada do certificado de cliente. |
| `inference.credentials.assertion.auth.token_file`
`CMA_INFERENCE__CREDENTIALS__ASSERTION__AUTH__TOKEN_FILE` | Nenhum | Obrigatória com `bearer_file`. O caminho de um arquivo que contém o bearer token. |
| `inference.credentials.assertion.auth.ca_file`
`CMA_INFERENCE__CREDENTIALS__ASSERTION__AUTH__CA_FILE` | Nenhum | O caminho de um arquivo PEM com as autoridades certificadoras em que o servidor confia para o callback. |
| `inference.credentials.assertion.forward_metadata`
`CMA_INFERENCE__CREDENTIALS__ASSERTION__FORWARD_METADATA` | Nenhum | As chaves de metadados da sessão cujos valores o servidor envia ao callback. Elas chegam como `session.metadata` no corpo da requisição. Os valores são o que quer que o chamador da API tenha escrito, então verifique-os em relação aos seus próprios registros. |
| `inference.credentials.exchange.token_url`
`CMA_INFERENCE__CREDENTIALS__EXCHANGE__TOKEN_URL` | Nenhum | Obrigatória para uma troca. O endpoint de token OAuth em que o servidor troca a asserção por um token. |
| `inference.credentials.exchange.grant_type`
`CMA_INFERENCE__CREDENTIALS__EXCHANGE__GRANT_TYPE` | Nenhum | Obrigatória para uma troca. O `grant_type` que o servidor envia, como `urn:ietf:params:oauth:grant-type:jwt-bearer`. |
| `inference.credentials.exchange.encoding`
`CMA_INFERENCE__CREDENTIALS__EXCHANGE__ENCODING` | `form` | Como o servidor codifica a requisição de troca, `form` ou `multipart`. |
| `inference.credentials.exchange.expiry`
`CMA_INFERENCE__CREDENTIALS__EXCHANGE__EXPIRY` | `expires_in` | Onde o servidor lê o tempo de vida do token. `expires_in` significa o mais cedo entre o `expires_in` da resposta e a claim `exp` do token. `jwt_exp` significa apenas a claim `exp`. |
| `inference.credentials.exchange.headers`
Somente arquivo | Nenhum | Cabeçalhos de requisição extras para o endpoint de token, como um mapa de nome de cabeçalho para valor. Coloque cada valor entre aspas, como em `inference.headers`. |
| `inference.credentials.exchange.ca_file`
`CMA_INFERENCE__CREDENTIALS__EXCHANGE__CA_FILE` | Nenhum | O caminho de um arquivo PEM com as autoridades certificadoras em que o servidor confia para o endpoint de token. |
## Single sign-on
Para configurar o login, consulte [Single sign-on](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/configure).
| Configuração
Variável de ambiente | Padrão | Descrição |
| ------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auth.issuers`
Somente arquivo | Nenhum | Os emissores OpenID Connect cujos tokens o servidor aceita. Consulte [Entradas de emissor](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/configuration-reference#issuer-entries). |
| `auth.refuse_server_api_key`
Somente arquivo | `false` | Se o servidor recusa a chave de API do servidor em todas as rotas. `true` precisa de pelo menos um emissor. Todo comando da CLI de administração que recebe a chave passa então a falhar. |
### Entradas de emissor
Cada entrada de `auth.issuers` recebe estes campos:
| Campo | Padrão | Descrição |
| ----------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | Nenhum | Obrigatório. Um rótulo para o emissor nas linhas de log. O servidor também o registra como parte do criador de cada recurso. |
| `issuer_url` | Nenhum | Obrigatório. A URL do emissor, exatamente como na claim `iss` de seus tokens. O servidor busca as chaves de assinatura deste host e do host `jwks_uri` que o documento de descoberta do emissor nomeia. Se sua rede limita conexões de saída, permita ambos os hosts. |
| `audiences` | Nenhum | Obrigatório. Os valores que a claim `aud` de um token pode conter. Se as aplicações encaminham tokens que já possuem, liste o ID de cliente de cada aplicação. |
| `roles` | Nenhum | Uma lista de pares `group` e `role`. Um grupo corresponde exatamente, ou como um padrão em que `*` representa qualquer sequência de caracteres e `?` um caractere. Uma função é `admin`, `developer` ou `user`. A função correspondente mais alta prevalece. Defina `roles`, `default_role` ou ambos. |
| `default_role` | Nenhum | A função de um chamador cujos grupos não correspondem a nenhuma entrada de `roles`. Defina-a somente se todos que podem obter um token para esta audiência devem ter acesso. |
| `subject_claim` | `sub` | A claim que identifica o chamador. Um nome que começa com `/` é um JSON Pointer para claims aninhadas. |
| `stable_subject` | `false` | Aplica-se somente se `subject_claim` nomear uma claim diferente de `sub` ou `oid`. Defina `true` para confirmar que seu provedor nunca altera o valor dessa claim de uma pessoa e nunca o atribui a outra pessoa. O servidor não verifica isso. Com `false`, os [tokens de agente](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/configuration-reference#agent-identity) omitem as claims `actor_sub` e `actor_iss`. |
| `groups_claim` | `groups` | A claim que lista os grupos do chamador. Um nome que começa com `/` é um JSON Pointer para claims aninhadas. |
| `jwks_file` | Nenhum | O caminho de um arquivo JSON Web Key Set. O servidor lê as chaves de assinatura dele e nunca entra em contato com o emissor. |
| `login_client_id` | Nenhum | O ID de cliente da aplicação que o [login pelo terminal](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/configure#let-developers-log-in-from-a-terminal) usa. Apenas um emissor pode defini-lo. |
| `login_scopes` | `[openid]` | Os escopos que o login solicita. Este campo precisa de `login_client_id`. |
## Gerenciador de segredos
Para configurar um armazenamento, consulte [Gerenciador de segredos](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/agent-identity#secret-manager).
| Configuração
Variável de ambiente | Padrão | Descrição |
| ----------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `secret_store.type`
`CMA_SECRET_STORE__TYPE` | Nenhum | O gerenciador de segredos que mantém as credenciais de vault. Os valores são `aws_secrets_manager`, `gcp_secret_manager`, `azure_key_vault` e `hashicorp_vault`. Sem ele, as credenciais de vault permanecem no banco de dados. |
| `secret_store.prefix`
`CMA_SECRET_STORE__PREFIX` | Nenhum | Obrigatória com `secret_store.type`. O início do nome de cada segredo que o servidor cria. Ele deve terminar com `/` para `aws_secrets_manager` e `hashicorp_vault`, com `-` ou `_` para `gcp_secret_manager`, e com `-` para `azure_key_vault`. |
| `secret_store.region`
`CMA_SECRET_STORE__REGION` | Nenhum | Somente `aws_secrets_manager`, e obrigatória nesse caso. A região da AWS que mantém os segredos. |
| `secret_store.project`
`CMA_SECRET_STORE__PROJECT` | Nenhum | Somente `gcp_secret_manager`, e obrigatória nesse caso. O ID do projeto do Google Cloud que mantém os segredos. |
| `secret_store.vault_url`
`CMA_SECRET_STORE__VAULT_URL` | Nenhum | Somente `azure_key_vault`, e obrigatória nesse caso. A URL do key vault, como `https://my-vault.vault.azure.net`. |
### HashiCorp Vault
Estas configurações se aplicam somente com `secret_store.type: hashicorp_vault`. Defina exatamente um método de login: `token_file`, `kubernetes` ou `approle`.
| Configuração
Variável de ambiente | Padrão | Descrição |
| -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `secret_store.address`
`CMA_SECRET_STORE__ADDRESS` | Nenhum | Obrigatória. A URL `https://` do servidor Vault. |
| `secret_store.namespace`
`CMA_SECRET_STORE__NAMESPACE` | Nenhum | O namespace do Vault Enterprise que contém o mount e o método de login. |
| `secret_store.mount`
`CMA_SECRET_STORE__MOUNT` | `secret` | O caminho do secrets engine KV versão 2. |
| `secret_store.ca_cert_file`
`CMA_SECRET_STORE__CA_CERT_FILE` | Nenhum | O caminho de um arquivo PEM com a autoridade certificadora que assinou o certificado do Vault. |
| `secret_store.token_file`
`CMA_SECRET_STORE__TOKEN_FILE` | Nenhum | O caminho de um arquivo com um token do Vault que outro processo, como o Vault Agent, mantém atualizado. |
| `secret_store.kubernetes.role`
`CMA_SECRET_STORE__KUBERNETES__ROLE` | Nenhum | Obrigatória com `kubernetes`. A função do Vault com a qual o servidor faz login. Vincule-a à conta de serviço do servidor. |
| `secret_store.kubernetes.mount_path`
`CMA_SECRET_STORE__KUBERNETES__MOUNT_PATH` | `kubernetes` | Onde o Vault monta o método de login do Kubernetes. |
| `secret_store.kubernetes.service_account_token_file`
`CMA_SECRET_STORE__KUBERNETES__SERVICE_ACCOUNT_TOKEN_FILE` | `/var/run/secrets/kubernetes.io/serviceaccount/token` | O caminho do token da conta de serviço que o servidor apresenta a cada login. |
| `secret_store.approle.role_id`
`CMA_SECRET_STORE__APPROLE__ROLE_ID` | Nenhum | Obrigatória com `approle`. O ID da função AppRole com a qual o servidor faz login. |
| `secret_store.approle.secret_id_file`
`CMA_SECRET_STORE__APPROLE__SECRET_ID_FILE` | Nenhum | Obrigatória com `approle`. O caminho de um arquivo com o `secret_id` da função. |
| `secret_store.approle.mount_path`
`CMA_SECRET_STORE__APPROLE__MOUNT_PATH` | `approle` | Onde o Vault monta o método de login AppRole. |
## Identidade do agente
Para configurar tokens de agente, consulte [Identidade do agente](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/agent-identity#agent-identity). Qualquer configuração desta tabela ativa o recurso. O servidor então precisa de `agent_identity.issuer` e de exatamente um local para a chave de assinatura: `key_file`, `key_secret` ou `kms_key`.
| Configuração
Variável de ambiente | Padrão | Descrição |
| ----------------------------------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `agent_identity.issuer`
`CMA_AGENT_IDENTITY__ISSUER` | Nenhum | A URL `https://` que os tokens de agente carregam como sua claim `iss`. |
| `agent_identity.key_file`
`CMA_AGENT_IDENTITY__KEY_FILE` | Nenhum | O caminho da chave privada PEM que assina os tokens. |
| `agent_identity.key_secret`
`CMA_AGENT_IDENTITY__KEY_SECRET` | Nenhum | O nome do segredo que contém a chave privada PEM no seu gerenciador de segredos, sem `secret_store.prefix`. |
| `agent_identity.kms_key.provider`
`CMA_AGENT_IDENTITY__KMS_KEY__PROVIDER` | Nenhum | O serviço de gerenciamento de chaves que mantém a chave de assinatura, `aws_kms` ou `gcp_kms`. |
| `agent_identity.kms_key.key`
`CMA_AGENT_IDENTITY__KMS_KEY__KEY` | Nenhum | Obrigatória com `kms_key.provider`. O ARN da chave para `aws_kms`, ou o nome de recurso de uma versão da chave para `gcp_kms`. |
| `agent_identity.published_key_files`
`CMA_AGENT_IDENTITY__PUBLISHED_KEY_FILES` | Nenhum | Os caminhos de chaves públicas PEM extras para o conjunto de chaves. O servidor publica essas chaves, mas nunca assina com elas. Use esta configuração quando você fizer a rotação da chave de assinatura. |
| `agent_identity.token_lifetime`
`CMA_AGENT_IDENTITY__TOKEN_LIFETIME` | `5m` | O tempo entre a claim `iat` de um token e sua claim `exp`. Um token já enviado permanece válido até seu `exp`. O mínimo é `limits.mcp_call_timeout` mais `1m`, e o máximo é `15m`. |
| `agent_identity.jwks_uri`
`CMA_AGENT_IDENTITY__JWKS_URI` | `/.well-known/jwks.json` | A URL que o documento de descoberta do emissor informa para o conjunto de chaves. Defina-a somente se você hospedar o conjunto de chaves em outro lugar que não sob a URL do emissor. |
| `agent_identity.direct.audiences`
Somente arquivo | Nenhum | Os receptores que podem obter um token. Cada entrada tem uma URL `audience` e `urls`, os prefixos de URL dos servidores MCP desse receptor. |
| `agent_identity.actor.enabled`
`CMA_AGENT_IDENTITY__ACTOR__ENABLED` | `true` | Se o servidor adiciona as claims `actor_sub` e `actor_iss` ao token de uma chamada de ferramenta. `actor_sub` é o subject do chamador que criou a sessão. `actor_iss` é o `issuer_url` da entrada de `auth.issuers` pela qual o chamador fez login. Nenhuma das claims significa que o chamador aprovou a chamada. |
## Gateway de egress
Para configurar o gateway, consulte [Credenciais de variável de ambiente](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/agent-identity#environment-variable-credentials). Defina as outras configurações desta tabela somente com `egress.gateway_enabled: true`. Sem isso, o servidor não inicia se qualquer uma delas estiver definida.
| Configuração
Variável de ambiente | Padrão | Descrição |
| ----------------------------------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `egress.gateway_enabled`
`CMA_EGRESS__GATEWAY_ENABLED` | `false` | Se o servidor trabalha com o gateway de egress e aceita credenciais de vault `environment_variable`. |
| `egress.allowed_hostnames`
`CMA_EGRESS__ALLOWED_HOSTNAMES` | Nenhum | Os nomes de host públicos exatos que os sandboxes podem alcançar por meio do gateway. Uma entrada sem porta, como `api.example.com`, permite a porta 443 para URLs `https` e a porta 80 para URLs `http`. Uma entrada com porta, como `api.example.com:8443`, permite somente essa porta. |
| `egress.swap_header_names`
`CMA_EGRESS__SWAP_HEADER_NAMES` | `Authorization` | Os cabeçalhos de requisição nos quais o gateway pode colocar o valor de uma credencial. Uma lista própria substitui o padrão, então inclua `Authorization` nela. |
| `egress.gateway_listen`
`CMA_EGRESS__GATEWAY_LISTEN` | `:8410` | O endereço do segundo listener do servidor, que atende somente o gateway. O padrão escuta em todas as interfaces. |
| `egress.gateway_key_file`
`CMA_EGRESS__GATEWAY_KEY_FILE` | Nenhum | Obrigatória. O caminho de um arquivo com a chave que o gateway apresenta ao servidor. |
| `egress.ca_cert_file`
`CMA_EGRESS__CA_CERT_FILE` | Nenhum | Obrigatória. O caminho do certificado PEM da autoridade certificadora do gateway. |
| `egress.gateway_proxy_address`
`CMA_EGRESS__GATEWAY_PROXY_ADDRESS` | Nenhum | Obrigatória. O `host:port` no qual os sandboxes alcançam a porta de proxy do gateway. |
## Servidores MCP
Consulte [Servidores MCP precisam de uma entrada na allowlist](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/differences#mcp-servers-need-an-allowlist-entry).
| Configuração
Variável de ambiente | Padrão | Descrição |
| --------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `mcp.allowed_hostnames`
`CMA_MCP__ALLOWED_HOSTNAMES` | Nenhum | Os nomes de host exatos dos servidores MCP aos quais o servidor pode se conectar. Sem ela, o servidor não se conecta a nenhum. |
| `mcp.private_hostnames`
Somente arquivo | Nenhum | Os nomes de host de `mcp.allowed_hostnames` que podem ser resolvidos para um endereço privado. |
| `mcp.max_result_bytes`
`CMA_MCP__MAX_RESULT_BYTES` | `102400` (100 KiB) | O máximo de bytes de um resultado de ferramenta MCP que o modelo vê. O mínimo é `1024`. |
## Repositórios Git
Consulte [Repositórios Git precisam de uma entrada na allowlist](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/differences#git-repositories-need-an-allowlist-entry).
| Configuração
Variável de ambiente | Padrão | Descrição |
| --------------------------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `git.allowed_hostnames`
`CMA_GIT__ALLOWED_HOSTNAMES` | Nenhum | Os hosts Git em que os repositórios de uma sessão podem estar. Os nomes de host correspondem exatamente, sem curingas, e uma entrada não abrange seus subdomínios. Uma entrada permite a porta 443, ou a única porta que ela nomeia, como em `git.example.com:8443`. Sem esta configuração, o servidor não aceita repositórios. |
| `git.private_hostnames`
Somente arquivo | Nenhum | Os nomes de host de `git.allowed_hostnames` que são resolvidos para um endereço privado, escritos sem porta. Para qualquer outro nome de host, o servidor se conecta somente aos seus endereços públicos. |
| `git.allowed_push_refs`
`CMA_GIT__ALLOWED_PUSH_REFS` | Nenhum | Os branches para os quais os agentes podem fazer push, cada um sob `refs/heads/`. Uma entrada que termina em `/` permite todos os branches abaixo dela. Qualquer outra entrada permite aquele único branch. Sem esta configuração, os agentes não podem fazer push. |
| `git.commit_author_name`
`CMA_GIT__COMMIT_AUTHOR_NAME` | `Claude` | O nome do autor nos commits do agente. Defina-o junto com `git.commit_author_email`. |
| `git.commit_author_email`
`CMA_GIT__COMMIT_AUTHOR_EMAIL` | `noreply@anthropic.com` | O endereço de e-mail do autor nos commits do agente. Defina-o junto com `git.commit_author_name`. |
| `git.max_concurrent_transfers`
`CMA_GIT__MAX_CONCURRENT_TRANSFERS` | `32` | O máximo de requisições Git que um servidor transporta ao mesmo tempo. O mínimo é `1`. |
| `git.max_session_transfer_bytes`
`CMA_GIT__MAX_SESSION_TRANSFER_BYTES` | `8589934592` (8 GiB) | O máximo de tráfego Git, em bytes, que um servidor transporta para uma sessão, somando uploads e downloads. A contagem recomeça do zero cada vez que um sandbox assume a sessão. No limite, o servidor recusa as próximas requisições Git da sessão com um `403`. `0` significa sem limite. Caso contrário, o mínimo é `1048576`. |
| `git.max_push_bytes`
`CMA_GIT__MAX_PUSH_BYTES` | `2147483648` (2 GiB) | O máximo de bytes que um push pode enviar. O mínimo é `1048576`. |
Estes limites se aplicam a repositórios Git:
* **Protocolos:** O servidor não oferece suporte a SSH nem a Git LFS, e recusa redirecionamentos, como o de um repositório renomeado.
* **Tokens:** O host Git deve aceitar o token como a senha da autenticação HTTP Basic, sob o nome de usuário `x-access-token`.
* **URLs:** Uma URL de repositório tem um proprietário e um nome de repositório, então você não pode usar um repositório em um subgrupo do GitLab.
* **Hosts:** Para uma URL em um host que `git.allowed_hostnames` não lista, o servidor retorna um `400`. A mensagem de erro diz que a URL deve estar em `github.com`, mesmo que você liste outros hosts.
* **Pushes:** O servidor sempre recusa um push que exclui um branch, ou que altera algo diferente de um branch, como uma tag.
## Ferramentas web e skills
Consulte [Ferramentas web precisam de uma configuração do servidor](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/differences#web-tools-need-a-server-setting).
| Configuração
Variável de ambiente | Padrão | Descrição |
| ----------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `web_tools.enabled`
`CMA_WEB_TOOLS__ENABLED` | `false` | Se os agentes podem usar as ferramentas `web_search` e `web_fetch`. Se você definir outra configuração de `web_tools`, o padrão é `true`. |
| `web_tools.allowed_domains`
`CMA_WEB_TOOLS__ALLOWED_DOMAINS` | Nenhum | Os únicos domínios que os agentes podem ler por meio das ferramentas web. Uma entrada abrange seus subdomínios. |
| `web_tools.blocked_domains`
`CMA_WEB_TOOLS__BLOCKED_DOMAINS` | Nenhum | Domínios que nenhum agente pode ler por meio das ferramentas web. Defina este ou `web_tools.allowed_domains`, não ambos. |
| `web_tools.max_content_tokens`
`CMA_WEB_TOOLS__MAX_CONTENT_TOKENS` | Nenhum | O máximo de tokens de uma página buscada que `web_fetch` retorna ao modelo. |
| `skills.max_name_chars`
`CMA_SKILLS__MAX_NAME_CHARS` | `64` | O `name` mais longo que um arquivo `SKILL.md` pode ter. O máximo é `255`. |
| `skills.max_description_chars`
`CMA_SKILLS__MAX_DESCRIPTION_CHARS` | `1024` | A `description` mais longa que um arquivo `SKILL.md` pode ter. |
## Limites, timeouts e agendamento
| Configuração
Variável de ambiente | Padrão | Descrição |
| ------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `limits.max_active_sessions`
`CMA_LIMITS__MAX_ACTIVE_SESSIONS` | `64` | Somente `store.backend: memory`. O máximo de sessões que executam um turno ao mesmo tempo. `0` significa sem limite. |
| `limits.max_live_subagent_threads`
`CMA_LIMITS__MAX_LIVE_SUBAGENT_THREADS` | `25` | O máximo de threads de subagente que uma sessão pode manter ao mesmo tempo. Uma thread conta até ser arquivada ou encerrada, então uma thread ociosa conta. No limite, o agente não pode iniciar outro subagente. O mínimo é `1`, e o máximo é `4000`. |
| `scheduler.max_concurrent_turns`
`CMA_SCHEDULER__MAX_CONCURRENT_TURNS` | `64` | Somente `store.backend: postgres`. O máximo de turnos que um servidor executa ao mesmo tempo. O mínimo é `1`. O servidor reserva slots extras apenas para turnos de subagentes. O número deles é um quarto desse valor, e no mínimo `4`. Com o padrão, um servidor pode executar 64 turnos mais 16 turnos de subagentes. |
| `scheduler.claim_poll_interval`
`CMA_SCHEDULER__CLAIM_POLL_INTERVAL` | `1s` | Somente `store.backend: postgres`. Com que frequência um servidor com um slot de turno livre procura trabalho em espera no banco de dados. O mínimo é `50ms`. |
| `scheduler.sandbox_claim`
`CMA_SCHEDULER__SANDBOX_CLAIM` | `immediate` | Quando um worker pode iniciar o sandbox de uma sessão. `immediate` significa assim que a sessão é criada, de modo que a primeira chamada de ferramenta espera menos. `tool_call` significa na primeira chamada de ferramenta da sessão que precisa do sandbox, de modo que uma sessão que não faz nenhuma não usa sandbox. |
| `limits.model_call_timeout`
`CMA_LIMITS__MODEL_CALL_TIMEOUT` | `20m` | Por quanto tempo uma chamada de modelo pode ser executada, incluindo novas tentativas, antes que o servidor a cancele. |
| `limits.stream_idle_timeout`
`CMA_LIMITS__STREAM_IDLE_TIMEOUT` | `5m` | Por quanto tempo a resposta de uma chamada de modelo pode ficar sem entregar nada antes que o servidor desista dessa tentativa. |
| `limits.mcp_call_timeout`
`CMA_LIMITS__MCP_CALL_TIMEOUT` | `4m` | Por quanto tempo uma chamada de ferramenta MCP pode ser executada antes que o servidor desista dela. |
## Modelos e compactação
| Configuração
Variável de ambiente | Padrão | Descrição |
| ------------------------------------------ | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `models.settings`
Somente arquivo | Nenhum | Alterações no catálogo de modelos integrado do servidor, indexadas por ID de modelo. Consulte [Entradas de modelo](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/configuration-reference#model-entries). |
| `compaction.triggers`
Somente arquivo | Cerca de 90% da “context window” (janela de contexto) de cada modelo | O tamanho do contexto, em tokens, no qual um turno em um modelo compacta seu histórico, indexado por ID de modelo. O mínimo é `50000`. Cada modelo deve oferecer suporte à compactação. |
### Entradas de modelo
Cada entrada de `models.settings` altera um modelo do catálogo ou adiciona um. Para um modelo do catálogo, um campo que você omitir mantém seu valor integrado.
| Campo | Descrição |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `fast_supported` | Se o modelo aceita `speed: "fast"`. Obrigatório para um modelo que você adiciona. |
| `inference_geo_supported` | Se o modelo aceita `inference_geo`. |
| `forced_tool_choice_supported` | Se o modelo aceita uma requisição que o força a chamar uma ferramenta. O servidor envia tal requisição somente para executar uma chamada `web_search` ou `web_fetch` que foi aprovada. Com `false`, ele nunca força uma ferramenta neste modelo. |
| `effort_supported` | Se o modelo aceita um nível de esforço. |
| `effort_levels` | Os níveis de esforço que o modelo aceita, dentre `low`, `medium`, `high`, `xhigh` e `max`. Obrigatório com `effort_supported: true` em um modelo sem níveis integrados. |
| `effort_default` | O nível de esforço de uma sessão cujo agente não nomeia nenhum. Deve ser um dos `effort_levels`. Obrigatório com `effort_supported: true` em um modelo sem padrão integrado. |
| `thinking` | O modo de pensamento que o servidor solicita, `enabled` ou `adaptive`. |
| `thinking_budget` | O orçamento de pensamento, em tokens, que o servidor envia com `thinking: enabled`. |
| `max_tokens` | O valor de `max_tokens` de cada chamada de modelo. |
## Console no seu servidor
| Configuração
Variável de ambiente | Padrão | Descrição |
| ----------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------- |
| `console.serve`
`CMA_CONSOLE__SERVE` | `true` | Se deve servir a [console no seu servidor](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/console). |