> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Exécuter des sessions cloud Claude Code
> Déployez un orchestrateur Claude Code qui crée une sandbox CoreWeave pour chaque session cloud.
Exécutez des sessions cloud Claude Code sur des sandboxes CoreWeave. Confiez une tâche à Claude dans l’[application web Claude Code](https://claude.ai/code) (claude.ai/code) : un orchestrateur hébergé dans une sandbox provisionne alors une sandbox worker pour la session. Une fois le déploiement effectué, votre ordinateur local peut se déconnecter.
Ce guide s’appuie sur les [environnements auto-hébergés](https://code.claude.com/docs/en/self-hosted-environments) d’Anthropic et sur une [recette exécutable](https://github.com/coreweave/cwsandbox-recipes/tree/main/recipes/claude-code-cloud). La recette utilise directement le kit de développement logiciel (SDK) Sandboxes. Pour un terminal interactif ou Remote Control, consultez [Claude Code](/fr/products/sandboxes/agents/claude-code). Pour des boucles d’agent gérées par API, consultez [Claude Managed Agents](/fr/products/sandboxes/agents/claude-managed-agents).
Dans cette recette, un *exécuteur* Anthropic exécute une session cloud Claude Code. Un *worker* désigne la sandbox qui l’héberge. Les exécuteurs Anthropic sont distincts des [exécuteurs gérés CoreWeave](/fr/products/sandboxes/operations/managed-runners), qui exécutent des sandboxes dans des clusters CoreWeave Kubernetes Service (CKS).
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](https://code.claude.com/docs/en/self-hosted-environments-quickstart#prerequisites).
* 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](https://code.claude.com/docs/en/claude-code-on-the-web).
* Un [jeton d’accès à l’API CoreWeave](/fr/products/sandboxes/placement#coreweave-api-access-token) 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`](https://docs.astral.sh/uv/getting-started/installation/)
La recette ne nécessite pas de GPU. Elle demande 1 CPU et 2 Gio de mémoire pour l’orchestrateur, plus 2 CPU et 4 Gio pour chaque worker. Par défaut, elle autorise jusqu’à quatre workers actifs.
L’orchestrateur reste facturé même lorsqu’il est inactif, et l’utilisation de Claude est facturée séparément. Pour estimer votre budget, sachez que 24 heures d’orchestration seule représentent 24 heures-CPU et 48 Gio-heures. Ajoutez-y le temps d’exécution des workers sur la base de leurs demandes de ressources, puis appliquez les tarifs de votre compte.
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](https://code.claude.com/docs/en/self-hosted-environments-quickstart). 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 ID `ccpool_...`. 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.
```bash theme={"system"}
git clone https://github.com/coreweave/cwsandbox-recipes.git
cd cwsandbox-recipes/recipes/claude-code-cloud
uv sync --locked
cp .env.example .env
chmod 600 .env
```
Modifiez le fichier `.env` et définissez les deux variables :
| Variable | Valeur |
| - | - |
| `CWSANDBOX_API_KEY` | Votre jeton d’accès à l’API CoreWeave. |
| `SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET` | La clé d’environnement fournie par Claude. |
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_...` :
```bash theme={"system"}
uv run cloud.py deploy --environment '[ENVIRONMENT-ID]'
```
La commande affiche l’ID de la sandbox de l’orchestrateur, attend la fin de la configuration, puis affiche `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 :
```text theme={"system"}
Use Bash to write exactly CWS_CLOUD_OK followed by a newline to
/tmp/claude-cloud-proof.txt, then read it back and report the current
directory. Do not modify repository files, commit, or push.
```
L’envoi de la tâche met une session en file d’attente et déclenche la création d’un worker.
Vérifier le résultat
Depuis votre terminal, listez le déploiement :
```bash theme={"system"}
uv run cloud.py status
```
Vous devriez obtenir `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 :
```bash theme={"system"}
uv run cloud.py read --worker '[WORKER-ID]' --path /tmp/claude-cloud-proof.txt
```
La sortie attendue est `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 :
```bash theme={"system"}
uv run cloud.py stop
```
La commande arrête l’orchestrateur ainsi que ses workers, vérifie qu’aucun ne reste actif et supprime le fichier `.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
```mermaid theme={"system"}
flowchart LR
U[Session de l’application web Claude Code] --> A[Plan de contrôle Anthropic]
O[Sandbox d’orchestration] -->|Interroger les files pour récupérer les tâches| A
O -->|SDK Sandbox| W[Sandbox de worker par session]
W -->|Requêtes de session et de modèle| A
```
La recette déploie deux rôles :
| Rôle | Responsabilité | Identifiants d’authentification fournis par la recette |
| - | - | - |
| Orchestrateur | Interroger Anthropic et soumettre des workers via un hook `spawn-runner`. | Jeton d’accès à l’API CoreWeave et clé d’environnement Claude. |
| Worker | Exécuter une session Claude Code, ses outils et l’extraction de son dépôt. | Un ordre de travail à usage unique émis pour l’exécuteur Anthropic. |
Le worker passe par le [proxy git Anthropic](https://code.claude.com/docs/en/self-hosted-environments-deploy#use-the-anthropic-git-proxy) 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](https://code.claude.com/docs/en/self-hosted-environments-configuration#on-demand-runners) : 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.
Définissez les options lorsque vous exécutez `deploy` :
| Option | Par défaut | Objectif |
| - | - | - |
| `--orchestrator-hours` | `24` | Durée de vie maximale stricte de l’orchestrateur, temps de configuration et d’inactivité compris. |
| `--worker-hours` | `8` | Durée de vie maximale stricte de chaque worker. |
| `--idle-minutes` | `15` | Libère les sessions après une période d’inactivité de l’utilisateur, lorsque l’exécuteur Anthropic les considère comme inactives. |
| `--max-workers` | `4` | Limite le nombre de workers actifs créés par ce déploiement. |
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](https://code.claude.com/docs/en/self-hosted-environments-configuration).
Surveiller les sessions
Inspectez la connexion, les workers et les journaux récents :
```bash theme={"system"}
uv run cloud.py status
uv run cloud.py logs
uv run cloud.py logs --bootstrap
uv run cloud.py logs --worker '[WORKER-ID]'
```
`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 commande `read` 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](/fr/products/sandboxes/file-system-snapshots). 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](https://code.claude.com/docs/en/self-hosted-environments-reference).
Dépannage
| Symptôme | Action |
| - | - |
| Les paramètres d’auto-hébergement sont absents | Sélectionnez l’organisation Team ou Enterprise et demandez à son propriétaire d’activer la fonctionnalité. |
| Un dépôt est absent ou l’extraction (checkout) échoue | Vérifiez la connexion GitHub et l’accès au dépôt dans l’organisation Claude sélectionnée. |
| En attente d’un exécuteur | Vérifiez que vous avez bien envoyé une tâche, exécutez `status` et examinez les journaux de l’orchestrateur. Contrôlez l’association entre l’ID et la clé de l’environnement, ainsi que votre [quota de sandboxes simultanées](/fr/products/sandboxes/reference/limits-and-quotas#concurrent-sandbox-quota). |
| Le démarrage du worker est lent | Consultez son journal d’amorçage pour distinguer les délais liés à l’ordonnancement et à l’installation des paquets des échecs de l’exécuteur Anthropic ou de l’extraction. |
| Limite de workers atteinte | Terminez ou libérez une session existante. Pour modifier la limite, enregistrez votre travail, arrêtez le déploiement, puis redéployez. |
| La soumission du worker est incertaine | Examinez les ressources actives et l’onglet **Activity** de l’environnement. Un propriétaire peut relancer la session en échec une fois la réconciliation effectuée. |
| Un enregistrement de déploiement existe déjà | Examinez le déploiement enregistré avec `status`. Enregistrez les résultats et utilisez `stop` avant de redéployer. |
| Un fichier est illisible | Vérifiez son chemin et l’ID du worker tant que celui-ci est actif. Les fichiers ne sont plus disponibles une fois le worker arrêté. |
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](https://code.claude.com/docs/en/self-hosted-environments-deploy).
É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](https://github.com/coreweave/cwsandbox-recipes/tree/main/recipes/claude-code-cloud#validate-changes).
* Utilisez les [tests de bout en bout d’Anthropic](https://code.claude.com/docs/en/self-hosted-environments-testing) pour obtenir des diagnostics supplémentaires.
* Découvrez [d’autres intégrations d’agents](/fr/products/sandboxes/agents).