Riferimento

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 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.

devin worker start --outpost=<outpost_id>

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.

devin worker outpost create <name> --platform <platform> --description "..."

Argomento / flag	Descrizione
`<name>`	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.

devin worker outpost delete <outpost_id>

API della flotta

Tutti gli endpoint si trovano in https://api.devin.ai/opbeta/outposts/ e richiedono un token Bearer:

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:

{
  "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=<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:

{
  "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

{ "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). 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

{ "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:

{
  "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:

# 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:

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:

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/<session_id>`, 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).

Introduzione

Guide fondamentali

Introduzione a Devin

Lavorare con Devin

Guide sul prodotto

Integrazioni

Admin

Note di rilascio

Autenticazione

CLI

`devin worker start`

`devin worker outpost create`

`devin worker outpost delete`

API della flotta

Oggetti

Elemento della coda (`devins`)

Outpost

Elencare le sessioni in attesa

Monitora le modifiche

Recupera un elemento della coda

Rivendica una sessione

Annullare una rivendicazione

Outposts

Distribuzione del binario remoto

Contratto di spawn

​Autenticazione

​CLI

​devin worker start

​devin worker outpost create

​devin worker outpost delete

​API della flotta

​Oggetti

​Elemento della coda (devins)

​Outpost

​Elencare le sessioni in attesa

​Monitora le modifiche

​Recupera un elemento della coda

​Rivendica una sessione

​Annullare una rivendicazione

​Outposts

​Distribuzione del binario remoto

​Contratto di spawn

Autenticazione

CLI

`devin worker start`

`devin worker outpost create`

`devin worker outpost delete`

API della flotta

Oggetti

Elemento della coda (`devins`)

Outpost

Elencare le sessioni in attesa

Monitora le modifiche

Recupera un elemento della coda

Rivendica una sessione

Annullare una rivendicazione

Outposts

Distribuzione del binario remoto

Contratto di spawn