> ## 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. # Devin Outposts API および CLI リファレンス > セルフホスト型ワーカー向けの Devin Outposts リファレンス: devin-remote、fleet API エンドポイント、CLI フラグ、バイナリのダウンロード、spawn 仕様。 Outposts の関連機能全体を網羅したリファレンスです。ワーカー CLI、fleet API、`devin-remote` バイナリの配布、およびカスタム オーケストレーター向けの spawn 仕様を扱います。
## 認証
ワーカーとオーケストレーターは、サービスユーザーに属する [v3 API token](/ja/api-reference/v3/overview) を使って認証します。サービスユーザーに割り当てられたロールによって、トークンに付与される Outposts のスコープが決まります。 | ロール権限 | トークンスコープ | 付与内容 | | ----------------------------------- | ------------------------ | ------------------------------------------ | | **Outpostsの読み取り** (`ReadOutposts`) | `account.outposts.read` | Outpostsの一覧表示とセッションキューの読み取り | | **Outpostsの書き込み** (`WriteOutposts`) | `account.outposts.write` | セッションの引き取りと解放、Outpostsの作成と削除 (読み取りスコープを含む) | 以前の `account.outposts.machine` および `account.outposts.orchestrator` スコープは非推奨です。これらが付与されたロールは引き続き機能します (どちらも 書き込みスコープを含みます) が、新しいロールでは **Outpostsの読み取り** / **Outpostsの 書き込み** を使用してください。 Outposts は **account** にスコープされ、その配下のすべての組織で共有されます。 `devin worker start` は、既存の CLI ログインを使用すれば、事前にプロビジョニングされたトークンなしでも実行できます。詳細は[トークンなしで開始する](#starting-without-a-token)を参照してください。
## CLI
### `devin worker start`
アウトポストのキューをポーリングしてセッションを引き取り、適切な `devin-remote` バイナリをダウンロードして、セッションを処理します。セッションで作業するディレクトリで実行します。セッションのリポジトリはそのディレクトリの `repos` サブディレクトリに配置されるため、`your-org/app` は `$(pwd)/repos/app` にチェックアウトされます。すでに存在するリポジトリは再利用され、不足しているリポジトリはセッション開始時にクローンされます。 ```bash theme={null} devin worker start --outpost= ``` | フラグ | 環境変数 | 説明 | | ---------------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------- | | `--outpost` | — | 名前または ID で指定したこのアウトポストのセッションだけを引き取ります。対話型ターミナルで省略した場合、ワーカーがアカウント内のアウトポストから選択を求めます。 | | `--session` (alias `--session-id`) | — | 特定の1つのセッションを引き取って処理し、その後終了します。 | | `--acceptor-id` | `DEVIN_WORKER_ACCEPTOR_ID` | 引き取り、更新、再起動後の復旧に使う安定したワーカー ID です。既定では、ワーカーデータディレクトリ配下に保存される生成済み ID が使われます。複数のマシンで同じものを共有しないでください。 | | `--token` | `DEVIN_OUTPOSTS_TOKEN` | ワーカー用の認証トークンです。任意です。どちらも未設定の場合、ワーカーは CLI ログインにフォールバックします ([トークンなしで開始する](#starting-without-a-token)を参照) 。 | | `--once` | — | キューに戻らず、1つのセッションを処理したら終了します。 | | `--api-url` | `DEVIN_API_URL` | Devin API のベース URL です。既定値は `https://api.devin.ai` です。 | | `--cache-dir` | `DEVIN_WORKER_CACHE_DIR` | ダウンロードした `devin-remote` バイナリをキャッシュするディレクトリです。既定値は `~/.devin/worker/cache` です。 | | `--static-base-url` | `DEVIN_WORKER_STATIC_BASE_URL` | `devin-remote` バイナリの公開先となるベース URL です。 | | `--gateway-url` | `DEVIN_OUTPOST_GATEWAY_URL` | 引き取りレスポンスに含まれない場合に使われるアウトポストゲートウェイ URL のフォールバックです。 | | `--remote-binary-sha` | `DEVIN_WORKER_REMOTE_SHA` | セッションで固定されていない場合に使うフォールバックの `devin-remote` git SHA です。どちらも設定されていない場合は、最新の公開済み SHA が使われます。 | | `--pty-bridge-port` | `DEVIN_PTY_BRIDGE_PORT` | 固定の PTY bridge port です。既定では、セッションごとに割り当てられる空きポートが使われます。 | | `--poll-interval-secs` | — | キューのポーリングとセッションのステータス確認の間隔 (秒) です。既定値は `5` です。 | ワーカーの環境には、ブラウザ機能で使用する Chrome/Chromium バイナリをセッションに指定するための `DEVIN_CHROME_PATH` を含めることもできます。
#### トークンを指定せずに起動する
事前にプロビジョニングされたアウトポストトークンは必要ありません。`--token` と `DEVIN_OUTPOSTS_TOKEN` のいずれも指定しない場合、`devin worker start` は既存のCLIログインを使用してアウトポストを作成し、以降の実行では保存されたワーカートークンを再利用します。
#### プラットフォームの検証
ワーカーはマシンの OS がアウトポストのプラットフォームと一致するか確認します。不一致の場合は、キューに入ったセッションの引き取りと解放を繰り返すのではなく、明確なメッセージを表示して終了します。 Windows x64 マシンに対応しています。ワーカーは適切な `devin-remote` バイナリをダウンロードし、Windows のシステム環境変数をセッションに引き渡します。
### `devin worker outpost create`
アウトポストを作成します。アウトポストは、インフラストラクチャ上で提供されるセッションの名前付きキューです。write スコープが必要です。 ```bash theme={null} devin worker outpost create --platform --description "..." ``` | 引数 / フラグ | 説明 | | --------------- | -------------------------------------------- | | `` | アカウントごとに一意なアウトポスト名。例: `rhel`、`gpu-h200`。 | | `--platform` | マシンのプラットフォーム: `linux`、`macos`、または `windows`。 | | `--description` | Webアプリに表示される、人が読める形式の説明。 | 新しいアウトポストの ID (`outpost_env-...`) を出力します。アウトポストは、Webアプリの **Settings → Environment → Outposts** から作成することもできます。
### `devin worker outpost delete`
アウトポストを削除します。write スコープが必要です。 ```bash theme={null} devin worker outpost delete ```
## Fleet API
すべてのエンドポイントは `https://api.devin.ai/opbeta/outposts/` 配下にあり、Bearer トークンを受け付けます： ```bash theme={null} curl -H "Authorization: Bearer $DEVIN_API_TOKEN" ... ``` リソースは Kubernetes スタイルの `metadata` / `spec` / `status` という構造に従っており、キューは Kubernetes の list-then-watch セマンティクスに従い、少なくとも 1 回の配信を保証します。
### オブジェクト
#### キューエントリ (`devins`)
キューに入っている各セッションは、1 つのキューエントリとして表現されます。 | Field | 説明 | | ------------------------ | ----------------------------------------------------------------------- | | `metadata.session_id` | セッション (devin) の ID。 | | `metadata.outpost_id` | セッションがキューに入っているアウトポスト。 | | `metadata.created_at` | セッションがキューに追加された日時 (Unix タイムスタンプ) 。 | | `metadata.updated_at` | このオブジェクトが最後に変更された日時 (Unix タイムスタンプ) 。 | | `spec.kind` | `new` または `resume`。 | | `spec.platform` | マシンのプラットフォーム。例: `linux`。 | | `spec.remote_binary_sha` | ワーカーが実行する `devin-remote` バイナリの短縮 commit SHA。`null` はワーカーのデフォルトを意味します。 | | `spec.network_policy` | セッションに実効的に適用されるネットワークポリシー (下記参照) 。 | | `status.phase` | キューのフェーズ: `pending` または `claimed`。 | | `status.acceptor_id` | `claimed` の場合に、現在引き取りを保持しているワーカー。 | | `status.claim_deadline` | 現在の引き取りが期限切れとなり、セッションがキューに戻る日時。 | | `status.session_status` | 基になるセッションのおおまかなステータス: `pending`、`running`、`suspended`、または `terminated`。 | | `status.connect_token` | ゲートウェイ接続トークン。引き取りが成功した場合にのみ返されます。 | | `status.gateway_url` | アウトポストゲートウェイの公開 WebSocket URL。引き取りが成功した場合にのみ返されます。 | `spec.network_policy` は、セッションのネットワークアクセスが制限されているかどうか (`enabled`) と、許可される宛先 (`allow`) を示します。宛先には、hostname の glob パターン (`{"hostname": ...}`) 、IPv4 アドレス/CIDR (`{"ipv4": ...}`) 、または IPv6 アドレス/CIDR (`{"ipv6": ...}`) があります。ポリシーはセッションを管理する[セキュリティプロファイル](/ja/product-guides/security-profiles#outposts-and-profiles)に由来します。各マシンでこれを適用する責任はアウトポストオペレーターにあります。
#### アウトポスト
| フィールド | 説明 | | ---------------------- | ---------------------------------------- | | `metadata.outpost_id` | アウトポスト ID (`outpost_env-...`) 。 | | `metadata.account_id` | アウトポストを所有するアカウント。 | | `metadata.created_at` | アウトポストの作成日時 (Unix タイムスタンプ) 。 | | `spec.name` | アカウント内で一意なアウトポスト名。 | | `spec.platform` | マシンプラットフォーム。`null` はデフォルトのプラットフォームを示します。 | | `spec.description` | 人が読める形式の説明。 | | `status.queue_depth` | キュー内で保留中の (まだワーカーに確保されていない) セッション数。 | | `status.active_claims` | ワーカーが保持している、期限切れでない claim の数。 |
### キュー内のセッションを一覧表示
``` GET /opbeta/outposts/devins ``` | クエリパラメータ | 説明 | | ------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `outpost` | アウトポスト ID で絞り込みます。一覧と watch の両方に適用されます。 | | `phase` | キューのフェーズ (`pending` または `claimed`) で絞り込みます。watch 時は無視されます。 | | `acceptor_id` | セッションを引き受けたワーカーで絞り込みます。watch 時は無視されます。 | | `first` | 一覧の 1 ページあたりの最大行数です。1～200。デフォルトは 100 です。 | | `cursor` | 以前の一覧レスポンスまたは watch イベントで取得した不透明なカーソルです (この 2 つは相互に利用できます) 。一覧では、この位置以降の行を返します。watch では、ライブの変更のストリーミングを開始する前に、この位置より後の変更を再生します。 | | `watch` | 一覧の代わりに、変更を SSE としてストリーミングします。 | レスポンス例: ```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 } ``` ページネーションと配信のセマンティクス: * `has_next_page` が `true` の間は、各レスポンスの `cursor` を次のリクエストに渡します。 * 配信は少なくとも1回行われます。ページ境界にあるセッションは両方のページに現れる可能性があるため、すべての項目を新規として扱うのではなく、`metadata.session_id` でエントリをアップサートしてください (claim CAS により重複は問題になりません) 。 * `has_next_page` が `false` になったら、返された `cursor` を watch の開始位置として保存します。
### 変更の監視
``` GET /opbeta/outposts/devins?watch=true&cursor= ``` Server-Sent Events をストリーム配信します。`MODIFIED` イベントはセッションのキューエントリが変更されたときに発生し (新たにキューに追加されたセッションも `MODIFIED` として届きます) 、`DELETED` イベントはキューエントリが削除されたときに発生します。各 SSE の `data` フィールドには次が含まれます: ```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 のセマンティクス: * 各イベントの最上位の `cursor` は、処理後に永続化してください。切断中に発生した変更を再生するには、再接続時に最後に永続化した `cursor` を使います。 * 配信は at-least-once です。重複するイベントを許容してください。 * ストリームは最長 5 分で終了するため、再接続を前提とした watch ループが必要です。 * `watch=true` の場合、`phase` と `acceptor_id` のフィルタは無視されます。watch 対象のイベントは、各イベントの `object` に含まれるフィールドを使って絞り込んでください。 * `cursor` を省略すると先頭から開始されるため、通常の整合には list-then-watch を利用してください。
### キューエントリを取得
``` GET /opbeta/outposts/devins/{session_id} ``` 1 つのセッションのキューエントリを返します。
### セッションを引き取る
``` POST /opbeta/outposts/devins/{session_id}/claim ``` ```json theme={null} { "acceptor_id": "worker-1" } ``` 指定されたワーカー識別情報に対して、このセッションをアトミックに引き取ります。別のワーカーが先に引き取っていた場合、このリクエストは `409` で失敗します。引き取りに成功したレスポンスには、`status.connect_token` と `status.gateway_url` が含まれます。これらは、`devin-remote` が接続するために必要な認証情報です ([spawn contract](#spawn-contract) を参照) 。 セッションを引き取ると、サーバーが割り当てた引き取り期限 (`status.claim_deadline`) までにワーカーの準備が整うことが前提となります。期限切れになった引き取りは、自動的にキューに戻されます。
### 引き取りを解除する
``` POST /opbeta/outposts/devins/{session_id}/release ``` ```json theme={null} { "acceptor_id": "worker-1" } ``` ワーカーによる取得を解除し、セッションを直ちにキューに戻します (たとえば、プロビジョニングに失敗した場合) 。
### Outposts
``` GET /opbeta/outposts # アウトポストの一覧取得 POST /opbeta/outposts # アウトポストの作成 GET /opbeta/outposts/{outpost_id} # アウトポストの取得 DELETE /opbeta/outposts/{outpost_id} # アウトポストの削除 ``` 作成時のリクエストボディ: ```json theme={null} { "name": "my-outpost", "platform": "linux", "description": "Dev boxes in our VPC" } ``` 作成と削除にはwrite スコープが必要で、取得と一覧取得には読み取りスコープが必要です。各アウトポストのレスポンスには現在の `status.queue_depth` と `status.active_claims` が含まれます。
### オペレーターメッセージを送信する
``` POST /opbeta/outposts/devins/{session_id}/operator-message ``` ```json theme={null} { "message": "Scheduled maintenance: workers restart at 5pm UTC." } ``` 対象のセッションに**アウトポストオペレーターからのメッセージ**バナーを表示します。インフラストラクチャの問題やメンテナンス時間帯の告知に利用できます。write スコープが必要です。 ```bash theme={null} curl -X POST "https://api.devin.ai/opbeta/outposts/devins//operator-message" \ -H "Authorization: Bearer $DEVIN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"message": "Scheduled maintenance: workers restart at 5pm UTC."}' ``` 動作: * 呼び出すたびに前のメッセージが**置き換えられ**、セッションには常に最新のメッセージのみが表示されます。 * **空文字列** (`{"message": ""}`) を送信すると、バナーがクリアされます。 * メッセージはプレーンテキストとして表示されます (最大2,000文字。これを超えるメッセージは`422`バリデーションエラーで拒否されます) 。HTMLとMarkdownは解釈されません。 * 不明なセッションID、別のアカウントのアウトポスト上のセッション、終了したセッションでは`404`が返されます。 * **レート制限:** セッションごとに新しいメッセージを送信できるのは30秒に1件です (超過した場合は`429`) 。空文字列によるクリアは常に許可されます。 レスポンス: ```json theme={null} { "session_id": "devin-...", "message": "Scheduled maintenance: workers restart at 5pm UTC." } ```
## リモートバイナリの配布
`devin worker start` コマンドは、適切な `devin-remote` バイナリを自動的にダウンロードします。Devin CLI を利用しないカスタムオーケストレーターは、以下から直接入手できます。 ``` https://static.devin.ai/devin-rs/remote/ ``` **最新バージョンを確認する:** ```bash theme={null} # お使いのプラットフォーム向けに公開された最新バイナリのgit SHAを返します curl -fsSL "https://static.devin.ai/devin-rs/remote/latest_linux_x64" ``` **ダウンロードして検証する:** ```bash theme={null} SHA=$(curl -fsSL "https://static.devin.ai/devin-rs/remote/latest_linux_x64") # バイナリをダウンロードする curl -fL "https://static.devin.ai/devin-rs/remote/devin-remote_${SHA}_linux_x64" \ -o devin-remote # チェックサムをダウンロードして検証する 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 ``` **利用可能なプラットフォーム：** | 接尾辞 | OS / アーキテクチャ | | ----------------- | ------------------- | | `linux_x64` | Linux x86\_64 | | `linux_arm64` | Linux aarch64 | | `macos_arm64` | macOS Apple Silicon | | `windows_x64.exe` | Windows x86\_64 | セッションのキューエントリに `spec.remote_binary_sha` が含まれている場合は、`latest` の代わりにその SHA を利用します。これにより、セッションはテスト済みの特定のバージョンに固定されます。
## spawn 仕様
オーケストレーターが `devin worker start` を使わずに `devin-remote` を直接起動する場合は、次のように起動してください: ```bash theme={null} devin-remote serve ``` 以下の環境変数を設定します。 | Variable | Required | Description | | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DEVIN_OUTPOST_GATEWAY_URL` | はい | アウトポストゲートウェイのベース URL。例: `wss://outpost-gateway.devin.ai`。 | | `DEVIN_OUTPOST_CONNECT_TOKEN` | はい | 引き取りレスポンスで返される、ゲートウェイ用の Bearer 接続トークン。 | | `DEVIN_OUTPOST_SESSION_ID` | はい | 対象のセッション ID。`DEVIN_OUTPOST_*` の 3 つの変数は必ずセットで設定してください。 | | `DEVIN_REMOTE_STATE_DIR` | 強く推奨 | リモートが認証情報、トークン、シェル統合ファイルを保存する、セッションごとの状態ディレクトリです。セッションごとに一意のディレクトリを使用してください (例: `~/.devin/worker/sessions/`。これは `devin worker` が利用するパスです) 。未設定の場合、リモートは共有のシステム全体のデフォルト (Linux では `/opt/.devin`、macOS では `~/.devin`、Windows では `C:\ProgramData\devin`) にフォールバックします。その場合、そのディレクトリは存在していて書き込み可能である必要があり、さらに同時実行中のセッション間でセッションごとの状態が漏洩します。必ず設定してください。 | | `DEVIN_CHROME_PATH` | 任意 | ブラウザツール用の、そのマシン上にある Chrome/Chromium バイナリへのパスです (Outposts には Devin が管理する Chrome はありません) 。 | | `DEVIN_OUTPOST_DESKTOP` | 任意 | デスクトップ (VNC) ストリームを有効にするには `true` に設定します。これはリモート側で遅延起動するため、ビューアが接続するまで何もキャプチャされません。そのため、常に有効にしておいても安全です。 | リモートには、上記の変数に加えて、基本的なシステム変数 (`PATH`、`HOME`、`USER`、`LOGNAME`、`TMPDIR`、`LANG`、`TZ`、および Linux/X11 でデスクトップストリームの画面キャプチャに必要な `DISPLAY`、`WAYLAND_DISPLAY`、`XAUTHORITY`) のみを含むクリーンな環境を渡してください。エージェントが見るべきでない情報をリモートに漏らさないでください。これらはエージェントのシェルに引き継がれます。 追加のライフサイクル上の想定事項: * **作業ディレクトリ**: セッションで作業させるディレクトリからリモートを起動してください。リポジトリはその `repos` サブディレクトリ、すなわち `$(pwd)/repos/` の下にあります (`devin worker start` と同じルールです) 。 * **セッション終了**: セッションが終了したとき (スリープに入るか終了したとき) 、Devin はリモートに通知し、リモートは自動的に終了ステータス 0 で終了します。正常終了はセッション終了として扱ってください。キューエントリの `status.session_status` が `suspended` または `terminated` であることを確認し (ステータス更新は終了の数秒後になることがあるため、数回読み直してください) 、その後引き取りを解放します。フォールバックとして、リモートの実行中も `status.session_status` をポーリングし、`terminated` に達した時点 (またはキューエントリが消えた時点) でプロセスを自分で終了してください。