Le plan de contrôle était l’élément qui brisait l’entente. Beaucoup d’entreprises voulaient des agents Claude qui travaillent sur du code interne pendant des heures d’affilée, et autant refusaient de laisser un fournisseur garder le registre des sessions, les identifiants et la boucle de l’agent pendant que ce travail fonctionnait. Claude Managed Agents auto hébergé, ouvert en bêta privée le 12 novembre, est la réponse d’Anthropic à ce refus. Vous faites fonctionner le service. Claude lui même fonctionne encore chez un fournisseur que vous choisissez.
Cette division façonne chaque étape ci dessous. Notre reportage sur le lancement a couvert ce qui a déménagé à l’interne et ce qui ne l’a pas fait. Ce tutoriel fait l’installation dans l’ordre que la documentation Anthropic établit, et il signale les limites avant que vous passiez un après midi sur une installation que votre charge de travail ne peut pas utiliser.
Ce que vous allez construire ou apprendre
Vous terminerez avec une pile de développement qui fonctionne sur une machine et une session d’agent qui a exécuté une commande shell dans son propre conteneur bac à sable. La pile a trois parties que vous exploitez. Le serveur, nommé cma-server, sert l’API Managed Agents, fait fonctionner la boucle de l’agent et range les agents, les sessions et l’historique des sessions. Les travailleurs prennent du travail du serveur et exécutent les outils shell et de fichiers dans vos bacs à sable. Le serveur lui même n’exécute jamais ces outils.
Vous apprendrez aussi où la frontière se trouve vraiment. Pour chaque appel de modèle, le serveur envoie la conversation jusqu’ici, entrées d’outils et résultats d’outils compris, à votre fournisseur d’inférence. Anthropic dit qu’il n’a aucun accès distant à votre serveur ni à ses journaux. Le registre et les clés restent à la maison. Les invites voyagent quand même, et l’étape 9 est l’endroit où vous décidez où elles voyagent.
Avant de commencer
Lisez d’abord les trous, parce qu’ils sont du genre qui termine les projets poliment en deuxième semaine. Rien ne se copie depuis le service hébergé, historique de sessions compris. Vous recréez les agents, les compétences, les identifiants de voûte et les magasins de mémoire sur votre propre serveur. Seuls les environnements self_hosted existent, et une demande pour un environnement infonuagique retourne une erreur 400. Le serveur ne sert ni l’API Messages ni l’API Models, et les appels à /v1/messages et /v1/models retournent 404.
La liste des manques est plus longue. Les ressources de session de fichiers et l’API Files n’existent pas, même si les ressources memory_store fonctionnent. Le serveur rejette les identifiants de voûte mcp_oauth, parce qu’il n’a aucun flux OAuth pour rafraîchir un jeton, alors vous rangez les jetons comme des identifiants static_bearer et vous les faites tourner vous même. Il rejette les agents qui déclarent les compétences préconstruites docx, pdf, pptx et xlsx, alors vous téléversez ces compétences comme des compétences personnalisées à la place. Les déploiements planifiés, les rêves et les webhooks n’ont aucune voie du tout. La recherche Web et la récupération Web commencent éteintes, et ce que vous pouvez allumer dépend du fournisseur que vous choisissez à l’étape 9.
Une note de portée sur l’honnêteté. L’accès à cette bêta est contrôlé, alors ce tutoriel a été vérifié ligne par ligne par rapport à la documentation Anthropic et n’a pas été exécuté sur une machine de test. Chaque commande ci dessous vient du démarrage rapide, de la page du fournisseur d’inférence ou de la page des différences, toutes nommées dans Sources. Là où la documentation montre une valeur secrète, ce tutoriel montre un espace réservé.
Trois identifiants font fonctionner toute l’installation, et les mélanger cause la plupart de la confusion précoce :
| Identifiant | Qui le détient | Ce qu’il fait |
|---|---|---|
| Clé API du serveur | Vos applications, le CLI ant et le CLI administrateur | Authentifie les demandes à votre serveur. L’installation la génère. Elle joue le rôle qu’une clé API Claude joue avec le service hébergé |
| Identifiant d’inférence | Le serveur seulement | Authentifie les appels de modèle du serveur à votre fournisseur, comme une clé API Claude ou un identifiant infonuagique |
| Clé d’environnement | Vos travailleurs | Permet à un travailleur de sonder une file de travail d’environnement et d’atteindre les sessions de cet environnement |
Étape 1 : obtenir l’archive et la déballer
Action : contactez votre équipe de compte Anthropic et demandez l’accès à Claude Managed Agents auto hébergé. Il n’existe aucun téléchargement public et aucune inscription libre dans la documentation. Quand l’équipe envoie l’archive de version, déballez la et travaillez depuis son répertoire compose. Remplacez <archive> par le nom de l’archive, sans .tar.gz.
tar -xzf <archive>.tar.gz && cd <archive>/compose
Résultat attendu : vous êtes dans le répertoire compose, à côté de docker-compose.yml. Si votre umask est plus strict que 022, les binaires perdent la permission d’exécution pour les autres utilisateurs et le conteneur du serveur ne peut pas les démarrer. Dans ce cas, réglez l’umask à 022 et déballez l’archive de nouveau. Chaque archive de version livre aussi un fichier operator-guide.md. La documentation suggère de faire lire ce fichier par Claude, pour que Claude puisse vous aider à configurer le serveur pour cette version exacte.
Étape 2 : créer le fichier .env
Action : créez le fichier .env à côté de docker-compose.yml, avec le bloc du démarrage rapide. Compose lit les secrets de la pile depuis ce fichier. Le bloc règle quatre valeurs. Deux sont des mots de passe et des clés générés pour la pile elle même, une est la clé qui chiffre les secrets rangés du serveur et une est votre clé API Claude, que vous ajoutez à la main.
CMA_PG_PASSWORD=<generated value from the quickstart block>
ANTHROPIC_API_KEY=sk-ant-...
CMA_SERVER__API_KEY=<generated value from the quickstart block>
CMA_STORE__CREDENTIALS_ENCRYPTION_KEY=$(openssl rand -base64 32)
chmod 600 .env
Résultat attendu : le fichier existe avec des permissions serrées, l’espace réservé sk-ant-... garde maintenant votre vraie clé API Claude, et les trois autres valeurs gardent les valeurs générées du bloc de démarrage rapide. Ouvrez le fichier dans un éditeur pour faire ce seul remplacement, et n’affichez pas le fichier dans un journal de terminal partagé ensuite.
Étape 3 : démarrer la pile
Action : construisez et démarrez la pile, puis suivez le journal du serveur. Restez dans ce terminal pour chaque commande docker compose dans tout le tutoriel. La raison de cette discipline arrive à l’étape 5.
docker compose up --build -d
docker compose logs -f cma-server
Résultat attendu : le journal montre une ligne avec msg="cma-server listening". Appuyez sur Ctrl+C pour arrêter de suivre le journal. La pile fait maintenant fonctionner le serveur, sa base de données PostgreSQL et un ensemble de travailleurs, avec un conteneur bac à sable par session une fois que les sessions commencent.
Étape 4 : vérifier que le serveur est prêt
Action : demandez au serveur son état de préparation.
curl -s http://127.0.0.1:8400/cma-server/readyz
Résultat attendu : un serveur prêt répond avec "status":"ready". Juste après un démarrage, il peut répondre "status":"degraded" pendant quelques secondes pendant que ses premières vérifications fonctionnent. S’il reste dégradé, ou répond "status":"not_ready", allez au Dépannage avant de créer quoi que ce soit.
Étape 5 : pointer le CLI vers votre serveur
Action : ouvrez un deuxième terminal dans le même répertoire et gardez le pour le travail ant. Réglez l’URL de base à votre serveur, et réglez la clé API à votre clé API de serveur tirée du fichier .env. Cette valeur n’est pas votre clé API Claude, et la documentation consacre une page entière à cette distinction.
export ANTHROPIC_BASE_URL=http://127.0.0.1:8400
export ANTHROPIC_API_KEY=<your server API key from .env>
Résultat attendu : les commandes ant dans ce terminal parlent maintenant à votre serveur au lieu du service hébergé. Gardez les ici. Si vous lancez docker compose up dans ce terminal, Compose passe ces variables au serveur, et le serveur s’appelle lui même au lieu de l’API Claude. Ce seul mélange explique une grande part des premiers lancements ratés.
Étape 6 : créer un agent
Action : enregistrez un fichier nommé quickstart-agent.md avec le contenu ci dessous, puis appliquez le. Le fichier donne à l’agent l’ensemble d’outils intégré et le laisse exécuter ces outils sans vous demander d’abord. Le nom du modèle est un identifiant API Claude, et il reste valide même si vous changez de fournisseur à l’étape 9, parce que le serveur traduit l’identifiant pour le fournisseur qui sert ce modèle.
---
name: Quickstart agent
model: claude-opus-5-5
tools:
- type: agent_toolset_20260401
---
You are a helpful assistant.
ant apply --yes quickstart-agent.md
Résultat attendu : la commande affiche d’abord un avertissement qu’elle could not determine the organization and workspace, avec une erreur 404, puis crée l’agent. La documentation dit que cet avertissement est attendu sur votre propre serveur. Ne courez pas après.
Étape 7 : démarrer une session
Action : trouvez l’agent et l’environnement de la pile, puis démarrez une session et gardez son identifiant. La pile Compose 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)
Résultat attendu : SESSION_ID garde une valeur, et la session existe sur votre serveur, dans votre base de données, sans copie sur le service hébergé. Une session prend un travailleur libre quand vous la créez, et la pile démarre dix travailleurs. Une session qui ne reçoit jamais de message peut garder son travailleur jusqu’à une heure, un fait qui compte dans le Dépannage.
Étape 8 : demander à l’agent d’exécuter une commande
Action : connectez votre terminal à la session, puis envoyez le message exact ci dessous.
ant beta:sessions connect "$SESSION_ID"
Run `hostname` with the bash tool and tell me the output.
Résultat attendu : l’agent répond avec un nom d’hôte qui commence par cma-sandbox-. Ce nom est le conteneur bac à sable qui a exécuté la commande, ce qui confirme que l’outil a fonctionné dans un bac à sable et non sur votre machine. Laissez le clavardage ouvert, retournez au terminal un et listez les conteneurs bacs à sable pour voir le même nom dans la sortie Docker.
docker ps --filter label=cma-server.sandbox
Le conteneur sort environ une minute après la fin d’un tour, et le prochain message en démarre un nouveau. Si la liste est vide, demandez à l’agent d’exécuter hostname de nouveau et listez les conteneurs pendant qu’il répond. Pour quitter le clavardage, appuyez sur Ctrl+C dans son terminal. La session continue de fonctionner sans vous.
Une chambre par session, une tour au dessus de toutes. Le serveur dirige le travail, et les travailleurs exécutent les outils. Illustration : Dirty Static
Étape 9 : choisir où les appels de modèle vont
Action : décidez le fournisseur d’inférence maintenant, pendant que l’installation est encore petite. Le réglage inference.provider dans le fichier de réglages du serveur prend cinq valeurs. anthropic est le défaut et envoie les appels à l’API Claude. bedrock les envoie à Amazon Bedrock. vertex les envoie à Claude Models sur Google Cloud. foundry les envoie à Microsoft Foundry. gateway les envoie à une passerelle de modèle que vous faites fonctionner vous même. Sous chaque valeur sauf anthropic, le serveur n’a besoin d’aucune clé API Claude.
Cet échantillon achemine les appels vers Bedrock. Mettez le dans le fichier de réglages du serveur, donnez au serveur l’identifiant du fournisseur comme la page du fournisseur d’inférence le décrit pour votre installation et redémarrez le serveur. Sur Compose, si vous avez changé .env ou docker-compose.yml pour passer cet identifiant, lancez docker compose up -d à la place, parce qu’un redémarrage simple ne relit pas ces fichiers.
inference:
provider: bedrock
region: us-east-1
#model_id_prefix: global.anthropic.
#model_id_overrides:
# claude-opus-5-5: us.anthropic.claude-opus-5-5
Résultat attendu : le serveur signe ses appels avec tout ce que la chaîne d’identifiants par défaut du SDK AWS trouve sur l’hôte, et il préfixe chaque identifiant de modèle avec us.anthropic. par défaut, ce qui nomme un profil d’inférence entre régions. L’identité AWS avec laquelle le serveur signe a besoin de bedrock:InvokeModel et de bedrock:InvokeModelWithResponseStream sur les modèles et les profils que vous utilisez, plus bedrock:ListFoundationModels et bedrock:ListInferenceProfiles sur la ressource *. Démarrez une nouvelle session après le redémarrage et confirmez que l’agent répond encore. Notre examen de recherche de la bêta pèse ce choix de fournisseur au complet, parce que c’est la décision qui décide ce que le mot privé signifie dans votre déploiement.
Vérification
Faites ces vérifications avant de déclarer l’installation terminée :
- L’appel de préparation à l’étape 4 répond
"status":"ready". - L’agent à l’étape 8 signale un nom d’hôte qui commence par
cma-sandbox-, etdocker psdans le terminal un montre ce conteneur pendant que le tour fonctionne. - La session et son historique vivent sur votre serveur. Arrêtez la pile depuis le terminal un avec la commande ci dessous, démarrez la de nouveau et confirmez que le registre de la session a survécu, parce que la base de données le garde.
docker compose down --remove-orphans
docker compose up -d
Cette commande d’arrêt supprime les conteneurs et garde la base de données. Ajoutez -v à elle seulement quand vous voulez que la base de données, avec chaque agent, session et historique de session dedans, soit supprimée aussi. C’est un choix destructeur, alors traitez le comme tel.
- Si vous avez changé le fournisseur à l’étape 9, une nouvelle session répond après le redémarrage, et votre console de fournisseur ou votre journal de passerelle montre l’appel de modèle qui arrive sur la voie que vous avez choisie.
Avant de l’appeler production
La pile Compose prouve la forme. Elle ne la durcit pas. Pour la production, Anthropic recommande les deux graphiques Helm dans l’archive de version, nommés cma-server et cma-sandboxes, sur un cluster Kubernetes en version 1.30 ou plus récente. Cette voie a besoin du contrôleur Agent Sandbox, de nœuds qui font fonctionner gVisor, d’un module réseau qui applique NetworkPolicy, d’une base de données PostgreSQL 16 ou plus récente hors des deux graphiques, d’un registre duquel le cluster peut tirer et de droits d’administrateur de cluster pour l’installation.
Le serveur parle aussi du HTTP simple sur le port 8400 sur cette voie, alors TLS appartient devant lui avant que tout client hors du cluster se connecte. La page Kubernetes établit les conditions pour cette porte d’entrée. Les chemins passent inchangés, les corps de demande jusqu’à 32 MiB passent, les réponses passent sans tampon, et le mandataire ne renvoie jamais un POST et ne met jamais une réponse en cache. Lisez cette page au complet avant d’installer quoi que ce soit, et traitez un déploiement par niveau de confiance comme la règle. La documentation est nette sur ce point, parce que la clé API du serveur atteint chaque environnement dans un déploiement.
Dépannage
| Problème | Cause probable | Correctif |
|---|---|---|
Votre archive n’a aucun répertoire compose | L’archive garde une version plus vieille, et les commandes de démarrage rapide ne lui correspondent pas | Demandez la version actuelle à votre équipe de compte Anthropic. Pour un déploiement en marche, suivez la page de mise à niveau dans la documentation |
| Le serveur ne se lève jamais | Le conteneur unique migrate a échoué, alors les tables de la base de données n’ont jamais été créées | Lancez docker compose logs migrate. Il doit sortir avec le statut 0 avant que le serveur démarre |
La préparation reste degraded, ou chaque tour échoue | Vous avez lancé docker compose up dans le terminal où ANTHROPIC_BASE_URL pointe vers votre propre serveur, alors le serveur s’appelle lui même | Lancez docker compose up -d de nouveau dans le terminal un, où cette variable n’est pas réglée. Lisez ensuite le journal du serveur avec docker compose logs -f cma-server |
La préparation répond not_ready et la vérification ratée est upstream | L’API Claude a rejeté votre clé API Claude | Corrigez ANTHROPIC_API_KEY dans .env, lancez unset ANTHROPIC_API_KEY dans le shell s’il règle sa propre valeur, puis lancez docker compose up -d de nouveau dans le terminal un |
La préparation répond not_ready et la vérification ratée est database | La base de données a rejeté la connexion du serveur, ou une connexion à la base de données s’est brisée | Lisez le journal du serveur avec docker compose logs -f cma-server pour voir laquelle des deux c’était, puis corrigez le mot de passe ou la connexion |
| L’agent répond, mais son appel d’outil ne se termine jamais | Aucun travailleur ne sonde l’environnement, ou un travailleur ne peut pas atteindre la prise du démon Docker | Vérifiez les travailleurs avec docker compose logs sandbox. Si le journal nomme CMA_DOCKER_SOCKET, réglez cette variable dans .env à votre chemin de prise de démon, puis lancez docker compose up -d de nouveau dans le terminal un |
| Les travailleurs fonctionnent, mais un appel d’outil attend encore | Les dix travailleurs sont pris par des sessions qui n’ont jamais reçu de message, et chacune garde son travailleur jusqu’à une heure | Listez les sessions derrière les conteneurs avec docker ps --filter label=cma-server.sandbox --format '{{.Label "cma-server.session"}}', quittez le clavardage avec Ctrl+C et archivez chaque session inutilisée avec ant beta:sessions archive --session-id <session-id> dans le terminal deux. Connectez vous ensuite à votre session de nouveau |
| Un agent qui fonctionnait sur le service hébergé échoue ici | Il utilise une fonction que le serveur auto hébergé n’a pas, comme un environnement infonuagique, une ressource de fichier ou une compétence de document préconstruite | Lisez la page des différences dans Sources et reconstruisez cette partie à la façon auto hébergée. Rien ne migre, alors attendez vous à du travail de reconstruction, pas à du travail d’importation |
Prochaines étapes
Prenez ensuite la lecture de production. Parcourez la page Deploy on Kubernetes dans la documentation avec votre équipe de plateforme, et évaluez le vrai coût de propriété pendant que vous lisez. Vous installez chaque version vous même, vous sauvegardez une base de données qui garde chaque conversation, et la licence du serveur, dans la couverture du lancement de son texte, vous donne huit heures pour reculer après un avis de sécurité et un jour ouvrable pour appliquer une mise à jour de sécurité. Le contrôle est le produit ici, et les opérations sont son prix.
Faites ensuite un vrai travail borné avant d’élargir quoi que ce soit. Choisissez une tâche d’arriéré avec un résultat que vous pouvez vérifier à la main, regardez le registre de session qu’elle laisse derrière et testez les modes d’échec exprès. Redémarrez le serveur et confirmez que l’historique a survécu. Révoquez un identifiant et confirmez que l’agent échoue d’une façon sûre. Pointez l’agent vers un hôte que vous n’avez jamais listé et confirmez que le bac à sable ne peut pas l’atteindre. Un agent que vous avez regardé bien échouer est un agent auquel vous pouvez commencer à faire confiance pour du travail qui compte.
Faits, commandes et réglages vérifiés par rapport à la documentation Anthropic le 13 novembre 2026. La disponibilité est en bêta privée et peut changer. Cette procédure a été vérifiée par rapport à ces documents et n’a pas été présentée comme un essai personnel, parce que l’accès à la version passe par une équipe de compte Anthropic.
Sources
- Anthropic Docs, Self hosted Claude Managed Agents, overview, credentials and what runs where: https://platform.claude.com/docs/en/managed-agents/self-hosted
- Anthropic Docs, Get started with self hosted Claude Managed Agents, the Compose quickstart this tutorial follows: https://platform.claude.com/docs/en/managed-agents/self-hosted/quickstart
- Anthropic Docs, Differences from the hosted service: https://platform.claude.com/docs/en/managed-agents/self-hosted/differences
- Anthropic Docs, Inference provider: https://platform.claude.com/docs/en/managed-agents/self-hosted/inference-provider
- Anthropic Docs, Deploy on Kubernetes: https://platform.claude.com/docs/en/managed-agents/self-hosted/kubernetes
- Anthropic, Claude Platform release notes, November 12, 2026 launch entry: https://platform.claude.com/docs/en/release-notes/overview
- Anthropic, Operate Claude Managed Agents inside your security perimeter, November 12, 2026: https://claude.com/resources/articles/self-hosted-claude-managed-agents
- Diagram: Anthropic, from the self hosted announcement and docs
- Hero and sandbox chamber illustrations: Dirty Static
FIN DE LA TRANSMISSION
Restez curieux. Remettez tout en question.
