> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Orchestration

> Provisionnez des machines et lancez automatiquement des workers à mesure que les sessions entrent dans la file d’attente

Un orchestrateur surveille l’API Outposts pour détecter les sessions en attente sur un outpost, provisionne une VM ou un conteneur pour chacune d’elles, puis y démarre le worker. Cette page décrit la boucle d’orchestration : interrogation périodique de la file d’attente, prise en charge des sessions, exécution des workers et suppression des machines.

Si vous voulez simplement exécuter des sessions sur une machine dont vous disposez déjà, commencez par le [quickstart](/fr/cloud/outposts/quickstart) — aucun orchestrateur n’est nécessaire. Si vous utilisez une plateforme prise en charge, une [intégration](/fr/cloud/outposts/overview#integrations) implémente peut-être déjà cette boucle pour vous. Pour la référence complète de l’API et de la CLI, consultez la [reference](/fr/cloud/outposts/reference).

<Note>
  Vous utilisez Kubernetes ? [devin-outpost-k8s](https://github.com/CognitionAI/devin-outpost-k8s)
  est un opérateur open source qui implémente cette boucle pour vous : il surveille la
  file d’attente, prend en charge les sessions en attente et exécute chacune d’elles sous forme de pod worker sur n’importe quel
  cluster certifié (GKE, EKS, ...). Installez-le avec son chart Helm au lieu de
  créer votre propre orchestrateur.
</Note>

<div id="the-core-flow">
  ## Le flux de travail principal
</div>

<div id="1-register-an-outpost">
  ### 1. Enregistrer un outpost
</div>

Un outpost est une file d’attente de sessions identifiée par un nom, gérée par de nombreux workers sur votre infrastructure (par exemple, `rhel`, `gpu-h200` ou `my-outpost`). Créez-le avec `devin worker outpost create`:

```bash theme={null}
devin worker outpost create <name> --platform <platform> --description "..."
```

Une fois enregistré, l’outpost apparaît parmi les options de machine dans Devin Cloud (aux côtés d’Ubuntu, Windows, etc.) au démarrage d’une session. Les sessions qui le ciblent attendent dans sa file d’attente jusqu’à ce qu’un worker les prenne en charge.

<Note>
  Dans la fleet API, les outposts sont représentés par des ressources `outposts`, dans le périmètre de
  votre compte (partagées entre toutes ses organisations). Consultez les
  [endpoints des outposts](/fr/cloud/outposts/reference#outposts).
</Note>

<div id="2-watch-the-fleet-api-for-waiting-sessions">
  ### 2. Point de surveillance de la fleet API pour les sessions en attente
</div>

Votre orchestrateur liste les sessions en attente pour les outposts qu’il prend en charge :

```bash theme={null}
curl -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  "https://api.devin.ai/opbeta/outposts/devins?outpost=<outpost_id>&phase=pending"
```

Ensuite, il maintient sa vue à jour au moyen d’un point de surveillance SSE (Server-Sent Events), en reprenant depuis le curseur final de la liste :

```bash theme={null}
curl -N -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  "https://api.devin.ai/opbeta/outposts/devins?outpost=<outpost_id>&watch=true&cursor=<cursor>"
```

Il s’agit du schéma standard de Kubernetes consistant à lister puis à surveiller : parcourez la liste page par page à l’aide du curseur de réponse, puis démarrez un point de surveillance là où la liste s’est arrêtée, en conservant le curseur de chaque événement afin de pouvoir vous reconnecter sans manquer de modification. La livraison est garantie au moins une fois ; effectuez donc un upsert par `metadata.session_id` et acceptez les doublons. Consultez [Lister les sessions en file d’attente](/fr/cloud/outposts/reference#list-queued-sessions) et [Point de surveillance des modifications](/fr/cloud/outposts/reference#watch-for-changes) pour les paramètres de requête, les structures de réponse et la sémantique complète de la pagination.

<div id="3-claim-before-provisioning">
  ### 3. Prise en charge avant le provisionnement
</div>

Avant de démarrer une machine pour une session, prenez-la en charge de manière atomique afin qu’aucun autre worker ne la récupère. Transmettez un `acceptor_id` — un identifiant déclaré par votre worker lui-même :

```bash theme={null}
curl -X POST -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"acceptor_id": "worker-1"}' \
  "https://api.devin.ai/opbeta/outposts/devins/{session_id}/claim"
```

La prise en charge est atomique : si un autre worker a pris en charge la session en premier, vous recevez un `409`. La prise en charge garantit qu’un worker sera prêt avant l’échéance de prise en charge attribuée par le serveur (`status.claim_deadline`) ; les prises en charge expirées retournent automatiquement dans la file d’attente. Si le provisionnement échoue, [libérez la prise en charge](/fr/cloud/outposts/reference#release-a-claim) afin que la session retourne immédiatement dans la file d’attente.

<div id="4-spawn-a-machine-and-run-the-worker">
  ### 4. Lancer une machine et exécuter le worker
</div>

Pour chaque session prise en charge, provisionnez une VM ou un conteneur à partir de votre image. À l’intérieur, exécutez le worker depuis le répertoire où les dépôts de la session ont déjà été clonés :

```bash theme={null}
cd /path/to/repos
devin worker start --session=<session_id> --outpost=<outpost_id> --acceptor-id=<worker_id>
```

Transmettez le même `--acceptor-id` que celui utilisé pour la prise en charge via l’API, et fournissez le token via `--token` ou `DEVIN_OUTPOSTS_TOKEN` (voir la [liste complète des options](/fr/cloud/outposts/reference#devin-worker-start)). Le worker établit une connexion vers le cloud de Devin, marque la session comme prête et commence à exécuter des appels d’outil.

<div id="5-terminate-the-machine-when-the-worker-exits">
  ### 5. Arrêter la machine lorsque le worker s'arrête
</div>

Lorsque `devin worker start` s'arrête, la session est terminée (ou suspendue). Arrêtez la VM ou le conteneur. Si votre outpost permet la reprise, créez un snapshot de la machine avant de l'arrêter afin de pouvoir la restaurer si la session reprend.

Votre orchestrateur peut suivre les sessions qu'il a prises en charge et leurs états :

```bash theme={null}
curl -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  "https://api.devin.ai/opbeta/outposts/devins?phase=claimed&acceptor_id=worker-1"
```

Chaque entrée affiche un `status.session_status` égal à `pending`, `running`, `suspended` ou `terminated`.

<div id="centralization-free-scheduling">
  ## Planification sans centralisation
</div>

<Note>
  Vous prévoyez d'exécuter plus de \~16 coordinateurs (workers ou orchestrateurs
  qui surveillent un outpost et y prennent en charge des sessions) ? Contactez d'abord votre équipe en charge du compte — des
  flottes plus importantes amplifient la contention sur les prises en charge et la charge de lecture de la file, et nous voulons nous
  assurer que l'outpost est correctement dimensionné pour cela.
</Note>

Vous n'avez pas besoin d'un ordonnanceur central pour faire tourner une flotte. L'API de la file d'attente est conçue pour que de nombreux workers indépendants puissent servir le même outpost sans communiquer entre eux :

* **Les prises en charge sont l'unique mécanisme de coordination.** Chaque worker surveille la file de manière indépendante et entre en concurrence pour prendre en charge les sessions en attente. La prise en charge est un compare-and-swap atomique sur le serveur : un seul worker l'emporte, et tous les autres reçoivent un `409` puis passent simplement à la session en attente suivante. Perdre la course à la prise en charge fait partie du fonctionnement normal, ce n'est pas une erreur.
* **Chaque worker a sa propre identité.** L'`acceptor_id` limite à ce seul worker ses prises en charge, ses renouvellements et sa récupération après redémarrage. `devin worker start` en génère et en conserve automatiquement un par machine, donc une flotte n'a besoin d'aucune configuration d'identité. Ne partagez jamais un ID d'acceptor (ni un répertoire de données de worker copié) entre plusieurs machines — des workers en collision se voleront mutuellement leurs prises en charge.
* **Les défaillances se résorbent d'elles-mêmes.** Si un worker s'arrête après avoir pris en charge une session, sa prise en charge expire à l'échéance de prise en charge et la session revient dans la file pour qu'un autre worker la récupère. Aucun suivi de l'état de santé à l'échelle de la flotte n'est nécessaire.

Autrement dit, monter en charge consiste simplement à exécuter le worker sur davantage de machines pointant vers le même outpost : N machines servent N sessions simultanées, et le reste attend dans la file.

<div id="building-a-custom-orchestrator">
  ## Créer un orchestrateur personnalisé
</div>

Tout ce que fait `devin worker start` est disponible directement via la fleet API, vous pouvez donc remplacer entièrement la CLI : récupérez le binaire `devin-remote` à partir de la distribution statique de Devin et lancez-le vous-même avec l’environnement documenté. Consultez [Distribution du binaire distant](/fr/cloud/outposts/reference#remote-binary-distribution) et le [contrat de spawn](/fr/cloud/outposts/reference#spawn-contract) dans la documentation de référence.