Iniziare con Claude Managed Agents self-hosted

In questa guida rapida, avvii Claude Managed Agents self-hosted su una sola macchina con Docker Compose. Lo stack Compose è composto dal server, dal suo database PostgreSQL e da un insieme di worker che eseguono ciascuna sessione in un proprio “sandbox container” (container sandbox). Poi chatti con un agente dal tuo terminale e verifichi che le sue chiamate agli strumenti siano state eseguite in un container sandbox. Puoi poi aprire la sessione nella console sul tuo server.

Per la produzione, Anthropic consiglia i due chart Helm della release. Consulta Distribuire su Kubernetes.

Prerequisiti

• L’archivio della release: Per richiedere l’accesso al download, contatta il tuo team account di Anthropic.
• Una chiave API di Claude: Il server la usa per le chiamate al modello. Creane una nella Claude Console.
• Docker: La versione più recente di Docker Engine con il plugin Compose (docker compose, non il vecchio docker-compose).
• Un host con almeno due CPU: x86-64 o Arm. Su un host più piccolo, imposta CMA_SANDBOX_CPUS sul numero di CPU dell’host quando crei .env.
• Accesso alla rete al primo avvio: La prima build scarica da Docker Hub, dai repository dei pacchetti Alpine e dalle release di GitHub.
• Strumenti: Sulla macchina su cui esegui Docker, ti servono openssl e la CLI ant.

Avviare lo stack

1. 1

   Estrarre l’archivio

   Estrai l’archivio e lavora dalla sua directory compose. Nel comando, sostituisci <archive> con il nome del tuo archivio, senza .tar.gz.

   tar -xzf <archive>.tar.gz && cd <archive>/compose

   

   Se la tua umask è più restrittiva di 022, i binari perdono il permesso di esecuzione per gli altri utenti e il container del server non può avviarli. In tal caso, impostala su 022 ed estrai di nuovo l’archivio.

2. 2

   Creare il file .env

   Compose legge i segreti dello stack da un file .env accanto a docker-compose.yml. Crea il file:

   cat > .env <<EOF
   CMA_PG_PASSWORD=$(openssl rand -hex 32)
   ANTHROPIC_API_KEY=sk-ant-...
   CMA_SERVER__API_KEY=$(openssl rand -hex 32)
   CMA_STORE__CREDENTIALS_ENCRYPTION_KEY=$(openssl rand -base64 32)
   EOF
   chmod 600 .env

   

   Apri .env in un editor e sostituisci sk-ant-... con la tua chiave API di Claude. Il blocco genera il resto: la password del database, la chiave API del server che le tue applicazioni inviano e la chiave che cifra i segreti memorizzati dal server.

3. 3

   Avviare i container

   Compila e avvia lo stack, quindi segui il log del server:

   docker compose up --build -d
   docker compose logs -f cma-server

   

   Quando il log mostra una riga con msg="cma-server listening", premi Ctrl+C per smettere di seguirlo.

4. 4

   Verificare che il server sia pronto

   curl -s http://127.0.0.1:8400/cma-server/readyz

   

   Un server pronto risponde con "status":"ready". Subito dopo l’avvio, può rispondere "status":"degraded" per qualche secondo mentre vengono eseguiti i suoi primi controlli. Se resta degraded o risponde "status":"not_ready", consulta Risoluzione dei problemi.

Eseguire la tua prima sessione

Crea un agente e chatta con esso dal tuo terminale con la CLI ant.

1. 1

   Puntare la CLI al tuo server

   Apri un secondo terminale nella stessa directory e tienilo per ant. I comandi seguenti impostano ANTHROPIC_API_KEY sulla chiave API del tuo server, non sulla tua chiave API di Claude, come spiega Chiamare l’API su un server self-hosted:

   export ANTHROPIC_BASE_URL=http://127.0.0.1:8400
   export ANTHROPIC_API_KEY=$(grep '^CMA_SERVER__API_KEY=' .env | cut -d= -f2)

   

   Tieni i comandi docker compose nel primo terminale. Se esegui docker compose up in questo terminale, Compose passa queste variabili al server e il server chiama se stesso invece dell’API di Claude.

2. 2

   Creare un agente

   Salva il file che segue il comando come quickstart-agent.md, quindi esegui il comando. Il file fornisce all’agente gli strumenti integrati e gli consente di eseguirli senza chiedertelo prima.

   CLI

   

   ant apply --yes quickstart-agent.md

   quickstart-agent.md

   

   ---
   name: Quickstart agent
   model: claude-opus-5-5
   tools:
     - type: agent_toolset_20260401
   ---
   
   You are a helpful assistant.

   Il comando stampa prima un avviso che indica che could not determine the organization and workspace, con un errore 404, e poi crea l’agente. Sul tuo server è un comportamento previsto.

3. 3

   Avviare una sessione

   Questi comandi trovano l’agente e l’ambiente dello stack, avviano una sessione e conservano l’ID della sessione in SESSION_ID. Lo stack assegna al suo ambiente il nome compose-sandbox.

   AGENT_ID=$(ant beta:agents list --format raw \
     --transform 'data.#(name=="Quickstart agent").id' --raw-output)
   ENVIRONMENT_ID=$(ant beta:environments list --format raw \
     --transform 'data.#(name=="compose-sandbox").id' --raw-output)
   SESSION_ID=$(ant beta:sessions create --agent "$AGENT_ID" \
     --environment-id "$ENVIRONMENT_ID" --transform id --raw-output)

   
4. 4

   Chiedere all’agente di eseguire un comando

   Collega il tuo terminale alla sessione:

   ant beta:sessions connect "$SESSION_ID"

   

   Il comando apre una vista chat della sessione. Invia questo messaggio:

   Run `hostname` with the bash tool and tell me the output.

   

   L’agente risponde con un hostname che inizia con cma-sandbox-. È il nome del container sandbox che ha eseguito il comando, il che conferma che lo strumento è stato eseguito in una sandbox e non sulla tua macchina.

5. 5

   Trovare il container sandbox

   Lascia aperta la chat. Nel primo terminale, elenca i container sandbox:

   docker ps --filter label=cma-server.sandbox

   

   L’elenco mostra il container indicato dall’agente. Il container termina circa un minuto dopo la fine di un turno, e il messaggio successivo della sessione avvia un nuovo container. Se l’elenco è vuoto, chiedi di nuovo all’agente di eseguire hostname ed elenca di nuovo i container mentre risponde.

   Per uscire dalla chat, premi Ctrl+C nel suo terminale. La sessione continua a essere eseguita.

Provare la console sul tuo server

Questa sezione è facoltativa. La console richiede il single sign-on. Per provarla, riavvia lo stack con il provider di accesso fittizio della release. La porta 8080 sulla tua macchina deve essere libera.

1. 1

   Riavviare lo stack con il provider di accesso fittizio

   Esegui questi comandi nel primo terminale:

   export COMPOSE_FILE=docker-compose.yml:docker-compose.oidc.yml
   docker compose up --build -d

   

   La riga export vale solo per il primo terminale, quindi eseguila di nuovo in ogni nuovo terminale che apri per docker compose. Per modificare le impostazioni del server in questo stack, modifica compose.config.oidc.yaml, non compose.config.yaml, quindi esegui docker compose restart cma-server.

2. 2

   Aprire la sessione

   In un browser sulla stessa macchina, apri http://127.0.0.1:8400/, fai clic su Continue with SSO e seleziona alice, l’amministratore demo. Nella barra laterale, seleziona Sessions, quindi seleziona la sessione.

   La pagina si aggiorna mentre l’agente lavora, e da essa puoi inviare un messaggio all’agente.

Per creare agenti e avviare sessioni anche nella console, consulta Eseguire un agente dalla console.

Arrestare lo stack

Nel primo terminale, esegui questo comando:

docker compose down --remove-orphans

Il comando elimina i container e mantiene il database. Per eliminare anche il database, con ogni agente, sessione e cronologia delle sessioni che contiene, esegui docker compose down --remove-orphans -v.

Risoluzione dei problemi

• Il tuo archivio non ha una directory compose: L’archivio contiene una release precedente e i comandi di questa pagina non corrispondono a essa. Chiedi la release attuale al tuo team account di Anthropic. Per spostare un deployment in esecuzione alla release attuale, consulta Aggiornare Claude Managed Agents self-hosted.
• Il server non si avvia mai: Esegui docker compose logs migrate. Il container migrate eseguito una sola volta crea le tabelle del database. Deve terminare con stato 0 prima che il server si avvii.
• Il controllo di disponibilità resta degraded, oppure ogni turno non riesce: Se hai eseguito docker compose up in un terminale in cui ANTHROPIC_BASE_URL è http://127.0.0.1:8400, il server chiama se stesso invece dell’API di Claude. Esegui di nuovo docker compose up -d nel primo terminale, dove la variabile non è impostata. Altrimenti, il log del server mostra cosa non è riuscito. Per leggerlo, esegui di nuovo docker compose logs -f cma-server.
• Il controllo di disponibilità risponde not_ready: Nella risposta, trova il controllo con lo stato failed:
  • upstream: L’API di Claude ha rifiutato la tua chiave API di Claude. Correggi ANTHROPIC_API_KEY in .env, poi, nel primo terminale, esegui di nuovo docker compose up -d. Se anche la tua shell imposta ANTHROPIC_API_KEY, Compose usa il valore della shell, quindi esegui prima unset ANTHROPIC_API_KEY.
  • database: Il database ha rifiutato il login del server, ad esempio a causa di una password errata, oppure una connessione aperta al database si è interrotta. Per capire quale dei due, esegui di nuovo docker compose logs -f cma-server.
• L’agente risponde ma la sua chiamata allo strumento non termina mai: Nessun worker sta interrogando l’ambiente. Controlla il log dei worker con docker compose logs sandbox. Un worker che non riesce a raggiungere il socket del daemon Docker termina con un messaggio che cita CMA_DOCKER_SOCKET. Imposta quella variabile in .env sul percorso del socket del tuo daemon, poi, nel primo terminale, esegui di nuovo docker compose up -d.
• I worker sono in esecuzione, ma una chiamata allo strumento continua a non terminare mai: Lo stack avvia 10 worker, e ciascuno esegue il container di una sola sessione alla volta. Una sessione occupa un worker libero quando la crei, e una sessione che non riceve mai un messaggio mantiene il suo worker fino a un’ora. Con tutti e 10 occupati, le chiamate agli strumenti di qualsiasi altra sessione attendono un worker. Se il comando docker ps nel passaggio “Trovare il container sandbox” elenca 10 container, archivia le sessioni che non usi:
  1. Nel primo terminale, esegui docker ps --filter label=cma-server.sandbox --format '{{.Label "cma-server.session"}}'. Stampa l’ID della sessione dietro ciascun container. La sessione in attesa non ha ancora un container, quindi non compare nell’elenco.
  2. Nel secondo terminale, premi Ctrl+C per uscire dalla chat ed esegui ant beta:sessions archive --session-id <session-id> per ogni sessione elencata che non usi.
  3. Esegui di nuovo ant beta:sessions connect "$SESSION_ID". La chiamata allo strumento termina quando un worker prende in carico la sua sessione.

Prossimi passi