---
title: Riferimento alla configurazione
url: https://platform.claude.com/docs/it/managed-agents/self-hosted/configuration-reference
description: Scopri dove vanno le impostazioni di un server Claude Managed Agents self-hosted e consulta la chiave, la variabile d'ambiente, il valore predefinito e lo scopo di ciascuna impostazione.
---
Per richiedere l’accesso a Claude Managed Agents self-hosted, contatta il tuo team di riferimento Anthropic.
Questa pagina mostra dove vanno le impostazioni di un server Claude Managed Agents self-hosted e le elenca. Per configurare una funzionalità, consulta [Single sign-on](https://platform.claude.com/docs/it/managed-agents/self-hosted/configure), [Identità e credenziali dell’agente](https://platform.claude.com/docs/it/managed-agents/self-hosted/agent-identity) e [Provider di inferenza](https://platform.claude.com/docs/it/managed-agents/self-hosted/inference-provider).
## Dove vanno le impostazioni
Il server legge le sue impostazioni da un unico file YAML e le sue credenziali dal suo ambiente.
* **Docker Compose:** Il file è `compose.config.yaml`, accanto a `docker-compose.yml` nell’archivio estratto. Modificalo, quindi esegui `docker compose restart cma-server` da quella directory.
* **Kubernetes:** Il file è il valore `server.config` del chart Helm del server. Modificalo nel tuo file dei valori, esegui `helm upgrade` e poi riavvia i server con `kubectl -n cma-server rollout restart deployment -l anthropic.com/role=server`. Consulta [Distribuire su Kubernetes](https://platform.claude.com/docs/it/managed-agents/self-hosted/kubernetes).
Se il server rifiuta un’impostazione mostrata nelle pagine self-hosted, [aggiorna il server](https://platform.claude.com/docs/it/managed-agents/self-hosted/upgrade). `cma-server.example.yaml`, al livello principale dell’archivio, annota le chiavi comuni.
Le credenziali non vanno mai nel file. Il server le legge dalle variabili d’ambiente, oppure dall’identità che il tuo cloud associa all’host.
### Passare una credenziale allo stack Compose
Nello stack Compose, il container del server riceve solo le variabili presenti nell’elenco `environment:` del servizio `cma-server` in `docker-compose.yml`. Per passarne un’altra:
1. Aggiungi il suo nome a quell’elenco e imposta il suo valore in `.env`.
2. Se la credenziale è un file, metti il file accanto a `docker-compose.yml` e aggiungi una riga come `- ./gcp-key.json:/etc/cma-server/gcp-key.json:ro` all’elenco `x-server-mounts` in `docker-compose.yml`. Il percorso dopo i primi due punti è il percorso del file all’interno del container. Usa quel percorso come valore della variabile in `.env`, oppure come valore dell’impostazione che indica il file.
3. Esegui `docker compose up -d`. Un riavvio non rilegge `.env`.
Un aggiornamento sostituisce `docker-compose.yml`, quindi ripeti queste modifiche nel file della nuova release prima di avviarne lo stack.
## Come leggere le tabelle
Ogni impostazione ha una chiave nel [file delle impostazioni](https://platform.claude.com/docs/it/managed-agents/self-hosted/configuration-reference#where-settings-go) e la maggior parte delle impostazioni ha anche una variabile d’ambiente. Una variabile ha la precedenza sul file e il file ha la precedenza sul valore predefinito. Il server non si avvia se il suo file delle impostazioni contiene una chiave sconosciuta e l’errore indica dove si trova la chiave.
* **Chiavi:** Ogni punto in una chiave corrisponde a un livello di annidamento nel file. Ad esempio, `server.addr` è la chiave `addr` nella sezione `server`.
* **Variabili:** Il nome di una variabile è `CMA_` seguito dalla chiave in maiuscolo, con due trattini bassi al posto di ogni punto.
* **Solo file:** L’impostazione non ha una variabile.
* **Solo ambiente:** Il server non si avvia se l’impostazione è nel file.
* **Solo `bedrock` ed etichette simili:** L’impostazione funziona solo con quel provider, store o secret manager. Se la imposti mentre ne usi uno diverso, il server non si avvia.
* **Liste:** Una lista è una lista YAML nel file e una stringa separata da virgole in una variabile.
* **Durate:** Una durata è un numero con un’unità, come `30s`, `5m` o `1h`.
* **Interi:** Un intero è composto da sole cifre, senza segno, zeri iniziali o trattini bassi.
All’avvio, il server registra nel log le impostazioni che hai impostato e la maggior parte dei valori predefiniti, ciascuna con la provenienza del suo valore, ad esempio `server.addr=0.0.0.0:8400 (file)`. Registra `***` al posto di un segreto, tranne per una chiave API del server che ha generato da solo.
## Server e logging
| Impostazione
Variabile d’ambiente | Predefinito | Descrizione |
| --------------------------------------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `server.addr`
`CMA_SERVER__ADDR` | `127.0.0.1:8400` | L’indirizzo su cui il server è in ascolto. |
| `server.api_key`
`CMA_SERVER__API_KEY` | Nessuno | La [chiave API del server](https://platform.claude.com/docs/it/managed-agents/self-hosted#the-three-credentials). Obbligatoria con `store.backend: postgres`, a meno che `auth.refuse_server_api_key` non sia `true`. Con `memory`, il server genera una chiave se non ne imposti nessuna e la registra nel log all’avvio. |
| `server.id_marker`
`CMA_SERVER__ID_MARKER` | `local` | Ciò che segue il prefisso in ogni ID creato dal server. `local` produce `sesn_local_01…` e `none` produce `sesn_01…`, come nel servizio ospitato. |
| `server.shutdown_delay`
`CMA_SERVER__SHUTDOWN_DELAY` | `0s` | Per quanto tempo il server continua a servire dopo un segnale di arresto, mentre la sua sonda di readiness risponde `not_ready`. Il massimo è `5m`. |
| `server.max_connections`
`CMA_SERVER__MAX_CONNECTIONS` | `0` | Il numero massimo di connessioni che il server mantiene aperte contemporaneamente su `server.addr`. `0` indica nessun limite. Al raggiungimento del limite, una nuova connessione attende finché un’altra non si chiude o il suo client non rinuncia. Gli stream di eventi, i polling dei worker e le sonde di health vengono tutti conteggiati. Su Kubernetes, il kubelet riavvia un pod le cui sonde attendono troppo a lungo. |
| `logging.format`
`CMA_LOGGING__FORMAT` | `text` | Il formato del log, `text` o `json`. |
| `logging.level`
`CMA_LOGGING__LEVEL` | `info` | Il livello più basso che il server registra nel log. I valori sono `debug`, `info`, `warn` ed `error`. |
| `logging.errors`
`CMA_LOGGING__ERRORS` | `false` | Se il log include i messaggi di errore delle risposte `4xx` e `5xx`. Un messaggio può citare un valore inviato dal client. |
| `health.check_interval`
`CMA_HEALTH__CHECK_INTERVAL` | `60s` | Ogni quanto il server verifica la propria credenziale di inferenza per la sonda di readiness. Il minimo è `5s`. |
| `health.upstream_affects_readiness`
`CMA_HEALTH__UPSTREAM_AFFECTS_READINESS` | `true` | Se la sonda di readiness risponde `503` mentre il provider di inferenza rifiuta la credenziale del server. |
## Database
Ogni impostazione in questa tabella, tranne `store.backend`, si applica solo con `store.backend: postgres`.
| Impostazione
Variabile d’ambiente | Predefinito | Descrizione |
| ---------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `store.backend`
`CMA_STORE__BACKEND` | `memory` | Dove il server conserva i propri dati. I valori sono `memory`, che un riavvio cancella, e `postgres`. |
| `store.database_url`
`CMA_STORE__DATABASE_URL` | Nessuno | La stringa di connessione PostgreSQL. Obbligatoria con `postgres`. |
| `store.control_database_url`
`CMA_STORE__CONTROL_DATABASE_URL` | Il valore di `store.database_url` | La stringa di connessione per le connessioni di manutenzione del server stesso, come il suo heartbeat. |
| `store.listen_database_url`
`CMA_STORE__LISTEN_DATABASE_URL` | Il valore di `store.database_url` | La stringa di connessione per l’unica connessione su cui il server è in ascolto per le notifiche. Un connection pooler in modalità transazione non può gestire quella connessione. |
| `store.migrate_database_url`
`CMA_STORE__MIGRATE_DATABASE_URL` | Il valore di `store.database_url` | La stringa di connessione usata dal comando `migrate` del server. Un connection pooler in modalità transazione non può gestire quella connessione. |
| `store.pool_max_conns`
`CMA_STORE__POOL_MAX_CONNS` | `24` | Il numero massimo di connessioni al database che il pool di un server apre. Il minimo è `4`. |
| `store.event_poll_interval`
`CMA_STORE__EVENT_POLL_INTERVAL` | `25ms` | Ogni quanto ciascun server chiede al database gli eventi più recenti nelle sessioni che i suoi client stanno trasmettendo in streaming. Un evento registrato da un altro server attende al massimo circa questo tempo prima di raggiungere lo stream. |
| `store.credentials_encryption_key`
`CMA_STORE__CREDENTIALS_ENCRYPTION_KEY`
Solo ambiente | Nessuno | La chiave che cifra le credenziali memorizzate nel database, come 32 byte casuali in base64. Le installazioni Docker Compose e Kubernetes la impostano. Il server non si avvia senza di essa, a meno che `store.allow_unencrypted_credentials` non sia `true`. |
| `store.allow_unencrypted_credentials`
`CMA_STORE__ALLOW_UNENCRYPTED_CREDENTIALS` | `false` | Se il server può avviarsi senza `store.credentials_encryption_key`. Senza la chiave, memorizza le credenziali nel database in chiaro. `true` non ha effetto se `git.allowed_hostnames` elenca un host, oppure se installi con Docker Compose o con il chart Helm del server. |
| `store.credentials_encryption_keys_retiring`
`CMA_STORE__CREDENTIALS_ENCRYPTION_KEYS_RETIRING`
Solo ambiente | Nessuno | Chiavi di cifratura precedenti con cui il server può ancora decifrare durante una rotazione delle chiavi. Questa impostazione richiede `store.credentials_encryption_key`. |
## Provider di inferenza
Per configurare un provider, consulta [Provider di inferenza](https://platform.claude.com/docs/it/managed-agents/self-hosted/inference-provider).
| Impostazione
Variabile d’ambiente | Predefinito | Descrizione |
| -------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inference.provider`
`CMA_INFERENCE__PROVIDER` | `anthropic` | Dove il server invia le chiamate al modello. I valori sono `anthropic`, `bedrock`, `vertex`, `foundry` e `gateway`. |
| `inference.headers`
Solo file | Nessuno | Header di richiesta che il server aggiunge a ogni chiamata al modello, come mappa dal nome dell’header al valore. Racchiudi tra virgolette ogni valore. Il server si rifiuta di avviarsi con un valore senza virgolette che YAML non legge come testo, ad esempio `true` o `0042`. Con `gateway`, un valore può anche essere `{ from: request_id }` o `{ from: session_id }`. |
| `inference.model_fallback`
`CMA_INFERENCE__MODEL_FALLBACK` | `true` | Solo `anthropic`. Se le chiamate al modello richiedono il [fallback lato server](https://platform.claude.com/docs/it/build-with-claude/refusals-and-fallback#server-side-fallback). Quelle chiamate includono un campo `fallbacks` e l’header `anthropic-beta: server-side-fallback-2026-07-01`. Un proxy che indichi in `ANTHROPIC_BASE_URL` potrebbe rifiutare il campo o l’header. Se risponde con un `400` o un `422`, il server invia di nuovo la chiamata senza di essi. |
| `inference.metadata.user_id`
`CMA_INFERENCE__METADATA__USER_ID` | Nessuno | Solo `anthropic` e `foundry`, oppure `gateway` con `format: anthropic-messages`. Un identificatore che il server invia come `metadata.user_id` con ogni chiamata al modello. Il log di avvio lo stampa. Senza questa impostazione, il server invia l’etichetta `cma-server`. Non puoi disattivare `metadata.user_id`. Se il provider o un proxy lo rifiuta, ogni chiamata al modello fallisce. Consulta [Cosa esce dalla tua rete](https://platform.claude.com/docs/it/managed-agents/self-hosted-data-and-access#what-leaves-your-network). |
### Provider cloud
| Impostazione
Variabile d’ambiente | Predefinito | Descrizione |
| -------------------------------------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inference.region`
`CMA_INFERENCE__REGION` | Nessuno | Solo `bedrock` e `vertex`. La Region AWS, oppure la località in Google Cloud’s Agent Platform. Obbligatoria con `vertex`. Senza di essa, `bedrock` usa la Region trovata dalla catena predefinita dell’SDK AWS. |
| `inference.project_id`
`CMA_INFERENCE__PROJECT_ID` | Nessuno | Solo `vertex`. Il progetto Google Cloud in cui vengono effettuate le chiamate. Obbligatorio a meno che la credenziale Google non indichi un progetto. |
| `inference.api`
`CMA_INFERENCE__API` | `invoke_model` | Solo `bedrock`. L’API di Amazon Bedrock che gestisce le chiamate, `invoke_model` o `messages`. `messages` è l’endpoint descritto in [Claude in Amazon Bedrock (`bedrock-mantle`)](https://platform.claude.com/docs/it/build-with-claude/claude-in-amazon-bedrock). Con esso, il ruolo AWS del server richiede `bedrock-mantle:CreateInference` al posto di `bedrock:InvokeModel` e `bedrock:InvokeModelWithResponseStream`. |
| `inference.list_models`
`CMA_INFERENCE__LIST_MODELS` | `true` | Solo `bedrock`. Se il server legge gli elenchi dei modelli Claude di Amazon Bedrock. Con quegli elenchi, gli agenti possono usare un modello uscito dopo la release del tuo server. |
| `inference.model_id_prefix`
`CMA_INFERENCE__MODEL_ID_PREFIX` | `us.anthropic.` | Solo `bedrock`. Il testo che il server antepone a ogni ID del modello. Con `inference.api: messages`, il valore predefinito è `anthropic.`. |
| `inference.model_id_overrides`
Solo file | Nessuno | Solo `bedrock`, `vertex` e `foundry`. Una mappa dall’ID del modello all’ID esatto che il provider si aspetta. Con `foundry`, quell’ID è il nome di un deployment. |
| `inference.foundry.resource`
`CMA_INFERENCE__FOUNDRY__RESOURCE` | Nessuno | Solo `foundry`. Il nome della risorsa Foundry. Imposta questa oppure `inference.foundry.base_url`, non entrambe. |
| `inference.foundry.base_url`
`CMA_INFERENCE__FOUNDRY__BASE_URL` | Nessuno | Solo `foundry`. Per impostazione predefinita, le chiamate vanno a `https://.services.ai.azure.com/anthropic`. Per raggiungere la risorsa a un altro indirizzo, ad esempio un proxy, imposta qui quell’URL. Termina con `/anthropic`. |
### Gateway del modello
Queste impostazioni si applicano solo con `inference.provider: gateway`. Consulta [Gateway del modello](https://platform.claude.com/docs/it/managed-agents/self-hosted/inference-provider#model-gateway).
| Impostazione
Variabile d’ambiente | Predefinito | Descrizione |
| ----------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `inference.gateway.url`
`CMA_INFERENCE__GATEWAY__URL` | Nessuno | Obbligatorio. L’URL che riceve le chiamate al modello. Con `bedrock-invoke` e `vertex-raw-predict`, `{model}` indica dove va l’ID del modello. Con `vertex-raw-predict`, l’URL deve terminare con `/{model}:rawPredict`. |
| `inference.gateway.format`
`CMA_INFERENCE__GATEWAY__FORMAT` | Nessuno | Obbligatorio. Il formato di richiesta che il gateway accetta: `bedrock-invoke`, `anthropic-messages` o `vertex-raw-predict`. |
| `inference.gateway.model_map`
Solo file | Nessuno | Obbligatorio. Una mappa da ciascun ID del modello che gli agenti possono indicare all’ID che il gateway si aspetta. Racchiudi tra virgolette ogni valore, come per `inference.headers`. |
| `inference.gateway.streaming`
`CMA_INFERENCE__GATEWAY__STREAMING` | `false` | Se il server invia la chiamata in streaming del formato, in modo che le risposte arrivino man mano che il modello le produce. Con `bedrock-invoke`, quella chiamata va allo stesso URL con `-with-response-stream` aggiunto in fondo. Con `vertex-raw-predict`, quella chiamata va allo stesso URL con `:streamRawPredict` al posto di `:rawPredict`. Lascia `:rawPredict` in `inference.gateway.url`. |
| `inference.credentials.supplier`
`CMA_INFERENCE__CREDENTIALS__SUPPLIER` | Nessuno | Obbligatorio. Da dove proviene la credenziale del gateway. `env` indica una chiave di lunga durata, `oauth_exchange` indica token di breve durata e `azure` indica token Microsoft Entra ID emessi per l’identità Azure del server stesso. |
| `inference.credentials.env.var`
`CMA_INFERENCE__CREDENTIALS__ENV__VAR` | Nessuno | Obbligatorio con `env`. Il nome della variabile d’ambiente che contiene la chiave. |
| `inference.credentials.azure.scope`
`CMA_INFERENCE__CREDENTIALS__AZURE__SCOPE` | Nessuno | Obbligatorio con `azure`. Lo scope per cui il server richiede i token: l’URI dell’ID applicazione o l’ID applicazione della registrazione dell’app del tuo gateway, seguito da `/.default`. |
| `inference.credentials.send_as.header`
`CMA_INFERENCE__CREDENTIALS__SEND_AS__HEADER` | `Authorization` | L’header di richiesta che trasporta la credenziale. |
| `inference.credentials.send_as.scheme`
`CMA_INFERENCE__CREDENTIALS__SEND_AS__SCHEME` | `Bearer` | La parola che precede la credenziale nell’header. Con qualsiasi header diverso da `Authorization`, il valore predefinito è nessuno schema. |
| `inference.credentials.renew_before`
`CMA_INFERENCE__CREDENTIALS__RENEW_BEFORE` | `90s` | Con `oauth_exchange`, con quanto anticipo il server sostituisce un token. Smette di usare un token in cache con questo anticipo rispetto alla scadenza del token e ne ottiene un altro per la chiamata al modello successiva. Mantieni il valore al di sotto della durata dei tuoi token. Il server rifiuta qualsiasi token valido per meno di questo valore. |
### Token del gateway di breve durata
Queste impostazioni si applicano solo con `inference.credentials.supplier: oauth_exchange`. Consulta [Token di breve durata](https://platform.claude.com/docs/it/managed-agents/self-hosted/inference-provider#short-lived-tokens). Le impostazioni `exchange` sono facoltative come gruppo. Senza di esse, il server invia al gateway ciò che restituisce il callback.
| Impostazione
Variabile d’ambiente | Predefinito | Descrizione |
| ----------------------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inference.credentials.assertion.url`
`CMA_INFERENCE__CREDENTIALS__ASSERTION__URL` | Nessuno | Obbligatorio. L’URL del callback HTTP che restituisce un’asserzione firmata. |
| `inference.credentials.assertion.auth.type`
`CMA_INFERENCE__CREDENTIALS__ASSERTION__AUTH__TYPE` | Nessuno | Obbligatorio. Come il server si autentica presso il callback, `mtls` o `bearer_file`. |
| `inference.credentials.assertion.auth.cert_file`
`CMA_INFERENCE__CREDENTIALS__ASSERTION__AUTH__CERT_FILE` | Nessuno | Obbligatorio con `mtls`. Il percorso del certificato client del server. |
| `inference.credentials.assertion.auth.key_file`
`CMA_INFERENCE__CREDENTIALS__ASSERTION__AUTH__KEY_FILE` | Nessuno | Obbligatorio con `mtls`. Il percorso della chiave privata del certificato client. |
| `inference.credentials.assertion.auth.token_file`
`CMA_INFERENCE__CREDENTIALS__ASSERTION__AUTH__TOKEN_FILE` | Nessuno | Obbligatorio con `bearer_file`. Il percorso di un file che contiene il bearer token. |
| `inference.credentials.assertion.auth.ca_file`
`CMA_INFERENCE__CREDENTIALS__ASSERTION__AUTH__CA_FILE` | Nessuno | Il percorso di un file PEM con le autorità di certificazione di cui il server si fida per il callback. |
| `inference.credentials.assertion.forward_metadata`
`CMA_INFERENCE__CREDENTIALS__ASSERTION__FORWARD_METADATA` | Nessuno | Le chiavi dei metadati della sessione i cui valori il server invia al callback. Arrivano come `session.metadata` nel corpo della richiesta. I valori sono quelli scritti dal chiamante dell’API, quindi verificali rispetto ai tuoi registri. |
| `inference.credentials.exchange.token_url`
`CMA_INFERENCE__CREDENTIALS__EXCHANGE__TOKEN_URL` | Nessuno | Obbligatorio per uno scambio. L’endpoint del token OAuth in cui il server scambia l’asserzione con un token. |
| `inference.credentials.exchange.grant_type`
`CMA_INFERENCE__CREDENTIALS__EXCHANGE__GRANT_TYPE` | Nessuno | Obbligatorio per uno scambio. Il `grant_type` che il server invia, ad esempio `urn:ietf:params:oauth:grant-type:jwt-bearer`. |
| `inference.credentials.exchange.encoding`
`CMA_INFERENCE__CREDENTIALS__EXCHANGE__ENCODING` | `form` | Come il server codifica la richiesta di scambio, `form` o `multipart`. |
| `inference.credentials.exchange.expiry`
`CMA_INFERENCE__CREDENTIALS__EXCHANGE__EXPIRY` | `expires_in` | Dove il server legge la durata del token. `expires_in` indica il minore tra il valore `expires_in` della risposta e la claim `exp` del token. `jwt_exp` indica la sola claim `exp`. |
| `inference.credentials.exchange.headers`
Solo file | Nessuno | Header di richiesta aggiuntivi per l’endpoint del token, come mappa dal nome dell’header al valore. Racchiudi tra virgolette ogni valore, come per `inference.headers`. |
| `inference.credentials.exchange.ca_file`
`CMA_INFERENCE__CREDENTIALS__EXCHANGE__CA_FILE` | Nessuno | Il percorso di un file PEM con le autorità di certificazione di cui il server si fida per l’endpoint del token. |
## Single sign-on
Per configurare l’accesso, consulta [Single sign-on](https://platform.claude.com/docs/it/managed-agents/self-hosted/configure).
| Impostazione
Variabile d’ambiente | Predefinito | Descrizione |
| ------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auth.issuers`
Solo file | Nessuno | Gli issuer OpenID Connect i cui token il server accetta. Consulta [Voci degli issuer](https://platform.claude.com/docs/it/managed-agents/self-hosted/configuration-reference#issuer-entries). |
| `auth.refuse_server_api_key`
Solo file | `false` | Se il server rifiuta la chiave API del server su ogni route. `true` richiede almeno un issuer. Ogni comando della CLI di amministrazione che accetta la chiave fallisce di conseguenza. |
### Voci degli issuer
Ogni voce di `auth.issuers` accetta questi campi:
| Campo | Predefinito | Descrizione |
| ----------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | Nessuno | Obbligatorio. Un’etichetta per l’issuer nelle righe di log. Il server la registra anche come parte del creatore di ogni risorsa. |
| `issuer_url` | Nessuno | Obbligatorio. L’URL dell’issuer, esattamente come nella claim `iss` dei suoi token. Il server recupera le chiavi di firma da questo host e dall’host `jwks_uri` indicato dal documento di discovery dell’issuer. Se la tua rete limita le connessioni in uscita, consenti entrambi gli host. |
| `audiences` | Nessuno | Obbligatorio. I valori che la claim `aud` di un token può contenere. Se le applicazioni inoltrano token che già possiedono, elenca il client ID di ciascuna applicazione. |
| `roles` | Nessuno | Una lista di coppie `group` e `role`. Un gruppo corrisponde esattamente, oppure come pattern in cui `*` sta per qualsiasi sequenza di caratteri e `?` per un carattere. Un ruolo è `admin`, `developer` o `user`. Prevale il ruolo corrispondente più alto. Imposta `roles`, `default_role` o entrambi. |
| `default_role` | Nessuno | Il ruolo di un chiamante i cui gruppi non corrispondono a nessuna voce di `roles`. Impostalo solo se chiunque possa ottenere un token per questa audience deve avere accesso. |
| `subject_claim` | `sub` | La claim che identifica il chiamante. Un nome che inizia con `/` è un JSON Pointer all’interno di claim annidate. |
| `stable_subject` | `false` | Si applica solo se `subject_claim` indica una claim diversa da `sub` o `oid`. Imposta `true` per confermare che il tuo provider non modifica mai il valore di quella claim per una persona e non lo assegna mai a qualcun altro. Il server non lo verifica. Con `false`, i [token dell’agente](https://platform.claude.com/docs/it/managed-agents/self-hosted/configuration-reference#agent-identity) omettono le claim `actor_sub` e `actor_iss`. |
| `groups_claim` | `groups` | La claim che elenca i gruppi del chiamante. Un nome che inizia con `/` è un JSON Pointer all’interno di claim annidate. |
| `jwks_file` | Nessuno | Il percorso di un file JSON Web Key Set. Il server legge le chiavi di firma da esso e non contatta mai l’issuer. |
| `login_client_id` | Nessuno | Il client ID dell’applicazione usata dal [login da terminale](https://platform.claude.com/docs/it/managed-agents/self-hosted/configure#let-developers-log-in-from-a-terminal). Solo un issuer può impostarlo. |
| `login_scopes` | `[openid]` | Gli scope richiesti dal login. Questo campo richiede `login_client_id`. |
## Secret manager
Per configurare uno store, consulta [Secret manager](https://platform.claude.com/docs/it/managed-agents/self-hosted/agent-identity#secret-manager).
| Impostazione
Variabile d’ambiente | Predefinito | Descrizione |
| ----------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `secret_store.type`
`CMA_SECRET_STORE__TYPE` | Nessuno | Il secret manager che contiene le credenziali dei vault. I valori sono `aws_secrets_manager`, `gcp_secret_manager`, `azure_key_vault` e `hashicorp_vault`. Senza di esso, le credenziali dei vault restano nel database. |
| `secret_store.prefix`
`CMA_SECRET_STORE__PREFIX` | Nessuno | Obbligatorio con `secret_store.type`. L’inizio del nome di ogni segreto creato dal server. Deve terminare con `/` per `aws_secrets_manager` e `hashicorp_vault`, con `-` o `_` per `gcp_secret_manager` e con `-` per `azure_key_vault`. |
| `secret_store.region`
`CMA_SECRET_STORE__REGION` | Nessuno | Solo `aws_secrets_manager`, e lì obbligatorio. La Region AWS che contiene i segreti. |
| `secret_store.project`
`CMA_SECRET_STORE__PROJECT` | Nessuno | Solo `gcp_secret_manager`, e lì obbligatorio. L’ID del progetto Google Cloud che contiene i segreti. |
| `secret_store.vault_url`
`CMA_SECRET_STORE__VAULT_URL` | Nessuno | Solo `azure_key_vault`, e lì obbligatorio. L’URL del key vault, ad esempio `https://my-vault.vault.azure.net`. |
### HashiCorp Vault
Queste impostazioni si applicano solo con `secret_store.type: hashicorp_vault`. Imposta esattamente un metodo di login: `token_file`, `kubernetes` o `approle`.
| Impostazione
Variabile d’ambiente | Predefinito | Descrizione |
| -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `secret_store.address`
`CMA_SECRET_STORE__ADDRESS` | Nessuno | Obbligatorio. L’URL `https://` del server Vault. |
| `secret_store.namespace`
`CMA_SECRET_STORE__NAMESPACE` | Nessuno | Il namespace di Vault Enterprise che contiene il mount e il metodo di login. |
| `secret_store.mount`
`CMA_SECRET_STORE__MOUNT` | `secret` | Il percorso del secrets engine KV versione 2. |
| `secret_store.ca_cert_file`
`CMA_SECRET_STORE__CA_CERT_FILE` | Nessuno | Il percorso di un file PEM con l’autorità di certificazione che ha firmato il certificato di Vault. |
| `secret_store.token_file`
`CMA_SECRET_STORE__TOKEN_FILE` | Nessuno | Il percorso di un file con un token Vault che un altro processo, come Vault Agent, mantiene aggiornato. |
| `secret_store.kubernetes.role`
`CMA_SECRET_STORE__KUBERNETES__ROLE` | Nessuno | Obbligatorio con `kubernetes`. Il ruolo Vault con cui il server effettua il login. Associalo al service account del server. |
| `secret_store.kubernetes.mount_path`
`CMA_SECRET_STORE__KUBERNETES__MOUNT_PATH` | `kubernetes` | Dove Vault monta il metodo di login Kubernetes. |
| `secret_store.kubernetes.service_account_token_file`
`CMA_SECRET_STORE__KUBERNETES__SERVICE_ACCOUNT_TOKEN_FILE` | `/var/run/secrets/kubernetes.io/serviceaccount/token` | Il percorso del token del service account che il server presenta a ogni login. |
| `secret_store.approle.role_id`
`CMA_SECRET_STORE__APPROLE__ROLE_ID` | Nessuno | Obbligatorio con `approle`. L’ID del ruolo AppRole con cui il server effettua il login. |
| `secret_store.approle.secret_id_file`
`CMA_SECRET_STORE__APPROLE__SECRET_ID_FILE` | Nessuno | Obbligatorio con `approle`. Il percorso di un file con il `secret_id` del ruolo. |
| `secret_store.approle.mount_path`
`CMA_SECRET_STORE__APPROLE__MOUNT_PATH` | `approle` | Dove Vault monta il metodo di login AppRole. |
## Identità dell’agente
Per configurare i token dell’agente, consulta [Identità dell’agente](https://platform.claude.com/docs/it/managed-agents/self-hosted/agent-identity#agent-identity). Qualsiasi impostazione in questa tabella attiva la funzionalità. Il server richiede quindi `agent_identity.issuer` ed esattamente una posizione per la chiave di firma: `key_file`, `key_secret` o `kms_key`.
| Impostazione
Variabile d’ambiente | Predefinito | Descrizione |
| ----------------------------------------------------------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent_identity.issuer`
`CMA_AGENT_IDENTITY__ISSUER` | Nessuno | L’URL `https://` che i token dell’agente riportano come claim `iss`. |
| `agent_identity.key_file`
`CMA_AGENT_IDENTITY__KEY_FILE` | Nessuno | Il percorso della chiave privata PEM che firma i token. |
| `agent_identity.key_secret`
`CMA_AGENT_IDENTITY__KEY_SECRET` | Nessuno | Il nome del segreto che contiene la chiave privata PEM nel tuo secret manager, senza `secret_store.prefix`. |
| `agent_identity.kms_key.provider`
`CMA_AGENT_IDENTITY__KMS_KEY__PROVIDER` | Nessuno | Il servizio di gestione delle chiavi che contiene la chiave di firma, `aws_kms` o `gcp_kms`. |
| `agent_identity.kms_key.key`
`CMA_AGENT_IDENTITY__KMS_KEY__KEY` | Nessuno | Obbligatorio con `kms_key.provider`. L’ARN della chiave per `aws_kms`, oppure il nome della risorsa di una versione della chiave per `gcp_kms`. |
| `agent_identity.published_key_files`
`CMA_AGENT_IDENTITY__PUBLISHED_KEY_FILES` | Nessuno | I percorsi di chiavi pubbliche PEM aggiuntive per il key set. Il server pubblica queste chiavi ma non firma mai con esse. Usa questa impostazione quando ruoti la chiave di firma. |
| `agent_identity.token_lifetime`
`CMA_AGENT_IDENTITY__TOKEN_LIFETIME` | `5m` | Il tempo tra la claim `iat` di un token e la sua claim `exp`. Un token già inviato resta valido fino al suo `exp`. Il minimo è `limits.mcp_call_timeout` più `1m` e il massimo è `15m`. |
| `agent_identity.jwks_uri`
`CMA_AGENT_IDENTITY__JWKS_URI` | `/.well-known/jwks.json` | L’URL che il documento di discovery dell’issuer indica per il key set. Impostalo solo se ospiti il key set in una posizione diversa dall’URL dell’issuer. |
| `agent_identity.direct.audiences`
Solo file | Nessuno | I destinatari che possono ricevere un token. Ogni voce ha un URL `audience` e `urls`, i prefissi URL dei server MCP di quel destinatario. |
| `agent_identity.actor.enabled`
`CMA_AGENT_IDENTITY__ACTOR__ENABLED` | `true` | Se il server aggiunge le claim `actor_sub` e `actor_iss` al token di una chiamata a uno strumento. `actor_sub` è il subject del chiamante che ha creato la sessione. `actor_iss` è l’`issuer_url` della voce di `auth.issuers` tramite cui il chiamante ha effettuato l’accesso. Nessuna delle due claim significa che il chiamante abbia approvato la chiamata. |
## Gateway di uscita
Per configurare il gateway, consulta [Credenziali tramite variabili d’ambiente](https://platform.claude.com/docs/it/managed-agents/self-hosted/agent-identity#environment-variable-credentials). Imposta le altre impostazioni di questa tabella solo con `egress.gateway_enabled: true`. Senza di essa, il server non si avvia se una qualsiasi di esse è impostata.
| Impostazione
Variabile d’ambiente | Predefinito | Descrizione |
| ----------------------------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `egress.gateway_enabled`
`CMA_EGRESS__GATEWAY_ENABLED` | `false` | Se il server funziona con il gateway di uscita e accetta le credenziali del vault `environment_variable`. |
| `egress.allowed_hostnames`
`CMA_EGRESS__ALLOWED_HOSTNAMES` | Nessuno | Gli hostname pubblici esatti che le sandbox possono raggiungere tramite il gateway. Una voce senza porta, come `api.example.com`, consente la porta 443 per gli URL `https` e la porta 80 per gli URL `http`. Una voce con una porta, come `api.example.com:8443`, consente solo quella porta. |
| `egress.swap_header_names`
`CMA_EGRESS__SWAP_HEADER_NAMES` | `Authorization` | Gli header di richiesta in cui il gateway può inserire il valore di una credenziale. Una tua lista sostituisce il valore predefinito, quindi includi `Authorization` in essa. |
| `egress.gateway_listen`
`CMA_EGRESS__GATEWAY_LISTEN` | `:8410` | L’indirizzo del secondo listener del server, che serve solo il gateway. Il valore predefinito è in ascolto su ogni interfaccia. |
| `egress.gateway_key_file`
`CMA_EGRESS__GATEWAY_KEY_FILE` | Nessuno | Obbligatorio. Il percorso di un file con la chiave che il gateway presenta al server. |
| `egress.ca_cert_file`
`CMA_EGRESS__CA_CERT_FILE` | Nessuno | Obbligatorio. Il percorso del certificato PEM dell’autorità di certificazione del gateway. |
| `egress.gateway_proxy_address`
`CMA_EGRESS__GATEWAY_PROXY_ADDRESS` | Nessuno | Obbligatorio. L’`host:port` a cui le sandbox raggiungono la porta proxy del gateway. |
## Server MCP
Consulta [I server MCP richiedono una voce nella allowlist](https://platform.claude.com/docs/it/managed-agents/self-hosted/differences#mcp-servers-need-an-allowlist-entry).
| Impostazione
Variabile d’ambiente | Predefinito | Descrizione |
| --------------------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `mcp.allowed_hostnames`
`CMA_MCP__ALLOWED_HOSTNAMES` | Nessuno | Gli hostname esatti dei server MCP a cui il server può connettersi. Senza di esso, il server non si connette a nessuno. |
| `mcp.private_hostnames`
Solo file | Nessuno | Gli hostname di `mcp.allowed_hostnames` che possono risolversi in un indirizzo privato. |
| `mcp.max_result_bytes`
`CMA_MCP__MAX_RESULT_BYTES` | `102400` (100 KiB) | Il numero massimo di byte di un risultato di uno strumento MCP che il modello vede. Il minimo è `1024`. |
## Repository Git
Consulta [I repository Git richiedono una voce nella allowlist](https://platform.claude.com/docs/it/managed-agents/self-hosted/differences#git-repositories-need-an-allowlist-entry).
| Impostazione
Variabile d’ambiente | Predefinito | Descrizione |
| --------------------------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `git.allowed_hostnames`
`CMA_GIT__ALLOWED_HOSTNAMES` | Nessuno | Gli host Git su cui possono trovarsi i repository di una sessione. Gli hostname corrispondono esattamente, senza caratteri jolly, e una voce non copre i suoi sottodomini. Una voce consente la porta 443, oppure l’unica porta che indica, come in `git.example.com:8443`. Senza questa impostazione, il server non accetta alcun repository. |
| `git.private_hostnames`
Solo file | Nessuno | Gli hostname di `git.allowed_hostnames` che si risolvono in un indirizzo privato, scritti senza porta. Per qualsiasi altro hostname, il server si connette solo ai suoi indirizzi pubblici. |
| `git.allowed_push_refs`
`CMA_GIT__ALLOWED_PUSH_REFS` | Nessuno | I branch su cui gli agenti possono eseguire il push, ciascuno sotto `refs/heads/`. Una voce che termina con `/` consente ogni branch al suo interno. Qualsiasi altra voce consente quel singolo branch. Senza questa impostazione, gli agenti non possono eseguire il push. |
| `git.commit_author_name`
`CMA_GIT__COMMIT_AUTHOR_NAME` | `Claude` | Il nome dell’autore sui commit dell’agente. Impostalo insieme a `git.commit_author_email`. |
| `git.commit_author_email`
`CMA_GIT__COMMIT_AUTHOR_EMAIL` | `noreply@anthropic.com` | L’indirizzo email dell’autore sui commit dell’agente. Impostalo insieme a `git.commit_author_name`. |
| `git.max_concurrent_transfers`
`CMA_GIT__MAX_CONCURRENT_TRANSFERS` | `32` | Il numero massimo di richieste Git che un server gestisce contemporaneamente. Il minimo è `1`. |
| `git.max_session_transfer_bytes`
`CMA_GIT__MAX_SESSION_TRANSFER_BYTES` | `8589934592` (8 GiB) | Il traffico Git massimo, in byte, che un server gestisce per una sessione, upload e download insieme. Il conteggio riparte da zero ogni volta che una sandbox riprende la sessione. Al raggiungimento del limite, il server rifiuta le successive richieste Git della sessione con un `403`. `0` indica nessun limite. Altrimenti, il minimo è `1048576`. |
| `git.max_push_bytes`
`CMA_GIT__MAX_PUSH_BYTES` | `2147483648` (2 GiB) | Il numero massimo di byte che un push può inviare. Il minimo è `1048576`. |
Questi limiti si applicano ai repository Git:
* **Protocolli:** Il server non supporta SSH né Git LFS e rifiuta i reindirizzamenti, come quello per un repository rinominato.
* **Token:** L’host Git deve accettare il token come password dell’autenticazione HTTP Basic, con il nome utente `x-access-token`.
* **URL:** L’URL di un repository ha un solo proprietario e un solo nome di repository, quindi non puoi usare un repository in un sottogruppo GitLab.
* **Host:** Per un URL su un host che `git.allowed_hostnames` non elenca, il server restituisce un `400`. Il messaggio di errore indica che l’URL deve trovarsi su `github.com`, anche se elenchi altri host.
* **Push:** Il server rifiuta sempre un push che elimina un branch o che modifica qualcosa di diverso da un branch, come un tag.
## Strumenti web e skill
Consulta [Gli strumenti web richiedono un’impostazione del server](https://platform.claude.com/docs/it/managed-agents/self-hosted/differences#web-tools-need-a-server-setting).
| Impostazione
Variabile d’ambiente | Predefinito | Descrizione |
| ----------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `web_tools.enabled`
`CMA_WEB_TOOLS__ENABLED` | `false` | Se gli agenti possono usare gli strumenti `web_search` e `web_fetch`. Se imposti un’altra impostazione `web_tools`, il valore predefinito è `true`. |
| `web_tools.allowed_domains`
`CMA_WEB_TOOLS__ALLOWED_DOMAINS` | Nessuno | Gli unici domini che gli agenti possono leggere tramite gli strumenti web. Una voce copre i suoi sottodomini. |
| `web_tools.blocked_domains`
`CMA_WEB_TOOLS__BLOCKED_DOMAINS` | Nessuno | Domini che nessun agente può leggere tramite gli strumenti web. Imposta questa oppure `web_tools.allowed_domains`, non entrambe. |
| `web_tools.max_content_tokens`
`CMA_WEB_TOOLS__MAX_CONTENT_TOKENS` | Nessuno | Il numero massimo di token di una pagina recuperata che `web_fetch` restituisce al modello. |
| `skills.max_name_chars`
`CMA_SKILLS__MAX_NAME_CHARS` | `64` | La lunghezza massima del `name` che un file `SKILL.md` può avere. Il massimo è `255`. |
| `skills.max_description_chars`
`CMA_SKILLS__MAX_DESCRIPTION_CHARS` | `1024` | La lunghezza massima della `description` che un file `SKILL.md` può avere. |
## Limiti, timeout e pianificazione
| Impostazione
Variabile d’ambiente | Predefinito | Descrizione |
| ------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `limits.max_active_sessions`
`CMA_LIMITS__MAX_ACTIVE_SESSIONS` | `64` | Solo `store.backend: memory`. Il numero massimo di sessioni che eseguono un turno contemporaneamente. `0` indica nessun limite. |
| `limits.max_live_subagent_threads`
`CMA_LIMITS__MAX_LIVE_SUBAGENT_THREADS` | `25` | Il numero massimo di thread di subagenti che una sessione può mantenere contemporaneamente. Un thread viene conteggiato finché non viene archiviato o terminato, quindi anche un thread inattivo viene conteggiato. Al raggiungimento del limite, l’agente non può avviare un altro subagente. Il minimo è `1` e il massimo è `4000`. |
| `scheduler.max_concurrent_turns`
`CMA_SCHEDULER__MAX_CONCURRENT_TURNS` | `64` | Solo `store.backend: postgres`. Il numero massimo di turni che un server esegue contemporaneamente. Il minimo è `1`. Il server riserva slot aggiuntivi esclusivamente ai turni dei subagenti. Il loro numero è un quarto di questo valore, e almeno `4`. Con il valore predefinito, un server può eseguire 64 turni più 16 turni di subagenti. |
| `scheduler.claim_poll_interval`
`CMA_SCHEDULER__CLAIM_POLL_INTERVAL` | `1s` | Solo `store.backend: postgres`. Ogni quanto un server con uno slot di turno libero cerca nel database lavoro in attesa. Il minimo è `50ms`. |
| `scheduler.sandbox_claim`
`CMA_SCHEDULER__SANDBOX_CLAIM` | `immediate` | Quando un worker può avviare la sandbox di una sessione. `immediate` indica non appena la sessione viene creata, così la prima chiamata a uno strumento attende il meno possibile. `tool_call` indica alla prima chiamata a uno strumento della sessione che richiede la sandbox, così una sessione che non ne effettua nessuna non usa alcuna sandbox. |
| `limits.model_call_timeout`
`CMA_LIMITS__MODEL_CALL_TIMEOUT` | `20m` | Per quanto tempo può durare una chiamata al modello, tentativi inclusi, prima che il server la annulli. |
| `limits.stream_idle_timeout`
`CMA_LIMITS__STREAM_IDLE_TIMEOUT` | `5m` | Per quanto tempo la risposta di una chiamata al modello può non consegnare nulla prima che il server abbandoni quel tentativo. |
| `limits.mcp_call_timeout`
`CMA_LIMITS__MCP_CALL_TIMEOUT` | `4m` | Per quanto tempo può durare una chiamata a uno strumento MCP prima che il server la abbandoni. |
## Modelli e compattazione
| Impostazione
Variabile d’ambiente | Predefinito | Descrizione |
| -------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `models.settings`
Solo file | Nessuno | Modifiche al catalogo di modelli integrato del server, indicizzate per ID del modello. Consulta [Voci dei modelli](https://platform.claude.com/docs/it/managed-agents/self-hosted/configuration-reference#model-entries). |
| `compaction.triggers`
Solo file | Circa il 90% della “context window” (finestra di contesto) di ciascun modello | La dimensione del contesto, in token, alla quale un turno su un modello compatta la sua cronologia, indicizzata per ID del modello. Il minimo è `50000`. Ogni modello deve supportare la compattazione. |
### Voci dei modelli
Ogni voce di `models.settings` modifica un modello nel catalogo o ne aggiunge uno. Per un modello nel catalogo, un campo che ometti mantiene il suo valore integrato.
| Campo | Descrizione |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fast_supported` | Se il modello accetta `speed: "fast"`. Obbligatorio per un modello che aggiungi. |
| `inference_geo_supported` | Se il modello accetta `inference_geo`. |
| `forced_tool_choice_supported` | Se il modello accetta una richiesta che lo obbliga a chiamare uno strumento. Il server invia una richiesta di questo tipo solo per eseguire una chiamata `web_search` o `web_fetch` che è stata approvata. Con `false`, non forza mai uno strumento su questo modello. |
| `effort_supported` | Se il modello accetta un livello di effort. |
| `effort_levels` | I livelli di effort che il modello accetta, tra `low`, `medium`, `high`, `xhigh` e `max`. Obbligatorio con `effort_supported: true` su un modello senza livelli integrati. |
| `effort_default` | Il livello di effort di una sessione il cui agente non ne indica nessuno. Deve essere uno di `effort_levels`. Obbligatorio con `effort_supported: true` su un modello senza un valore predefinito integrato. |
| `thinking` | La modalità di “thinking” (ragionamento) che il server richiede, `enabled` o `adaptive`. |
| `thinking_budget` | Il budget di ragionamento, in token, che il server invia con `thinking: enabled`. |
| `max_tokens` | Il valore `max_tokens` di ogni chiamata al modello. |
## Console sul tuo server
| Impostazione
Variabile d’ambiente | Predefinito | Descrizione |
| ----------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------- |
| `console.serve`
`CMA_CONSOLE__SERVE` | `true` | Se servire la [console sul tuo server](https://platform.claude.com/docs/it/managed-agents/self-hosted/console). |