> ## 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. # Referenz > CLI-Befehle, Endpunkte der fleet API und der Spawn-Spezifikation für worker Vollständige Referenz zum Outposts-Funktionsumfang: die worker-CLI, die fleet API, die Distribution der `devin-remote`-Binärdatei und die Spawn-Spezifikation für benutzerdefinierte Orchestratoren.
## Authentifizierung
Worker und Orchestratoren authentifizieren sich mit einem [v3-API-Token](/de/api-reference/v3/overview), das zu einem Service-Benutzer gehört. Die dem Service-Benutzer zugewiesene Rolle legt die Outposts-Geltungsbereiche des Tokens fest: | Rollenberechtigung | Token-Geltungsbereich | Gewährt | | ----------------------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------- | | **Outpost-Maschine verwenden** (`UseOutpostsMachine`) | `account.outposts.machine` | Lesen der Warteschlange sowie Übernehmen und Freigeben von Sitzungen | | **Outposts verwalten** (`ManageOutpostsOrchestrator`) | `account.outposts.orchestrator` | Erstellen und Löschen von Outposts (einschließlich des Maschinen-Geltungsbereichs) | Outposts sind Ihrem **Konto** zugeordnet und werden von allen zugehörigen Organisationen gemeinsam genutzt.
## CLI
### `devin worker start`
Fragt die Warteschlange eines Outposts regelmäßig ab, nimmt Sitzungen an, lädt die passende `devin-remote`-Binärdatei herunter und führt Sitzungen aus. Führen Sie den Befehl in dem Verzeichnis aus, das die ausgecheckten Repositorys der Sitzung enthält. ```bash theme={null} devin worker start --outpost= ``` | Flag | Umgebungsvariable | Beschreibung | | ---------------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--outpost` | — | Nur Sitzungen aus diesem Outpost beanspruchen. Wenn dies in einem interaktiven Terminal weggelassen wird, fordert der Worker Sie auf, einen Outpost aus Ihrem Konto auszuwählen. | | `--session` (alias `--session-id`) | — | Eine bestimmte Sitzung beanspruchen und verarbeiten, dann beenden. | | `--acceptor-id` | `DEVIN_WORKER_ACCEPTOR_ID` | Stabile Worker-Identität für Claims, Verlängerungen und die Wiederherstellung nach Neustarts. Standardmäßig wird eine generierte ID verwendet, die im Datenverzeichnis des Workers gespeichert wird. Verwenden Sie dieselbe ID niemals auf mehreren Maschinen. | | `--token` | `DEVIN_OUTPOSTS_TOKEN` | Auth-Token für den Worker. Wenn keines von beiden gesetzt ist, schlägt der Befehl fehl. | | `--once` | — | Nach der Verarbeitung einer Sitzung beenden, anstatt zur Warteschlange zurückzukehren. | | `--api-url` | `DEVIN_API_URL` | Basis-URL der Devin API. Standardmäßig `https://api.devin.ai`. | | `--cache-dir` | `DEVIN_WORKER_CACHE_DIR` | Verzeichnis, in dem heruntergeladene `devin-remote`-Binärdateien zwischengespeichert werden. Standardmäßig `~/.devin/worker/cache`. | | `--static-base-url` | `DEVIN_WORKER_STATIC_BASE_URL` | Basis-URL, unter der `devin-remote`-Binärdateien veröffentlicht werden. | | `--gateway-url` | `DEVIN_OUTPOST_GATEWAY_URL` | Fallback-Outpost-Gateway-URL, falls die Claim-Antwort keine enthält. | | `--remote-binary-sha` | `DEVIN_WORKER_REMOTE_SHA` | Fallback-Git-SHA für `devin-remote`, wenn für die Sitzung keines angepinnt ist. Wenn keines von beiden gesetzt ist, wird die zuletzt veröffentlichte SHA verwendet. | | `--pty-bridge-port` | `DEVIN_PTY_BRIDGE_PORT` | Fester PTY-Bridge-Port. Standardmäßig wird pro Sitzung ein freier Port zugewiesen. | | `--poll-interval-secs` | — | Sekunden zwischen Warteschlangen-Abfragen und Statusprüfungen der Sitzung. Standardmäßig `5`. | Die Umgebung des Workers kann außerdem `DEVIN_CHROME_PATH` enthalten, um Sitzungen für Browser-Funktionen auf eine Chrome-/Chromium-Binärdatei zu verweisen.
### `devin worker outpost create`
Erstellt einen Outpost – eine benannte Warteschlange für Sitzungen, die von Ihrer Infrastruktur bedient wird. Erfordert den Geltungsbereich orchestrator. ```bash theme={null} devin worker outpost create --platform --description "..." ``` | Argument / Flag | Beschreibung | | --------------- | -------------------------------------------------------------------- | | `` | Eindeutiger (pro Konto) Name des Outposts, z. B. `rhel`, `gpu-h200`. | | `--platform` | Plattform der Maschine: `linux`, `macos` oder `windows`. | | `--description` | Lesbare Beschreibung, die in der Web-App angezeigt wird. | Gibt die ID des neuen Outposts aus (`outpost_env-...`). Sie können Outposts auch in der Web-App unter **Settings → Environment → Outposts** erstellen.
### `devin worker outpost delete`
Löscht einen Outpost. Erfordert den Geltungsbereich „orchestrator“. ```bash theme={null} devin worker outpost delete ```
## Fleet API
Alle Endpunkte sind unter `https://api.devin.ai/opbeta/outposts/` verfügbar und verwenden ein Bearer-Token: ```bash theme={null} curl -H "Authorization: Bearer $DEVIN_API_TOKEN" ... ``` Ressourcen folgen einer Kubernetes-ähnlichen `metadata`-/`spec`-/`status`-Struktur, und die Warteschlange verwendet die Kubernetes-Semantik „list-then-watch“ mit mindestens einmaliger Zustellung.
### Objekte
#### Warteschlangeneintrag (`devins`)
Jede Sitzung in der Warteschlange wird durch einen Warteschlangeneintrag dargestellt: | Feld | Beschreibung | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------ | | `metadata.session_id` | Die ID der Sitzung (`devin`). | | `metadata.outpost_id` | Der Outpost, in dessen Warteschlange die Sitzung eingereiht ist. | | `metadata.created_at` | Zeitpunkt, zu dem die Sitzung in die Warteschlange eingereiht wurde (Unix-Zeitstempel). | | `metadata.updated_at` | Zeitpunkt der letzten Änderung dieses Objekts (Unix-Zeitstempel). | | `spec.kind` | `new` oder `resume`. | | `spec.platform` | Maschinenplattform, z. B. `linux`. | | `spec.remote_binary_sha` | Kurze Commit-SHA der `devin-remote`-Binärdatei, die der Worker ausführen soll; `null` bedeutet den Standard des Workers. | | `spec.network_policy` | Die effektive Netzwerkrichtlinie der Sitzung (siehe unten). | | `status.phase` | Warteschlangenphase: `pending` oder `claimed`. | | `status.acceptor_id` | Worker, der die Sitzung derzeit beansprucht hat, sofern sie beansprucht wurde. | | `status.claim_deadline` | Zeitpunkt, zu dem die aktuelle Beanspruchung abläuft und die Sitzung in die Warteschlange zurückkehrt. | | `status.session_status` | Grober Status der zugrunde liegenden Sitzung: `pending`, `running`, `suspended` oder `terminated`. | | `status.connect_token` | Gateway-Verbindungstoken; wird nur nach einer erfolgreichen Beanspruchung zurückgegeben. | | `status.gateway_url` | Öffentliche WebSocket-URL des Outpost-Gateways; wird nur nach einer erfolgreichen Beanspruchung zurückgegeben. | `spec.network_policy` gibt an, ob der Netzwerkzugriff der Sitzung eingeschränkt ist (`enabled`) und welche Ziele zulässig sind (`allow`): Hostname-Muster (`{"hostname": ...}`), IPv4-Adressen/CIDRs (`{"ipv4": ...}`) oder IPv6-Adressen/CIDRs (`{"ipv6": ...}`).
#### Outpost
| Feld | Beschreibung | | ---------------------- | ------------------------------------------------------------------------------ | | `metadata.outpost_id` | Die Outpost-ID (`outpost_env-...`). | | `metadata.account_id` | Konto, dem der Outpost gehört. | | `metadata.created_at` | Zeitpunkt der Erstellung des Outposts (Unix-Zeitstempel). | | `spec.name` | Eindeutiger Outpost-Name (pro Konto). | | `spec.platform` | Plattform der Maschine; `null` bedeutet die Standardplattform. | | `spec.description` | Für Menschen lesbare Beschreibung. | | `status.queue_depth` | Anzahl ausstehender (noch nicht beanspruchter) Sitzungen in der Warteschlange. | | `status.active_claims` | Anzahl nicht abgelaufener Reservierungen durch Worker. |
### Sitzungen in der Warteschlange auflisten
``` GET /opbeta/outposts/devins ``` | Abfrageparameter | Beschreibung | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `outpost` | Nach der Outpost-ID filtern. Gilt sowohl für `list` als auch für `watch`. | | `phase` | Nach der Warteschlangenphase filtern (`pending` oder `claimed`). Wird bei `watch` ignoriert. | | `acceptor_id` | Nach dem Worker filtern, der die Sitzung beansprucht hat. Wird bei `watch` ignoriert. | | `first` | Maximale Anzahl von Zeilen pro `list`-Seite, 1–200. Standard ist 100. | | `cursor` | Opaker Cursor aus einer vorherigen `list`-Antwort oder einem `watch`-Ereignis (beide sind austauschbar). Für `list` werden Zeilen an oder ab dieser Position zurückgegeben; für `watch` werden Änderungen danach erneut abgespielt, bevor Live-Änderungen gestreamt werden. | | `watch` | Änderungen als SSE streamen, statt sie aufzulisten. | Beispielantwort: ```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 } ``` Paginierungs- und Zustellungssemantik: * Übergeben Sie den `Cursor` jeder Antwort in die nächste Anfrage, solange `has_next_page` `true` ist. * Die Zustellung erfolgt mindestens einmal: Eine Sitzung an einer Seitengrenze kann auf beiden Seiten erscheinen. Führen Sie daher Upserts für Einträge anhand von `metadata.session_id` aus, anstatt jedes Element als neu zu behandeln (das Claim-CAS macht Duplikate unschädlich). * Wenn `has_next_page` `false` wird, speichern Sie den zurückgegebenen Cursor als Startposition für einen Watch.
### Änderungen beobachten
``` GET /opbeta/outposts/devins?watch=true&cursor= ``` Streamt Server-Sent Events. `MODIFIED`-Ereignisse werden ausgelöst, wenn sich der Warteschlangeneintrag einer Sitzung ändert (neu in die Warteschlange aufgenommene Sitzungen kommen ebenfalls als `MODIFIED` an); `DELETED`-Ereignisse werden ausgelöst, wenn er entfernt wird. Jedes SSE-`data`-Feld enthält: ```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" } ``` Watch-Semantik: * Persistieren Sie nach der Verarbeitung jedes Ereignisses dessen `cursor` auf oberster Ebene; stellen Sie die Verbindung mit dem zuletzt persistierten Cursor wieder her, um Änderungen wiederzugeben, die während der Unterbrechung aufgetreten sind. * Die Zustellung erfolgt mindestens einmal — tolerieren Sie doppelte Ereignisse. * Streams enden nach spätestens fünf Minuten; eine Watch-Schleife mit Wiederverbindung wird erwartet. * `phase`- und `acceptor_id`-Filter werden ignoriert, wenn `watch=true`; filtern Sie beobachtete Ereignisse stattdessen anhand der Felder im `object` jedes Ereignisses. * Wenn der Cursor weggelassen wird, beginnt der Stream am Anfang. Verwenden Sie daher für den normalen Abgleich list-then-watch.
### Einen Queue-Eintrag abrufen
``` GET /opbeta/outposts/devins/{session_id} ``` Gibt den Warteschlangeneintrag für eine Sitzung zurück.
### Eine Sitzung übernehmen
``` POST /opbeta/outposts/devins/{session_id}/claim ``` ```json theme={null} { "acceptor_id": "worker-1" } ``` Beansprucht die Sitzung atomar für die angegebene Worker-Identität. Wenn ein anderer Worker sie zuerst beansprucht hat, schlägt die Anfrage mit `409` fehl. Eine erfolgreiche Beanspruchungsantwort enthält `status.connect_token` und `status.gateway_url` — die Zugangsdaten, die `devin-remote` zum Herstellen der Verbindung benötigt (siehe den [Spawn-Spezifikation](#spawn-contract)). Mit der Beanspruchung wird zugesichert, dass ein Worker innerhalb der vom Server zugewiesenen Claim-Deadline (`status.claim_deadline`) bereit ist; abgelaufene Beanspruchungen kehren automatisch in die Warteschlange zurück.
### Eine Beanspruchung freigeben
``` POST /opbeta/outposts/devins/{session_id}/release ``` ```json theme={null} { "acceptor_id": "worker-1" } ``` Gibt die Reservierung des Workers frei, sodass die Sitzung sofort in die Warteschlange zurückkehrt (z. B. wenn die Bereitstellung fehlschlägt).
### Outposts
``` GET /opbeta/outposts/outposts # Outposts auflisten POST /opbeta/outposts/outposts # einen Outpost erstellen GET /opbeta/outposts/outposts/{outpost_id} # einen Outpost abrufen DELETE /opbeta/outposts/outposts/{outpost_id} # einen Outpost löschen ``` Request-Body für das Erstellen: ```json theme={null} { "name": "my-outpost", "platform": "linux", "description": "Dev boxes in our VPC" } ``` Zum Erstellen, Abrufen und Löschen ist der Geltungsbereich `orchestrator` erforderlich; jede Outpost-Antwort enthält die aktuellen Werte von `status.queue_depth` und `status.active_claims`.
## Verteilung von Remote-Binärdateien
Der Befehl `devin worker start` lädt automatisch die passende `devin-remote`-Binärdatei herunter. Benutzerdefinierte Orchestratoren, die nicht die Devin CLI verwenden, können sie direkt hier abrufen: ``` https://static.devin.ai/devin-rs/remote/ ``` **Neueste Version ermitteln:** ```bash theme={null} # Gibt den Git-SHA der neuesten veröffentlichten Binary für Ihre Plattform zurück curl -fsSL "https://static.devin.ai/devin-rs/remote/latest_linux_x64" ``` **Herunterladen und überprüfen:** ```bash theme={null} SHA=$(curl -fsSL "https://static.devin.ai/devin-rs/remote/latest_linux_x64") # Binary herunterladen curl -fL "https://static.devin.ai/devin-rs/remote/devin-remote_${SHA}_linux_x64" \ -o devin-remote # Prüfsumme herunterladen und verifizieren 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 ``` **Verfügbare Plattformen:** | Suffix | OS / Architektur | | ----------------- | ------------------- | | `linux_x64` | Linux x86\_64 | | `macos_arm64` | macOS Apple Silicon | | `windows_x64.exe` | Windows x86\_64 | Wenn der Warteschlangeneintrag der Sitzung ein `spec.remote_binary_sha` enthält, verwenden Sie diesen SHA-Wert anstelle von `latest` — dadurch wird die Sitzung auf eine bestimmte getestete Version angepinnt.
## Spawn-Spezifikation
Wenn Ihr Orchestrator `devin-remote` selbst startet, statt `devin worker start` zu verwenden, starten Sie ihn wie folgt: ```bash theme={null} devin-remote serve ``` mit den folgenden Umgebungsvariablen: | Variable | Erforderlich | Beschreibung | | ----------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DEVIN_OUTPOST_GATEWAY_URL` | Ja | Base-URL des Outpost-Gateways, z. B. `wss://outpost-gateway.devin.ai`. | | `DEVIN_OUTPOST_CONNECT_TOKEN` | Ja | Bearer-Connect-Token für das Gateway aus der Claim-Antwort. | | `DEVIN_OUTPOST_SESSION_ID` | Ja | Die Sitzungs-ID, die bedient wird. Alle drei Variablen `DEVIN_OUTPOST_*` müssen gemeinsam gesetzt werden. | | `DEVIN_REMOTE_STATE_DIR` | Dringend empfohlen | Zustandsverzeichnis pro Sitzung, in dem das Remote seine Anmeldedaten, Tokens und Shell-Integrationsdateien speichert. Verwenden Sie für jede Sitzung ein eigenes Verzeichnis (z. B. `~/.devin/worker/sessions/`, was auch `devin worker` verwendet). Wenn diese Variable nicht gesetzt ist, greift das Remote auf einen gemeinsamen systemweiten Standard zurück (`/opt/.devin` unter Linux, `~/.devin` unter macOS, `C:\ProgramData\devin` unter Windows). Dieser muss dann vorhanden und beschreibbar sein — und dabei werden sitzungsspezifische Zustände über parallele Sitzungen hinweg offengelegt. Setzen Sie diese Variable immer. | | `DEVIN_CHROME_PATH` | Optional | Pfad zu einer Chrome-/Chromium-Binärdatei auf dem System für das Browser-Tool (auf Outposts gibt es kein von Devin verwaltetes Chrome). | | `DEVIN_OUTPOST_DESKTOP` | Optional | Auf `true` setzen, um den Desktop-(VNC-)Stream zu aktivieren. Auf der Remote-Seite wird er nur bei Bedarf aktiviert — es wird nichts erfasst, bis sich ein Viewer verbindet — daher kann er bedenkenlos immer aktiviert sein. | Geben Sie dem Remote eine saubere Umgebung, die nur die oben genannten Variablen sowie grundlegende Systemvariablen enthält (`PATH`, `HOME`, `USER`, `LOGNAME`, `TMPDIR`, `LANG`, `TZ` und — für die Bildschirmaufnahme des Desktop-Streams unter Linux/X11 — `DISPLAY`, `WAYLAND_DISPLAY`, `XAUTHORITY`). Geben Sie nichts an das Remote weiter, was der Agent nicht sehen können soll: Es wird von der Shell des Agenten vererbt. Zusätzliche Lifecycle-Erwartungen: * **Arbeitsverzeichnis**: Starten Sie das Remote in dem Verzeichnis, das die Repositories der Sitzung enthält (dieselbe Regel wie bei `devin worker start`). * **Sitzungsende**: Wenn die Sitzung endet (in den sleep-Zustand wechselt oder beendet wird), benachrichtigt Devin das Remote und es beendet sich selbst mit Status 0. Behandeln Sie einen sauberen Exit als Ende der Sitzung: Bestätigen Sie, dass `status.session_status` des Warteschlangeneintrags `suspended` oder `terminated` ist (die Statusaktualisierung kann dem Exit um einige Sekunden hinterherhinken, lesen Sie also einige Male erneut), und geben Sie dann den Claim frei. Als Fallback pollen Sie `status.session_status` auch, während das Remote läuft, und beenden den Prozess selbst, sobald es `terminated` erreicht (oder der Warteschlangeneintrag verschwindet).