> ## 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. # Référence > Commandes CLI, endpoints de la fleet API et contrat de spawn du worker Référence complète du périmètre fonctionnel d’Outposts : la CLI du worker, la fleet API, la distribution du binaire `devin-remote` et le contrat de spawn pour les orchestrateurs personnalisés.
## Authentification
Les workers et les orchestrateurs s’authentifient à l’aide d’un [jeton d’API v3](/fr/api-reference/v3/overview) appartenant à un utilisateur de service. Le rôle attribué à l’utilisateur de service confère au jeton ses périmètres Outposts : | Autorisation du rôle | Périmètre du jeton | Accorde | | ------------------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------- | | **Utiliser la machine Outposts** (`UseOutpostsMachine`) | `account.outposts.machine` | Lecture de la file d’attente et prise en charge/libération des sessions | | **Gérer les Outposts** (`ManageOutpostsOrchestrator`) | `account.outposts.orchestrator` | Création et suppression d’outposts (implique le périmètre machine) | Les Outposts sont associés à votre **compte** et partagés entre toutes les organisations de ce compte.
## CLI
### `devin worker start`
Interroge périodiquement la file d’attente d’un outpost, prend en charge les sessions, télécharge le bon binaire `devin-remote` et exécute les sessions. Lancez-la depuis le répertoire contenant les dépôts extraits pour la session. ```bash theme={null} devin worker start --outpost= ``` | Flag | Environment variable | Description | | ---------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--outpost` | — | Ne prendre en charge que les sessions de cet outpost. Si cette option est omise dans un terminal interactif, le worker vous invite à choisir parmi les outposts de votre compte. | | `--session` (alias `--session-id`) | — | Prendre en charge et servir une session spécifique, puis quitter. | | `--acceptor-id` | `DEVIN_WORKER_ACCEPTOR_ID` | Identité stable du worker utilisée pour les prises en charge, les renouvellements et la reprise après redémarrage. Par défaut, un ID généré est conservé dans le répertoire de données du worker. N’en partagez jamais un entre plusieurs machines. | | `--token` | `DEVIN_OUTPOSTS_TOKEN` | Auth token du worker. Si aucun des deux n’est défini, la commande renvoie une erreur. | | `--once` | — | Quitter après avoir servi une session au lieu de revenir dans la file d’attente. | | `--api-url` | `DEVIN_API_URL` | Base URL de l’API Devin. Valeur par défaut : `https://api.devin.ai`. | | `--cache-dir` | `DEVIN_WORKER_CACHE_DIR` | Répertoire dans lequel les binaires `devin-remote` téléchargés sont mis en cache. Valeur par défaut : `~/.devin/worker/cache`. | | `--static-base-url` | `DEVIN_WORKER_STATIC_BASE_URL` | Base URL sur laquelle les binaires `devin-remote` sont publiés. | | `--gateway-url` | `DEVIN_OUTPOST_GATEWAY_URL` | URL de secours de la passerelle outpost lorsque la réponse de prise en charge n’en contient pas. | | `--remote-binary-sha` | `DEVIN_WORKER_REMOTE_SHA` | SHA Git de secours pour `devin-remote` lorsque la session n’en épingle pas un. Si aucun des deux n’est défini, le dernier SHA publié est utilisé. | | `--pty-bridge-port` | `DEVIN_PTY_BRIDGE_PORT` | Port fixe pour la passerelle PTY. Valeur par défaut : un port libre alloué par session. | | `--poll-interval-secs` | — | Nombre de secondes entre les interrogations périodiques de la file d’attente et les vérifications du statut de la session. Valeur par défaut : `5`. | L’environnement du worker peut également inclure `DEVIN_CHROME_PATH` pour faire pointer les sessions vers un binaire Chrome/Chromium pour les fonctionnalités de navigateur.
### `devin worker outpost create`
Crée un outpost — une file d’attente de sessions nommée, gérée par votre infrastructure. Nécessite le périmètre orchestrator. ```bash theme={null} devin worker outpost create --platform --description "..." ``` | Argument / option | Description | | ----------------- | ------------------------------------------------------------- | | `` | Nom d’outpost unique (par compte), p. ex. `rhel`, `gpu-h200`. | | `--platform` | Plateforme de la machine : `linux`, `macos` ou `windows`. | | `--description` | Description lisible affichée dans l’application web. | Affiche l’ID du nouvel outpost (`outpost_env-...`). Vous pouvez également créer des outposts dans l’application web, sous **Settings → Environment → Outposts**.
### `devin worker outpost delete`
Supprime un outpost. Nécessite le périmètre « orchestrator ». ```bash theme={null} devin worker outpost delete ```
## Fleet API
Tous les endpoints se trouvent sous `https://api.devin.ai/opbeta/outposts/` et utilisent un jeton Bearer : ```bash theme={null} curl -H "Authorization: Bearer $DEVIN_API_TOKEN" ... ``` Les ressources suivent une structure de type Kubernetes `metadata` / `spec` / `status`, et la file d’attente suit la sémantique Kubernetes « list-then-watch » avec une garantie de livraison au moins une fois.
### Objets
#### Entrée de file d’attente (`devins`)
Chaque session en file d’attente est représentée par une entrée de file d’attente : | Champ | Description | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------- | | `metadata.session_id` | ID de la session (devin). | | `metadata.outpost_id` | ID de l’outpost sur lequel la session est en file d’attente. | | `metadata.created_at` | Date de mise en file d’attente de la session (horodatage Unix). | | `metadata.updated_at` | Date de dernière modification de cet objet (horodatage Unix). | | `spec.kind` | `new` ou `resume`. | | `spec.platform` | Plateforme de la machine, p. ex. `linux`. | | `spec.remote_binary_sha` | SHA de commit court du binaire `devin-remote` que le worker doit exécuter ; `null` indique la valeur par défaut du worker. | | `spec.network_policy` | Politique réseau effective de la session (voir ci-dessous). | | `status.phase` | Phase de la file d’attente : `pending` ou `claimed`. | | `status.acceptor_id` | Worker ayant actuellement pris en charge la session, le cas échéant. | | `status.claim_deadline` | Date à laquelle la prise en charge en cours expire et la session retourne dans la file d’attente. | | `status.session_status` | Statut général de la session sous-jacente : `pending`, `running`, `suspended` ou `terminated`. | | `status.connect_token` | Jeton de connexion de la passerelle ; renvoyé uniquement après une prise en charge réussie. | | `status.gateway_url` | URL WebSocket publique de la passerelle de l’outpost ; renvoyée uniquement après une prise en charge réussie. | `spec.network_policy` indique si l’accès réseau de la session est restreint (`enabled`) ainsi que les destinations autorisées (`allow`) : motifs de nom d’hôte (`{"hostname": ...}`), adresses IPv4/plages CIDR (`{"ipv4": ...}`) ou adresses IPv6/plages CIDR (`{"ipv6": ...}`).
#### Outpost
| Champ | Description | | ---------------------- | ---------------------------------------------------------------------------- | | `metadata.outpost_id` | Identifiant de l’outpost (`outpost_env-...`). | | `metadata.account_id` | Compte propriétaire de l’outpost. | | `metadata.created_at` | Date de création de l’outpost (horodatage Unix). | | `spec.name` | Nom d’outpost unique (par compte). | | `spec.platform` | Plateforme de la machine ; `null` indique la plateforme par défaut. | | `spec.description` | Description en clair. | | `status.queue_depth` | Nombre de sessions en attente (non prises en charge) dans la file d’attente. | | `status.active_claims` | Nombre de prises en charge non expirées détenues par des workers. |
### Lister les sessions en attente
``` GET /opbeta/outposts/devins ``` | Paramètre de requête | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `outpost` | Filtrer par ID d’outpost. S’applique à la fois au listing et au mode watch. | | `phase` | Filtrer par phase de la file d’attente (`pending` ou `claimed`). Ignoré en mode watch. | | `acceptor_id` | Filtrer par worker ayant pris en charge la session. Ignoré en mode watch. | | `first` | Nombre maximal de lignes par page de listing, de 1 à 200. La valeur par défaut est 100. | | `cursor` | Curseur opaque provenant d’une réponse de listing précédente ou d’un événement watch (les deux sont interchangeables). Pour un listing, renvoie les lignes à partir de cette position ; pour un watch, rejoue d’abord les modifications qui la suivent avant de diffuser les nouvelles en direct. | | `watch` | Diffuser les modifications sous forme de SSE au lieu de renvoyer une liste. | Exemple de réponse : ```json theme={null} { "items": [ { "metadata": { "session_id": "devin-...", "outpost_id": "outpost_env-...", "created_at": 1781050000, "updated_at": 1781050000 }, "spec": { "kind": "new", "platform": "linux", "remote_binary_sha": null }, "status": { "phase": "pending", "acceptor_id": null, "claim_deadline": null, "session_status": "pending" } } ], "cursor": "djE6MTc4MTA1MDAwMC4w", "has_next_page": false, "total": 1 } ``` Pagination et sémantique de livraison : * Passez le `cursor` de chaque réponse dans la requête suivante tant que `has_next_page` vaut `true`. * La livraison suit une sémantique « at-least-once » : une session à la jonction de deux pages peut apparaître dans les deux. Effectuez donc un upsert des entrées à partir de `metadata.session_id` plutôt que de traiter chaque élément comme nouveau (le CAS de prise en charge rend les doublons inoffensifs). * Lorsque `has_next_page` passe à `false`, enregistrez le curseur renvoyé comme position de départ pour une opération de surveillance.
### Surveiller les modifications
``` GET /opbeta/outposts/devins?watch=true&cursor= ``` Diffuse des Server-Sent Events. Les événements `MODIFIED` sont déclenchés lorsque l’entrée de file d’attente d’une session est modifiée (les sessions nouvellement placées en file d’attente arrivent également comme `MODIFIED`) ; les événements `DELETED` sont déclenchés lorsqu’elle est supprimée. Chaque champ SSE `data` contient : ```json theme={null} { "type": "MODIFIED", "object": { "metadata": { "session_id": "devin-...", "outpost_id": "outpost_env-...", "created_at": 1781050000, "updated_at": 1781050100 }, "spec": { "kind": "new", "platform": "linux", "remote_binary_sha": null }, "status": { "phase": "pending", "acceptor_id": null, "claim_deadline": null, "session_status": "pending" } }, "cursor": "djE6MTc4MTA1MDEwMC4w" } ``` Sémantique de surveillance : * Conservez le `cursor` de premier niveau de chaque événement après l’avoir traité ; reconnectez-vous avec le dernier curseur enregistré pour rejouer les modifications survenues pendant la déconnexion. * La livraison s’effectue au moins une fois — prévoyez donc la possibilité d’événements en double. * Les flux se terminent au bout de cinq minutes maximum ; une boucle de surveillance avec reconnexion est donc attendue. * Les filtres `phase` et `acceptor_id` sont ignorés lorsque `watch=true` ; filtrez les événements surveillés à l’aide des champs de l’`object` de chaque événement. * Si vous omettez le curseur, le flux démarre depuis le début ; utilisez donc list-then-watch pour une réconciliation normale.
### Récupérer une entrée de file d’attente
``` GET /opbeta/outposts/devins/{session_id} ``` Renvoie l’entrée de file d’attente d’une session.
### S’attribuer une session
``` POST /opbeta/outposts/devins/{session_id}/claim ``` ```json theme={null} { "acceptor_id": "worker-1" } ``` Prend en charge de manière atomique la session pour l’identité du worker spécifiée. Si un autre worker l’a prise en charge en premier, la requête échoue avec `409`. Une réponse de prise en charge réussie inclut `status.connect_token` et `status.gateway_url` — les identifiants dont `devin-remote` a besoin pour se connecter (voir le [contrat de spawn](#spawn-contract)). La prise en charge implique 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 sont automatiquement remises dans la file d’attente.
### Libérer une prise en charge
``` POST /opbeta/outposts/devins/{session_id}/release ``` ```json theme={null} { "acceptor_id": "worker-1" } ``` Libère la prise en charge par le worker afin que la session retourne immédiatement dans la file d’attente (par ex. en cas d’échec du provisionnement).
### Outposts
``` GET /opbeta/outposts/outposts # lister les outposts POST /opbeta/outposts/outposts # créer un outpost GET /opbeta/outposts/outposts/{outpost_id} # récupérer un outpost DELETE /opbeta/outposts/outposts/{outpost_id} # supprimer un outpost ``` Corps de la requête de création : ```json theme={null} { "name": "my-outpost", "platform": "linux", "description": "Dev boxes in our VPC" } ``` La création, la récupération et la suppression nécessitent le périmètre orchestrator ; chaque réponse d’outpost indique en temps réel `status.queue_depth` et `status.active_claims`.
## Distribution du binaire distant
La commande `devin worker start` télécharge automatiquement le binaire `devin-remote` approprié. Les orchestrateurs personnalisés qui n’utilisent pas le Devin CLI peuvent le récupérer directement ici : ``` https://static.devin.ai/devin-rs/remote/ ``` **Déterminez la version la plus récente :** ```bash theme={null} # Retourne le SHA git du dernier binaire publié pour votre plateforme curl -fsSL "https://static.devin.ai/devin-rs/remote/latest_linux_x64" ``` **Télécharger et vérifier :** ```bash theme={null} SHA=$(curl -fsSL "https://static.devin.ai/devin-rs/remote/latest_linux_x64") # Télécharger le binaire curl -fL "https://static.devin.ai/devin-rs/remote/devin-remote_${SHA}_linux_x64" \ -o devin-remote # Télécharger et vérifier la somme de contrôle curl -fsSL "https://static.devin.ai/devin-rs/remote/devin-remote_${SHA}_linux_x64.sha256" \ -o devin-remote.sha256 echo "$(cat devin-remote.sha256) devin-remote" | sha256sum -c chmod +x devin-remote ``` **Plateformes disponibles :** | Suffixe | OS / architecture | | ----------------- | ------------------- | | `linux_x64` | Linux x86\_64 | | `macos_arm64` | macOS Apple Silicon | | `windows_x64.exe` | Windows x86\_64 | Si l’élément de file d’attente de la session contient un `spec.remote_binary_sha`, utilisez ce SHA au lieu de `latest` — cela verrouille la session sur une version spécifique testée.
## Contrat de spawn
Si votre orchestrateur lance lui-même `devin-remote` au lieu d’utiliser `devin worker start`, démarrez-le comme suit : ```bash theme={null} devin-remote serve ``` avec les variables d’environnement suivantes : | Variable | Requis | Description | | ----------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DEVIN_OUTPOST_GATEWAY_URL` | Oui | URL de base de la passerelle Outpost, p. ex. `wss://outpost-gateway.devin.ai`. | | `DEVIN_OUTPOST_CONNECT_TOKEN` | Oui | Jeton Bearer de connexion pour la passerelle, provenant de la réponse à la prise en charge. | | `DEVIN_OUTPOST_SESSION_ID` | Oui | ID de la session prise en charge. Les trois variables `DEVIN_OUTPOST_*` doivent être définies ensemble. | | `DEVIN_REMOTE_STATE_DIR` | Fortement recommandé | Répertoire d’état propre à chaque session, dans lequel le remote stocke ses identifiants, jetons et fichiers d’intégration Shell. Utilisez un répertoire unique par session (p. ex. `~/.devin/worker/sessions/`, comme le fait `devin worker`). S’il n’est pas défini, le remote utilise à la place une valeur par défaut partagée à l’échelle du système (`/opt/.devin` sur Linux, `~/.devin` sur macOS, `C:\ProgramData\devin` sur Windows), qui doit alors exister et être accessible en écriture — et qui expose l’état de chaque session aux autres sessions concurrentes. Définissez-le systématiquement. | | `DEVIN_CHROME_PATH` | Facultatif | Chemin vers un binaire Chrome/Chromium sur la machine pour l’outil Browser (il n’y a pas de Chrome géré par Devin sur Outposts). | | `DEVIN_OUTPOST_DESKTOP` | Facultatif | Définissez cette variable sur `true` pour activer le flux du bureau (VNC). Côté remote, il est activé à la demande — rien n’est capturé tant qu’un visualiseur ne se connecte pas — il est donc possible de l’activer systématiquement en toute sécurité. | Fournissez au remote un environnement propre contenant uniquement les variables ci-dessus, ainsi que les variables système de base (`PATH`, `HOME`, `USER`, `LOGNAME`, `TMPDIR`, `LANG`, `TZ` et — pour la capture d’écran du flux du bureau sous Linux/X11 — `DISPLAY`, `WAYLAND_DISPLAY`, `XAUTHORITY`). Ne laissez rien fuiter dans le remote que l’agent ne devrait pas pouvoir voir : il est hérité par le shell de l’agent. Attentes supplémentaires concernant le cycle de vie : * **Répertoire de travail** : lancez le remote depuis le répertoire contenant les dépôts de la session (même règle que pour `devin worker start`). * **Fin de session** : lorsque la session se termine (se met en veille ou s’arrête), Devin notifie le remote et celui-ci s’arrête de lui-même avec le code de sortie 0. Traitez un arrêt propre comme la fin de la session : confirmez que le `status.session_status` de l’entrée de file d’attente est `suspended` ou `terminated` (la mise à jour du statut peut avoir quelques secondes de retard, donc revérifiez plusieurs fois), puis libérez la prise en charge. En solution de repli, interrogez aussi périodiquement `status.session_status` pendant l’exécution du remote et tuez vous-même le processus dès qu’il atteint `terminated` (ou que l’entrée de file d’attente disparaît).