> ## 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. # Riferimento > Comandi CLI, endpoint dell'API della flotta e contratto di spawn del worker Riferimento completo per tutti i componenti di Outposts: la CLI del worker, l'API della flotta, la distribuzione del binario `devin-remote` e il contratto di spawn per orchestrator personalizzati.
## Autenticazione
I worker e gli orchestratori si autenticano con un [token API v3](/it/api-reference/v3/overview) associato a un utente di servizio. Il ruolo assegnato all'utente di servizio conferisce al token i relativi ambiti di Outposts: | Autorizzazione del ruolo | Ambito del token | Consente | | --------------------------------------------------------- | ------------------------------- | ------------------------------------------------------- | | **Usare la macchina dell'outpost** (`UseOutpostsMachine`) | `account.outposts.machine` | Leggere la coda e rivendicare/rilasciare le sessioni | | **Gestire Outposts** (`ManageOutpostsOrchestrator`) | `account.outposts.orchestrator` | Creare ed eliminare outpost (implica l'ambito macchina) | Outposts è associato al tuo **account** ed è condiviso tra tutte le relative organizzazioni.
## CLI
### `devin worker start`
Esegue il polling della coda di un outpost, rivendica le sessioni, scarica il binario `devin-remote` corretto e gestisce le sessioni. Eseguilo dalla directory che contiene i repository della sessione su cui è stato eseguito il checkout. ```bash theme={null} devin worker start --outpost= ``` | Flag | Environment variable | Descrizione | | ---------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--outpost` | — | Rivendica solo le sessioni da questo outpost. Se omesso in un terminale interattivo, il worker ti chiede di scegliere tra gli outpost del tuo account. | | `--session` (alias `--session-id`) | — | Rivendica e gestisce una sessione specifica, quindi esce. | | `--acceptor-id` | `DEVIN_WORKER_ACCEPTOR_ID` | Identità stabile del worker usata per le rivendicazioni, i rinnovi e il recupero dopo il riavvio. Per impostazione predefinita usa un ID generato e salvato nella directory dei dati del worker. Non condividerne mai uno tra più macchine. | | `--token` | `DEVIN_OUTPOSTS_TOKEN` | Token di autenticazione per il worker. Se nessuno dei due è impostato, il comando restituisce un errore. | | `--once` | — | Esce dopo aver gestito una sessione invece di tornare alla coda. | | `--api-url` | `DEVIN_API_URL` | URL di base dell'API di Devin. Per impostazione predefinita è `https://api.devin.ai`. | | `--cache-dir` | `DEVIN_WORKER_CACHE_DIR` | Directory in cui vengono memorizzati nella cache i file binari `devin-remote` scaricati. Per impostazione predefinita è `~/.devin/worker/cache`. | | `--static-base-url` | `DEVIN_WORKER_STATIC_BASE_URL` | URL di base in cui vengono pubblicati i file binari `devin-remote`. | | `--gateway-url` | `DEVIN_OUTPOST_GATEWAY_URL` | URL di fallback del gateway dell'outpost quando la risposta alla rivendicazione non ne include uno. | | `--remote-binary-sha` | `DEVIN_WORKER_REMOTE_SHA` | SHA git di fallback di `devin-remote` quando la sessione non ne blocca uno. Se nessuno dei due è impostato, viene usato l'ultimo SHA pubblicato. | | `--pty-bridge-port` | `DEVIN_PTY_BRIDGE_PORT` | Porta fissa del bridge PTY. Per impostazione predefinita viene allocata una porta libera per ogni sessione. | | `--poll-interval-secs` | — | Secondi tra un controllo della coda e l'altro e tra le verifiche dello stato della sessione. Per impostazione predefinita è `5`. | L'environment del worker può includere anche `DEVIN_CHROME_PATH` per indirizzare le sessioni a un file binario Chrome/Chromium per le funzionalità del Browser.
### `devin worker outpost create`
Crea un outpost, ovvero una coda di sessioni con nome gestita dalla tua infrastruttura. Richiede l'ambito dell'orchestrator. ```bash theme={null} devin worker outpost create --platform --description "..." ``` | Argomento / flag | Descrizione | | ---------------- | ------------------------------------------------------------------- | | `` | Nome univoco dell'outpost (per account), ad es. `rhel`, `gpu-h200`. | | `--platform` | Piattaforma della macchina: `linux`, `macos` o `windows`. | | `--description` | Descrizione leggibile mostrata nell'app web. | Stampa l'ID del nuovo outpost (`outpost_env-...`). Puoi anche creare outpost nell'app web in **Settings → Environment → Outposts**.
### `devin worker outpost delete`
Elimina un outpost. Richiede l'ambito orchestrator. ```bash theme={null} devin worker outpost delete ```
## API della flotta
Tutti gli endpoint si trovano in `https://api.devin.ai/opbeta/outposts/` e richiedono un token Bearer: ```bash theme={null} curl -H "Authorization: Bearer $DEVIN_API_TOKEN" ... ``` Le risorse seguono una struttura in stile Kubernetes con `metadata` / `spec` / `status`, e la coda segue la semantica Kubernetes list-then-watch, con consegna almeno una volta.
### Oggetti
#### Elemento della coda (`devins`)
Ogni sessione in coda è rappresentata da un elemento della coda: | Campo | Descrizione | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | | `metadata.session_id` | L'ID della sessione (devin). | | `metadata.outpost_id` | L'outpost su cui la sessione è in coda. | | `metadata.created_at` | Quando la sessione è stata accodata (timestamp Unix). | | `metadata.updated_at` | Quando questo oggetto è stato modificato l'ultima volta (timestamp Unix). | | `spec.kind` | `new` o `resume`. | | `spec.platform` | Piattaforma della macchina, ad es. `linux`. | | `spec.remote_binary_sha` | SHA di commit breve del file binario `devin-remote` che il worker deve eseguire; `null` indica il valore predefinito del worker. | | `spec.network_policy` | La policy di rete effettiva della sessione (vedi sotto). | | `status.phase` | Fase della coda: `pending` o `claimed`. | | `status.acceptor_id` | Worker che detiene attualmente la rivendicazione, se presente. | | `status.claim_deadline` | Quando la rivendicazione corrente scade e la sessione torna in coda. | | `status.session_status` | Stato generale della sessione sottostante: `pending`, `running`, `suspended` o `terminated`. | | `status.connect_token` | Token di connessione del gateway; restituito solo dopo una rivendicazione riuscita. | | `status.gateway_url` | URL websocket pubblico del gateway dell'outpost; restituito solo dopo una rivendicazione riuscita. | `spec.network_policy` indica se l'accesso di rete della sessione è limitato (`enabled`) e le destinazioni consentite (`allow`): pattern glob di hostname (`{"hostname": ...}`), indirizzi/CIDR IPv4 (`{"ipv4": ...}`) o indirizzi/CIDR IPv6 (`{"ipv6": ...}`).
#### Outpost
| Campo | Descrizione | | ---------------------- | --------------------------------------------------------------------- | | `metadata.outpost_id` | ID dell'outpost (`outpost_env-...`). | | `metadata.account_id` | Account che possiede l'outpost. | | `metadata.created_at` | Data di creazione dell'outpost (timestamp Unix). | | `spec.name` | Nome univoco dell'outpost (per account). | | `spec.platform` | Piattaforma della macchina; `null` indica la piattaforma predefinita. | | `spec.description` | Descrizione leggibile. | | `status.queue_depth` | Numero di sessioni in attesa nella coda (non ancora prese in carico). | | `status.active_claims` | Numero di claim non scaduti in possesso dei worker. |
### Elencare le sessioni in attesa
``` GET /opbeta/outposts/devins ``` | Parametro di query | Descrizione | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `outpost` | Filtra per ID dell'outpost. Si applica sia all'elenco sia al monitoraggio. | | `phase` | Filtra per fase della coda (`pending` o `claimed`). Ignorato durante il monitoraggio. | | `acceptor_id` | Filtra per il worker che ha rivendicato la sessione. Ignorato durante il monitoraggio. | | `first` | Numero massimo di righe per pagina dell'elenco, 1–200. Il valore predefinito è 100. | | `cursor` | Cursor opaco da una precedente risposta di elenco o da un evento di monitoraggio (i due sono intercambiabili). Per un elenco, restituisce le righe in corrispondenza o dopo questa posizione; per il monitoraggio, riproduce prima le modifiche successive e poi trasmette quelle in tempo reale. | | `watch` | Trasmette le modifiche come SSE invece di restituire un elenco. | Risposta di esempio: ```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 } ``` Semantica di paginazione e consegna: * Passa il `cursor` di ogni risposta alla richiesta successiva finché `has_next_page` è `true`. * La consegna segue una semantica at-least-once: una sessione al confine tra due pagine può comparire in entrambe, quindi aggiorna o inserisci le voci in base a `metadata.session_id` invece di considerare ogni elemento come nuovo (il CAS usato per la rivendicazione rende innocui i duplicati). * Quando `has_next_page` diventa `false`, salva il `cursor` restituito come posizione iniziale per un watch.
### Monitora le modifiche
``` GET /opbeta/outposts/devins?watch=true&cursor= ``` Trasmette eventi Server-Sent Events. Gli eventi `MODIFIED` vengono inviati quando cambia l'elemento in coda di una sessione (anche le sessioni appena messe in coda arrivano come `MODIFIED`); gli eventi `DELETED` vengono inviati quando viene rimosso. Ogni campo SSE `data` contiene: ```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" } ``` Semantica di watch: * Salva il `cursor` di primo livello di ogni evento dopo averlo elaborato; riconnettiti con l'ultimo cursor salvato per recuperare le modifiche avvenute durante la disconnessione. * La consegna segue una semantica at-least-once — prevedi eventi duplicati. * I flussi terminano dopo al massimo cinque minuti; è previsto un ciclo di watch con riconnessione. * I filtri `phase` e `acceptor_id` vengono ignorati quando `watch=true`; filtra gli eventi monitorati usando i campi nell'`object` di ogni evento. * Se ometti il cursor, si parte dall'inizio, quindi usa `list-then-watch` per una riconciliazione standard.
### Recupera un elemento della coda
``` GET /opbeta/outposts/devins/{session_id} ``` Restituisce l'elemento della coda per una sessione.
### Rivendica una sessione
``` POST /opbeta/outposts/devins/{session_id}/claim ``` ```json theme={null} { "acceptor_id": "worker-1" } ``` Rivendica la sessione in modo atomico per l'identità del worker specificata. Se un altro worker l'ha rivendicata per primo, la richiesta restituisce `409`. In caso di esito positivo, la risposta include `status.connect_token` e `status.gateway_url` — le credenziali necessarie a `devin-remote` per connettersi (vedi lo [contratto di spawn](#spawn-contract)). La rivendicazione implica che un worker sarà pronto entro il termine di rivendicazione assegnato dal server (`status.claim_deadline`); le rivendicazioni scadute tornano automaticamente nella coda.
### Annullare una rivendicazione
``` POST /opbeta/outposts/devins/{session_id}/release ``` ```json theme={null} { "acceptor_id": "worker-1" } ``` Rilascia la rivendicazione del worker, così la sessione torna immediatamente in coda (ad es. quando il provisioning non va a buon fine).
### Outposts
``` GET /opbeta/outposts/outposts # elenca gli outpost POST /opbeta/outposts/outposts # crea un outpost GET /opbeta/outposts/outposts/{outpost_id} # recupera un outpost DELETE /opbeta/outposts/outposts/{outpost_id} # elimina un outpost ``` Corpo della richiesta di creazione: ```json theme={null} { "name": "my-outpost", "platform": "linux", "description": "Dev boxes in our VPC" } ``` La creazione, il recupero e l'eliminazione richiedono l'ambito orchestrator; ogni risposta dell'outpost riporta in tempo reale `status.queue_depth` e `status.active_claims`.
## Distribuzione del binario remoto
Il comando `devin worker start` scarica automaticamente il binario `devin-remote` corretto. Gli orchestratori personalizzati che non usano la Devin CLI possono scaricarlo direttamente da: ``` https://static.devin.ai/devin-rs/remote/ ``` **Individua la versione più recente:** ```bash theme={null} # Restituisce il git SHA del binary più recente pubblicato per la tua piattaforma curl -fsSL "https://static.devin.ai/devin-rs/remote/latest_linux_x64" ``` **Scarica e verifica:** ```bash theme={null} SHA=$(curl -fsSL "https://static.devin.ai/devin-rs/remote/latest_linux_x64") # Scarica il binary curl -fL "https://static.devin.ai/devin-rs/remote/devin-remote_${SHA}_linux_x64" \ -o devin-remote # Scarica e verifica il checksum 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 ``` **Piattaforme disponibili:** | Suffisso | SO / Architettura | | ----------------- | ------------------- | | `linux_x64` | Linux x86\_64 | | `macos_arm64` | macOS Apple Silicon | | `windows_x64.exe` | Windows x86\_64 | Se la voce della coda della sessione include un `spec.remote_binary_sha`, usa quell'SHA invece di `latest` — in questo modo blocchi la sessione su una specifica versione testata.
## Contratto di spawn
Se il tuo orchestrator avvia `devin-remote` direttamente anziché usare `devin worker start`, avvialo come segue: ```bash theme={null} devin-remote serve ``` con le seguenti variabili d'ambiente: | Variable | Required | Description | | ----------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DEVIN_OUTPOST_GATEWAY_URL` | Sì | Base URL del gateway dell'outpost, ad es. `wss://outpost-gateway.devin.ai`. | | `DEVIN_OUTPOST_CONNECT_TOKEN` | Sì | Bearer token di connessione per il gateway, ottenuto dalla risposta di rivendicazione. | | `DEVIN_OUTPOST_SESSION_ID` | Sì | L'ID della sessione servita. Tutte e tre le variabili `DEVIN_OUTPOST_*` devono essere impostate insieme. | | `DEVIN_REMOTE_STATE_DIR` | Fortemente consigliato | Directory di stato per sessione in cui il processo remoto archivia credenziali, token e file di integrazione della shell. Usa una directory univoca per ogni sessione (ad es. `~/.devin/worker/sessions/`, che è quella usata da `devin worker`). Se non è impostata, il processo remoto usa come fallback una directory predefinita condivisa a livello di sistema (`/opt/.devin` su Linux, `~/.devin` su macOS, `C:\ProgramData\devin` su Windows), che deve quindi esistere ed essere scrivibile e che comporta la condivisione dello stato per sessione tra sessioni concorrenti. Imposta sempre questa variabile. | | `DEVIN_CHROME_PATH` | Facoltativo | Percorso di un file binario Chrome/Chromium sulla macchina per lo strumento browser (su Outposts non esiste un Chrome gestito da Devin). | | `DEVIN_OUTPOST_DESKTOP` | Facoltativo | Imposta su `true` per abilitare il flusso desktop (VNC). Sul lato remoto viene attivato solo quando un visualizzatore si connette, quindi è sicuro abilitarlo sempre. | Fornisci al processo remoto un ambiente pulito che contenga solo le variabili sopra, oltre alle variabili di sistema di base (`PATH`, `HOME`, `USER`, `LOGNAME`, `TMPDIR`, `LANG`, `TZ` e — per l'acquisizione dello schermo del flusso desktop su Linux/X11 — `DISPLAY`, `WAYLAND_DISPLAY`, `XAUTHORITY`). Non esporre al processo remoto nulla che l'agente non dovrebbe poter vedere: viene ereditato dalla shell dell'agente. Aspettative aggiuntive del lifecycle: * **Directory di lavoro**: avvia il processo remoto dalla directory che contiene le repo della sessione (la stessa regola di `devin worker start`). * **Fine della sessione**: quando la sessione termina (va in sleep o viene chiusa), Devin notifica il processo remoto e questo termina autonomamente con status 0. Considera un'uscita pulita come la fine della sessione: verifica che `status.session_status` dell'elemento della coda sia `suspended` o `terminated` (l'aggiornamento dello status può arrivare con alcuni secondi di ritardo rispetto all'uscita, quindi rileggilo alcune volte), quindi rilascia la rivendicazione. Come fallback, esegui anche il poll di `status.session_status` mentre il processo remoto è in esecuzione e termina tu stesso il processo quando raggiunge `terminated` (o se l'elemento della coda scompare).