---
title: Démarrer avec Claude Managed Agents auto-hébergé
url: https://platform.claude.com/docs/fr/managed-agents/self-hosted/quickstart
description: Démarrez Claude Managed Agents auto-hébergé sur une seule machine avec Docker Compose et exécutez une première session dans un conteneur de sandbox.
---

<Note>
  Pour demander l’accès à Claude Managed Agents auto-hébergé, contactez l’équipe de votre compte Anthropic.
</Note>

Dans ce guide de démarrage rapide, vous lancez Claude Managed Agents auto-hébergé sur une seule machine avec Docker Compose. La pile Compose se compose du serveur, de sa base de données PostgreSQL et d’un ensemble de workers qui exécutent chaque session dans son propre conteneur de sandbox. Vous discutez ensuite avec un agent depuis votre terminal et confirmez que ses appels d’outils se sont exécutés dans un conteneur de sandbox. Vous pouvez ensuite ouvrir la session dans la [console de votre serveur](https://platform.claude.com/docs/fr/managed-agents/self-hosted/console).

<Warning>
  La pile Compose est destinée au développement, pas à la production. Elle sert du HTTP en clair et, par défaut, ne publie le port 8400 que sur l’adresse de bouclage de l’hôte Docker, `127.0.0.1`. Avec certaines versions de Docker Engine antérieures à 28.3.3, les machines du réseau local de l’hôte peuvent également atteindre ce port. Les outils de l’agent s’exécutent dans des conteneurs sur cet hôte : utilisez donc une machine qui ne contient rien que vous deviez protéger.
</Warning>

Pour la production, Anthropic recommande les deux charts Helm de la version. Consultez [Déployer sur Kubernetes](https://platform.claude.com/docs/fr/managed-agents/self-hosted/kubernetes).

Laissez Claude Code exécuter ce guide de démarrage rapide pour vous

```text
Configure Claude Managed Agents auto-hébergé sur cette machine en suivant https://platform.claude.com/docs/en/managed-agents/self-hosted/quickstart.md. J'ai déjà téléchargé l'archive de la version.
```

Si vous êtes un agent qui exécute ces étapes pour une personne :

* **Archive de la version :** Demandez à la personne où se trouve l’archive. Elle seule peut la télécharger.
* **Clé API Claude :** Faites modifier `.env` par la personne elle-même. Ne demandez pas la clé et n’affichez pas `.env`.
* **Variables :** Si votre shell ne conserve pas les variables entre les commandes, définissez à nouveau `ANTHROPIC_BASE_URL` et `ANTHROPIC_API_KEY` dans chaque commande `ant`. Sans elles, `ant` appelle le service hébergé.
* **Compose :** Placez `env -u ANTHROPIC_BASE_URL -u ANTHROPIC_API_KEY -u ANTHROPIC_AUTH_TOKEN` devant chaque commande `docker compose`, afin que les valeurs de votre shell n’atteignent pas le serveur.
* **Discussion :** `ant beta:sessions connect` nécessite un terminal interactif. Sans terminal interactif, envoyez le message avec `ant beta:sessions:events send` et lisez la réponse avec `ant beta:sessions:events list`. [Envoyer des événements](https://platform.claude.com/docs/fr/managed-agents/events-and-streaming#send-events) et [Lister les événements passés](https://platform.claude.com/docs/fr/managed-agents/events-and-streaming#list-past-events) contiennent des exemples.
* **Console :** N’effectuez la section « Essayer la console de votre serveur » que si la personne le demande. Si votre shell ne conserve pas les variables entre les commandes, placez également `COMPOSE_FILE=docker-compose.yml:docker-compose.oidc.yml` devant chaque commande `docker compose` à partir de cette section.

## Prérequis

* **L’archive de la version :** Pour demander l’accès au téléchargement, contactez l’équipe chargée de votre compte Anthropic.
* **Une clé API Claude :** Le serveur l’utilise pour les appels au modèle. Créez-en une dans la [Claude Console](https://platform.claude.com/settings/keys).
* **Docker :** La [dernière version de Docker Engine](https://docs.docker.com/engine/install/) avec le plugin Compose (`docker compose`, et non l’ancien `docker-compose`).
* **Un hôte disposant d’au moins deux CPU :** x86-64 ou Arm. Sur un hôte plus petit, définissez `CMA_SANDBOX_CPUS` sur son nombre de CPU lorsque vous créez `.env`.
* **Accès réseau au premier démarrage :** La première construction récupère des éléments depuis Docker Hub, les dépôts de paquets Alpine et les versions publiées sur GitHub.
* **Outils :** Sur la machine où vous exécutez Docker, vous avez besoin de `openssl` et de la [CLI `ant`](https://platform.claude.com/docs/fr/cli-sdks-libraries/cli/quickstart#installation).

## Démarrer la pile

<Steps>
  <Step title="Extraire l’archive">
    Extrayez l’archive et travaillez depuis son répertoire `compose`. Dans la commande, remplacez `<archive>` par le nom de votre archive, sans `.tar.gz`.

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

    Si votre umask est plus strict que `022`, les binaires perdent leur permission d’exécution pour les autres utilisateurs, et le conteneur du serveur ne peut pas les lancer. Dans ce cas, définissez-le sur `022` et extrayez à nouveau l’archive.
  </Step>

  <Step title="Créer le fichier .env">
    Compose lit les secrets de la pile depuis un fichier `.env` situé à côté de `docker-compose.yml`. Créez le fichier :

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

    Ouvrez `.env` dans un éditeur et remplacez `sk-ant-...` par votre clé API Claude. Le bloc génère le reste : le mot de passe de la base de données, la clé API du serveur que vos applications envoient, et la clé qui chiffre les secrets stockés par le serveur.
  </Step>

  <Step title="Démarrer les conteneurs">
    Construisez et démarrez la pile, puis suivez le journal du serveur :

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

    Lorsque le journal affiche une ligne contenant `msg="cma-server listening"`, appuyez sur Ctrl+C pour arrêter de le suivre.
  </Step>

  <Step title="Vérifier que le serveur est prêt">
    ```bash
    curl -s http://127.0.0.1:8400/cma-server/readyz
    ```

    Un serveur prêt répond avec `"status":"ready"`. Juste après le démarrage, il peut répondre `"status":"degraded"` pendant quelques secondes, le temps que ses premières vérifications s’exécutent. S’il reste `degraded` ou répond `"status":"not_ready"`, consultez [Dépannage](https://platform.claude.com/docs/fr/managed-agents/self-hosted/quickstart#troubleshooting).
  </Step>
</Steps>

## Exécuter votre première session

Créez un agent et discutez avec lui depuis votre terminal avec la CLI `ant`.

<Steps>
  <Step title="Diriger la CLI vers votre serveur">
    Ouvrez un second terminal dans le même répertoire et réservez-le à `ant`. Les commandes suivantes définissent `ANTHROPIC_API_KEY` sur la clé API de votre serveur, et non sur votre clé API Claude, comme l’explique [Appeler l’API sur un serveur auto-hébergé](https://platform.claude.com/docs/fr/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)
    ```

    Conservez les commandes `docker compose` dans le premier terminal. Si vous exécutez `docker compose up` dans ce terminal, Compose transmet ces variables au serveur, et le serveur s’appelle lui-même au lieu de l’API Claude.
  </Step>

  <Step title="Créer un agent">
    Enregistrez le fichier qui suit la commande sous le nom `quickstart-agent.md`, puis exécutez la commande. Le fichier donne à l’agent les outils intégrés et lui permet de les exécuter sans vous le demander d’abord.

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

    La commande affiche d’abord un avertissement indiquant qu’elle `could not determine the organization and workspace`, avec une erreur `404`, puis crée l’agent. C’est le comportement attendu sur votre propre serveur.
  </Step>

  <Step title="Démarrer une session">
    Ces commandes trouvent l’agent et l’environnement de la pile, démarrent une session et conservent l’ID de la session dans `SESSION_ID`. La pile nomme son environnement `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="Demander à l’agent d’exécuter une commande">
    Connectez votre terminal à la session :

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

    La commande ouvre une [vue de discussion](https://platform.claude.com/docs/fr/cli-sdks-libraries/cli/sessions-connect) de la session. Envoyez ce message :

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

    L’agent répond avec un nom d’hôte qui commence par `cma-sandbox-`. C’est le nom du conteneur de sandbox qui a exécuté la commande, ce qui confirme que l’outil s’est exécuté dans une sandbox et non sur votre machine.
  </Step>

  <Step title="Trouver le conteneur de sandbox">
    Laissez la discussion ouverte. Dans le premier terminal, listez les conteneurs de sandbox :

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

    La liste affiche le conteneur signalé par l’agent. Le conteneur s’arrête environ une minute après la fin d’un tour, et le message suivant de la session démarre un nouveau conteneur. Si la liste est vide, demandez à nouveau à l’agent d’exécuter `hostname`, et listez à nouveau les conteneurs pendant qu’il répond.

    Pour quitter la discussion, appuyez sur Ctrl+C dans son terminal. La session continue de s’exécuter.
  </Step>
</Steps>

## Essayer la console de votre serveur

Cette section est facultative. La console nécessite l’authentification unique. Pour l’essayer, redémarrez la pile avec le fournisseur de connexion fictif de la version. Le port 8080 de votre machine doit être libre.

<Warning>
  Utilisez le fournisseur fictif uniquement avec des données jetables. Il remet un jeton d’administrateur à quiconque l’atteint. Sur Docker Desktop, cela inclut les conteneurs de sandbox. Avec certaines versions de Docker Engine antérieures à 28.3.3, cela inclut les machines de votre réseau.
</Warning>

<Steps>
  <Step title="Redémarrer la pile avec le fournisseur de connexion fictif">
    Exécutez ces commandes dans le premier terminal :

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

    La ligne `export` ne s’applique qu’au premier terminal : exécutez-la donc à nouveau dans tout nouveau terminal que vous ouvrez pour `docker compose`. Pour modifier les paramètres du serveur dans cette pile, modifiez `compose.config.oidc.yaml`, et non `compose.config.yaml`, puis exécutez `docker compose restart cma-server`.
  </Step>

  <Step title="Ouvrir la session">
    Dans un navigateur sur la même machine, ouvrez `http://127.0.0.1:8400/`, cliquez sur **Continue with SSO**, puis sélectionnez **alice**, l’administrateur de démonstration. Dans la barre latérale, sélectionnez **Sessions**, puis sélectionnez la session.

    La page se met à jour à mesure que l’agent travaille, et vous pouvez envoyer un message à l’agent depuis celle-ci.
  </Step>
</Steps>

Pour créer également des agents et démarrer des sessions dans la console, consultez [Exécuter un agent depuis la console](https://platform.claude.com/docs/fr/managed-agents/self-hosted/console#run-an-agent-from-the-console).

## Arrêter la pile

Dans le premier terminal, exécutez cette commande :

```bash
docker compose down --remove-orphans
```

La commande supprime les conteneurs et conserve la base de données. Pour supprimer également la base de données, avec chaque agent, session et historique des sessions qu’elle contient, exécutez `docker compose down --remove-orphans -v`.

## Dépannage

* **Votre archive ne contient pas de répertoire `compose` :** L’archive contient une version antérieure, et les commandes de cette page ne lui correspondent pas. Demandez la version actuelle à l’équipe chargée de votre compte Anthropic. Pour migrer un déploiement en cours d’exécution vers la version actuelle, consultez [Mettre à niveau Claude Managed Agents auto-hébergé](https://platform.claude.com/docs/fr/managed-agents/self-hosted/upgrade).

* **Le serveur ne démarre jamais :** Exécutez `docker compose logs migrate`. Le conteneur `migrate` à usage unique crée les tables de la base de données. Il doit se terminer avec le statut `0` avant que le serveur ne démarre.

* **La vérification de disponibilité reste `degraded`, ou chaque tour échoue :** Si vous avez exécuté `docker compose up` dans un terminal où `ANTHROPIC_BASE_URL` vaut `http://127.0.0.1:8400`, le serveur s’appelle lui-même au lieu de l’API Claude. Exécutez à nouveau `docker compose up -d` dans le premier terminal, où la variable n’est pas définie. Sinon, le journal du serveur indique ce qui a échoué. Pour le lire, exécutez à nouveau `docker compose logs -f cma-server`.

* **La vérification de disponibilité répond `not_ready` :** Dans la réponse, trouvez la vérification dont l’état est `failed` :

  * **`upstream` :** L’API Claude a rejeté votre clé API Claude. Corrigez `ANTHROPIC_API_KEY` dans `.env`, puis exécutez à nouveau `docker compose up -d` dans le premier terminal. Si votre shell définit également `ANTHROPIC_API_KEY`, Compose utilise la valeur du shell : exécutez donc d’abord `unset ANTHROPIC_API_KEY`.
  * **`database` :** Soit la base de données a rejeté la connexion du serveur, par exemple à cause d’un mot de passe erroné, soit une connexion ouverte à la base de données a été interrompue. Pour savoir laquelle, exécutez à nouveau `docker compose logs -f cma-server`.

* **L’agent répond mais son appel d’outil ne se termine jamais :** Aucun worker n’interroge l’environnement. Consultez le journal des workers avec `docker compose logs sandbox`. Un worker qui ne peut pas atteindre le socket du démon Docker se termine avec un message qui mentionne `CMA_DOCKER_SOCKET`. Définissez cette variable dans `.env` sur le chemin du socket de votre démon, puis exécutez à nouveau `docker compose up -d` dans le premier terminal.

* **Les workers s’exécutent, mais un appel d’outil ne se termine toujours jamais :** La pile démarre 10 workers, et chacun exécute le conteneur d’une seule session à la fois. Une session prend un worker libre lorsque vous la créez, et une session qui ne reçoit jamais de message conserve son worker jusqu’à une heure. Lorsque les 10 sont pris, les appels d’outils de toute autre session attendent un worker. Si la commande `docker ps` de l’étape « Trouver le conteneur de sandbox » liste 10 conteneurs, archivez les sessions que vous n’utilisez pas :

  1. Dans le premier terminal, exécutez `docker ps --filter label=cma-server.sandbox --format '{{.Label "cma-server.session"}}'`. Elle affiche l’ID de la session derrière chaque conteneur. La session en attente n’a pas encore de conteneur : elle ne figure donc pas dans la liste.
  2. Dans le second terminal, appuyez sur Ctrl+C pour quitter la discussion, et exécutez `ant beta:sessions archive --session-id <session-id>` pour chaque session listée que vous n’utilisez pas.
  3. Exécutez à nouveau `ant beta:sessions connect "$SESSION_ID"`. L’appel d’outil se termine lorsqu’un worker prend sa session.

## Étapes suivantes

<CardGroup cols={2}>
  <Card title="Appeler l’API" icon="code-brackets" href="https://platform.claude.com/docs/fr/managed-agents/self-hosted/call-the-api">
    Dirigez le SDK et la CLI `ant` vers votre serveur.
  </Card>

  <Card title="Différences avec le service hébergé" icon="arrows-left-right" href="https://platform.claude.com/docs/fr/managed-agents/self-hosted/differences">
    Vérifiez quelles fonctionnalités se comportent différemment ou ne sont pas disponibles.
  </Card>

  <Card title="Console de votre serveur" icon="browser" href="https://platform.claude.com/docs/fr/managed-agents/self-hosted/console">
    Configurez la connexion, puis créez des agents et exécutez des sessions dans un navigateur.
  </Card>
</CardGroup>