---
title: Iniziare con Claude Managed Agents self-hosted
url: https://platform.claude.com/docs/it/managed-agents/self-hosted/quickstart
description: Avvia Claude Managed Agents self-hosted su una sola macchina con Docker Compose ed esegui una prima sessione in un container sandbox.
---

<Note>
  Per richiedere l’accesso a Claude Managed Agents self-hosted, contatta il tuo team di riferimento Anthropic.
</Note>

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](https://platform.claude.com/docs/it/managed-agents/self-hosted/console).

<Warning>
  Lo stack Compose serve per lo sviluppo, non per la produzione. Espone HTTP in chiaro e, per impostazione predefinita, pubblica la porta 8400 solo sull’indirizzo di loopback dell’host Docker, `127.0.0.1`. Con alcune release di Docker Engine precedenti alla 28.3.3, anche le macchine sulla rete locale dell’host possono raggiungere quella porta. Gli strumenti dell’agente vengono eseguiti in container su quell’host, quindi usa una macchina che non contenga nulla che tu debba proteggere.
</Warning>

Per la produzione, Anthropic consiglia i due chart Helm della release. Consulta [Distribuire su Kubernetes](https://platform.claude.com/docs/it/managed-agents/self-hosted/kubernetes).

Lascia che Claude Code esegua questa guida rapida per te

```text
Configura Claude Managed Agents self-hosted su questa macchina seguendo https://platform.claude.com/docs/en/managed-agents/self-hosted/quickstart.md. Ho già scaricato l'archivio della release.
```

Se sei un agente che esegue questi passaggi per una persona:

* **Archivio della release:** Chiedi alla persona dove si trova l’archivio. Solo lei può scaricarlo.
* **Chiave API di Claude:** Fai modificare `.env` direttamente alla persona. Non chiedere la chiave e non stampare `.env`.
* **Variabili:** Se la tua shell non conserva le variabili tra un comando e l’altro, imposta di nuovo `ANTHROPIC_BASE_URL` e `ANTHROPIC_API_KEY` in ogni comando `ant`. Senza di esse, `ant` chiama il servizio ospitato.
* **Compose:** Metti `env -u ANTHROPIC_BASE_URL -u ANTHROPIC_API_KEY -u ANTHROPIC_AUTH_TOKEN` davanti a ogni comando `docker compose`, in modo che i valori della tua shell non raggiungano il server.
* **Chat:** `ant beta:sessions connect` richiede un terminale interattivo. Senza un terminale interattivo, invia il messaggio con `ant beta:sessions:events send` e leggi la risposta con `ant beta:sessions:events list`. [Inviare eventi](https://platform.claude.com/docs/it/managed-agents/events-and-streaming#send-events) ed [Elencare gli eventi passati](https://platform.claude.com/docs/it/managed-agents/events-and-streaming#list-past-events) contengono degli esempi.
* **Console:** Esegui la sezione “Provare la console sul tuo server” solo se la persona lo richiede. Se la tua shell non conserva le variabili tra un comando e l’altro, metti anche `COMPOSE_FILE=docker-compose.yml:docker-compose.oidc.yml` davanti a ogni comando `docker compose` da quella sezione in poi.

## 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](https://platform.claude.com/settings/keys).
* **Docker:** La [versione più recente di Docker Engine](https://docs.docker.com/engine/install/) 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`](https://platform.claude.com/docs/it/cli-sdks-libraries/cli/quickstart#installation).

## Avviare lo stack

<Steps>
  <Step title="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`.

    ```bash
    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.
  </Step>

  <Step title="Creare il file .env">
    Compose legge i segreti dello stack da un file `.env` accanto a `docker-compose.yml`. Crea il file:

    ```bash
    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.
  </Step>

  <Step title="Avviare i container">
    Compila e avvia lo stack, quindi segui il log del server:

    ```bash
    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.
  </Step>

  <Step title="Verificare che il server sia pronto">
    ```bash
    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](https://platform.claude.com/docs/it/managed-agents/self-hosted/quickstart#troubleshooting).
  </Step>
</Steps>

## Eseguire la tua prima sessione

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

<Steps>
  <Step title="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](https://platform.claude.com/docs/it/managed-agents/self-hosted/call-the-api):

    ```bash
    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.
  </Step>

  <Step title="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.

    <CodeGroup>
      <CodeGroupItem>
        ```bash CLI
        ant apply --yes quickstart-agent.md
        ```

        <File filename="quickstart-agent.md">
          ```markdown
          ---
          name: Quickstart agent
          model: claude-opus-5-5
          tools:
            - type: agent_toolset_20260401
          ---

          You are a helpful assistant.
          ```
        </File>
      </CodeGroupItem>
    </CodeGroup>

    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.
  </Step>

  <Step title="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`.

    ```bash
    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)
    ```
  </Step>

  <Step title="Chiedere all’agente di eseguire un comando">
    Collega il tuo terminale alla sessione:

    ```bash
    ant beta:sessions connect "$SESSION_ID"
    ```

    Il comando apre una [vista chat](https://platform.claude.com/docs/it/cli-sdks-libraries/cli/sessions-connect) della sessione. Invia questo messaggio:

    ```text wrap
    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.
  </Step>

  <Step title="Trovare il container sandbox">
    Lascia aperta la chat. Nel primo terminale, elenca i container sandbox:

    ```bash
    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.
  </Step>
</Steps>

## 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.

<Warning>
  Usa il provider fittizio solo con dati usa e getta. Fornisce un token di amministratore a chiunque lo raggiunga. Su Docker Desktop, ciò include i container sandbox. Con alcune release di Docker Engine precedenti alla 28.3.3, include le macchine sulla tua rete.
</Warning>

<Steps>
  <Step title="Riavviare lo stack con il provider di accesso fittizio">
    Esegui questi comandi nel primo terminale:

    ```bash
    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`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

Per creare agenti e avviare sessioni anche nella console, consulta [Eseguire un agente dalla console](https://platform.claude.com/docs/it/managed-agents/self-hosted/console#run-an-agent-from-the-console).

## Arrestare lo stack

Nel primo terminale, esegui questo comando:

```bash
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](https://platform.claude.com/docs/it/managed-agents/self-hosted/upgrade).

* **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

<CardGroup cols={2}>
  <Card title="Chiamare l’API" icon="code-brackets" href="https://platform.claude.com/docs/it/managed-agents/self-hosted/call-the-api">
    Punta l’SDK e la CLI `ant` al tuo server.
  </Card>

  <Card title="Differenze rispetto al servizio ospitato" icon="arrows-left-right" href="https://platform.claude.com/docs/it/managed-agents/self-hosted/differences">
    Verifica quali funzionalità si comportano diversamente o non sono disponibili.
  </Card>

  <Card title="Console sul tuo server" icon="browser" href="https://platform.claude.com/docs/it/managed-agents/self-hosted/console">
    Configura l’accesso, crea agenti ed esegui sessioni in un browser.
  </Card>
</CardGroup>