Prérequis
Avant de commencer, assurez-vous de disposer des éléments suivants :- Une organisation Claude Team ou Enterprise dans laquelle un propriétaire a activé les environnements auto-hébergés. Voir les prérequis d’Anthropic.
- Un dépôt GitHub connecté à Claude et accessible depuis votre compte. Commencez par un dépôt de test. Pour connecter GitHub, suivez la documentation de l’application web Claude Code.
- Un jeton d’accès à l’API CoreWeave disposant de l’action de gestion des identités et des accès (IAM)
SANDBOX_USER, ainsi qu’une capacité sans serveur suffisante pour les ressources décrites dans cette section. La recette utilise explicitement l’authentification CoreWeave. - Un ordinateur Linux ou macOS avec Git, Python 3.11 ou version ultérieure, et
uv
Démarrage rapide avec la recette
Créez un environnement Claude, déployez l’orchestrateur, puis vérifiez la sortie d’un worker avant d’arrêter le déploiement.Créer l’environnement Claude
Suivez la procédure de configuration de l’environnement d’Anthropic. Sur la page d’administration Cloud environments, un propriétaire active Allow self-hosted environments et crée un environnement dans la section Self-hosted environments. Un propriétaire crée cet environnement cloud Claude Code dans les paramètres d’administration de claude.ai. Claude Managed Agents utilise un environnement et une clé distincts, créés dans la Claude Console. Conservez la clé de l’environnement et son IDccpool_.... Si vous n’avez pas accès à la page d’administration, demandez à un propriétaire de vous les fournir. L’ID identifie l’environnement, tandis que la clé authentifie l’orchestrateur. Dans les étapes suivantes, la recette déploie l’infrastructure de l’orchestrateur et du worker.
Installer la recette
Installez la recette en local et configurez les identifiants d’authentification dont l’orchestrateur a besoin..env et définissez les deux variables :
Gardez le fichier
.env privé et excluez-le du contrôle de version. Vous pouvez aussi plutôt injecter ces variables depuis un gestionnaire de secrets. Les variables d’environnement existantes prévalent sur le fichier .env.
Déployer l’orchestrateur
Remplacez[ENVIRONMENT-ID] par votre identifiant ccpool_... :
Connected une fois la connexion à Anthropic établie. La configuration peut prendre plusieurs minutes. Un délai d’expiration dépassé ne signifie pas que les ressources ont été nettoyées. Consultez status et logs avant toute nouvelle tentative.
Conservez le fichier local .deployment.json. Il contient les ID et les paramètres nécessaires à la gestion du déploiement, mais aucun identifiant d’authentification. Exécutez les commandes suivantes depuis le répertoire de la recette.
Envoyer une tâche
Dans l’application web Claude Code, sélectionnez votre organisation, votre dépôt connecté et votre environnement auto-hébergé. Pour créer le fichier utilisé lors de l’étape de vérification, envoyez exactement le prompt suivant :Vérifier le résultat
Depuis votre terminal, listez le déploiement :Connected: True ainsi qu’une ligne Worker: contenant un ID de sandbox. Une fois que Claude a terminé, remplacez [WORKER-ID] par cet ID dans la commande suivante :
CWS_CLOUD_OK. Cette vérification lit le fichier de la sandbox via le SDK Sandboxes, indépendamment de la réponse de Claude. Lisez-le avant que le worker ne passe à l’état inactif et ne s’arrête. Si vous avez envoyé une autre tâche, lisez plutôt un fichier créé par celle-ci.
Nettoyage
Après avoir enregistré vos résultats, arrêtez le déploiement :.deployment.json. Elle interrompt les tâches en cours et supprime définitivement les fichiers stockés uniquement dans ces sandboxes. L’environnement Claude reste disponible pour un déploiement ultérieur.
Fonctionnement de l’intégration
La recette déploie deux rôles :
Le worker passe par le proxy git Anthropic pour accéder au dépôt. La recette ne copie dans le worker ni votre connexion Claude locale ni votre jeton GitHub. Les requêtes au modèle, les prompts, les réponses et les résultats d’outils transitent néanmoins toujours par Anthropic.
Le hook respecte le contrat d’exécuteur à la demande d’Anthropic : il soumet la charge de travail de manière asynchrone et l’enregistre à l’aide d’un ordre de travail à usage unique. La recette consigne les ID d’ordre sur le disque de l’orchestrateur afin d’éviter les soumissions en double si le processus de l’orchestrateur redémarre. En cas d’incertitude sur une création, celle-ci échoue de manière sécurisée (fail closed) et doit être vérifiée avant toute nouvelle tentative.
Les workers s’exécutent dans un encapsuleur de processus qui enregistre le code de sortie et termine la sandbox sans relancer le processus. En cas d’échec au démarrage, consultez les journaux. L’achèvement de la sandbox ne garantit pas à lui seul la réussite de la tâche.
La recette fixe Claude Code à la version
2.1.284 et le SDK Sandboxes à la version 1.14.2. Chaque sandbox démarre à partir de python:3.12-bookworm et installe Git et Claude lors de l’amorçage. Le démarrage d’un worker comprend l’ordonnancement, l’installation, l’enregistrement et l’extraction du dépôt.
Configurer le déploiement
Définissez les options lorsque vous exécutezdeploy :
Les deux options de durée de vie acceptent une valeur comprise entre 1 et 720 heures. Le délai d’expiration d’inactivité ne doit pas dépasser 10 080 minutes (7 jours) et doit être inférieur à la durée de vie du worker moins 5 minutes. Pour un orchestrateur de 30 jours, ajoutez
--orchestrator-hours 720 lors du déploiement. Les durées de vie ne peuvent pas être prolongées après la création.
N’exécutez qu’un seul déploiement de la recette par environnement Claude. La recette ne remplace pas automatiquement les sandboxes de l’orchestrateur. Son superviseur redémarre le processus de l’orchestrateur Claude Code dans la même sandbox, ce qui préserve le registre local des ordres. Si la sandbox échoue ou expire, ce registre est perdu. Surveillez le déploiement, enregistrez les résultats des sessions et prévoyez le remplacement avant l’expiration. Pour un remplacement planifié, terminez le travail en cours, exécutez stop, puis redéployez. Avant toute reprise après une soumission incertaine ou une défaillance de l’hôte, inspectez les sessions en attente et les ressources existantes.
Pour ajouter une chaîne d’outils, modifiez la branche worker dans le script bootstrap.sh de la recette, puis testez-la avec votre dépôt. Pour les hooks de cycle de vie et la configuration des sessions, consultez Personnaliser les sessions dans les environnements auto-hébergés.
Surveiller les sessions
Inspectez la connexion, les workers et les journaux récents :status indique l’état de la connexion de l’orchestrateur et son heure d’expiration approximative. Une fois que toutes les sessions sont inactives et que le délai d’expiration d’inactivité est écoulé, le nombre de workers devrait tomber à zéro si aucune nouvelle session n’est mise en file d’attente. Lorsque de la capacité est disponible, toute nouvelle session crée un worker. Les messages de suivi peuvent continuer sur le worker actuel tant qu’il reste associé.
L’écouteur d’état de santé de l’orchestrateur reste confiné à sa sandbox. Ces commandes utilisent le SDK Sandboxes et ne nécessitent aucun point de terminaison public.
Pour afficher la sortie d’installation d’un worker, ajoutez --bootstrap à sa commande de journal. Ce journal contient également la sortie de l’exécuteur Anthropic une fois la configuration terminée.
Enregistrer les résultats avant l’arrêt d’un worker
L’exécuteur Anthropic libère les sessions inactives, puis s’arrête. Il commence également à se retirer 5 minutes avant la fin de la durée de vie de son sandbox. Un tour de conversation de longue durée peut toutefois atteindre la limite stricte de durée de vie et être interrompu. Demandez à Claude de commiter et de téléverser (push) le travail que vous souhaitez conserver, puis vérifiez la branche dans GitHub. Pour un artifact texte, utilisez la commanderead de la recette et redirigez sa sortie vers un fichier local. La recette ne configure aucun push ni instantané automatique. Une requête ultérieure envoyée après la libération peut s’exécuter dans un nouveau worker : ne comptez donc pas sur la conservation des fichiers non téléversés.
Pour connaître les options de persistance dans d’autres flux de travail, consultez Instantanés du système de fichiers. Pour en savoir plus sur le comportement de libération de l’exécuteur Anthropic, consultez la référence de l’exécuteur d’Anthropic.
Dépannage
Si vous restreignez le trafic sortant, tenez compte à la fois du trafic de l’exécuteur Anthropic et des téléchargements d’amorçage depuis Debian, PyPI et les services de téléchargement de Claude. Cette recette ne configure pas de liste d’autorisation pour le trafic sortant. Pour connaître les exigences réseau et les mesures de renforcement de la sécurité, consultez les recommandations d’Anthropic pour le déploiement en production.
Étapes suivantes
Utilisez les ressources suivantes pour valider vos modifications ou découvrir d’autres intégrations :- Après avoir modifié la recette, exécutez ses vérifications hors ligne et en direct.
- Utilisez les tests de bout en bout d’Anthropic pour obtenir des diagnostics supplémentaires.
- Découvrez d’autres intégrations d’agents.