Démarrer avec Claude Managed Agents auto-hébergé

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.

Pour la production, Anthropic recommande les deux charts Helm de la version. Consultez Déployer sur Kubernetes.

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.
• Docker : La dernière version de Docker Engine 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.

Démarrer la pile

1. 1

   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.

   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.

2. 2

   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 :

   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.

3. 3

   Démarrer les conteneurs

   Construisez et démarrez la pile, puis suivez le journal du serveur :

   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.

4. 4

   Vérifier que le serveur est prêt

   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.

Exécuter votre première session

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

1. 1

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

   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.

2. 2

   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.

   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.

   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.

3. 3

   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.

   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

   Demander à l’agent d’exécuter une commande

   Connectez votre terminal à la session :

   ant beta:sessions connect "$SESSION_ID"

   

   La commande ouvre une vue de discussion de la session. Envoyez ce message :

   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.

5. 5

   Trouver le conteneur de sandbox

   Laissez la discussion ouverte. Dans le premier terminal, listez les conteneurs de sandbox :

   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.

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.

1. 1

   Redémarrer la pile avec le fournisseur de connexion fictif

   Exécutez ces commandes dans le premier terminal :

   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.

2. 2

   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.

Pour créer également des agents et démarrer des sessions dans la console, consultez Exécuter un agent depuis la console.

Arrêter la pile

Dans le premier terminal, exécutez cette commande :

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é.
• 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