リファレンス

Outposts の関連機能全体を網羅したリファレンスです。ワーカー CLI、fleet API、devin-remote バイナリの配布、およびカスタムオーケストレーター向けの spawn 仕様を扱います。

認証

ワーカーとオーケストレーターは、サービスユーザーに属する v3 API token を使って認証します。サービスユーザーに割り当てられたロールによって、トークンに付与される Outposts のスコープが決まります。

ロール権限	トークンスコープ	付与内容
アウトポストのマシンを利用する (`UseOutpostsMachine`)	`account.outposts.machine`	キューの読み取り、セッションの引き取りと解放
アウトポストを管理する (`ManageOutpostsOrchestrator`)	`account.outposts.orchestrator`	アウトポストの作成と削除 (マシンスコープを含む)

Outposts は account にスコープされ、その配下のすべての組織で共有されます。

CLI

`devin worker start`

アウトポストのキューをポーリングしてセッションを取得し、適切な devin-remote バイナリをダウンロードして、セッションを処理します。セッション用にチェックアウトされたリポジトリがあるディレクトリで実行します。

devin worker start --outpost=<outpost_id>

フラグ	環境変数	説明
`--outpost`	—	このアウトポストのセッションだけを引き取ります。対話型ターミナルで省略した場合、ワーカーがアカウント内のアウトポストから選択を求めます。
`--session` (alias `--session-id`)	—	特定の1つのセッションを引き取って処理し、その後終了します。
`--acceptor-id`	`DEVIN_WORKER_ACCEPTOR_ID`	引き取り、更新、再起動後の復旧に使う安定したワーカー ID です。既定では、ワーカーデータディレクトリ配下に保存される生成済み ID が使われます。複数のマシンで同じものを共有しないでください。
`--token`	`DEVIN_OUTPOSTS_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`	引き取りレスポンスに含まれない場合に使われるアウトポスト gateway 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 を含めることもできます。

`devin worker outpost create`

アウトポストを作成します。アウトポストは、インフラストラクチャ上で提供されるセッションの名前付きキューです。orchestrator スコープが必要です。

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

引数 / フラグ	説明
`<name>`	アカウントごとに一意なアウトポスト名。例: `rhel`、`gpu-h200`。
`--platform`	マシンのプラットフォーム: `linux`、`macos`、または `windows`。
`--description`	Webアプリに表示される、人が読める形式の説明。

新しいアウトポストの ID (outpost_env-...) を出力します。アウトポストは、Webアプリの Settings → Environment → Outposts から作成することもできます。

`devin worker outpost delete`

アウトポストを削除します。orchestrator スコープが必要です。

devin worker outpost delete <outpost_id>

Fleet API

すべてのエンドポイントは https://api.devin.ai/opbeta/outposts/ 配下にあり、Bearer トークンを受け付けます：

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` の場合に、現在 claim を保持しているワーカー。
`status.claim_deadline`	現在の claim が期限切れとなり、セッションがキューに戻る日時。
`status.session_status`	基になるセッションのおおまかなステータス: `pending`、`running`、`suspended`、または `terminated`。
`status.connect_token`	ゲートウェイ接続トークン。claim が成功した場合にのみ返されます。
`status.gateway_url`	アウトポストゲートウェイの公開 WebSocket URL。claim が成功した場合にのみ返されます。

spec.network_policy は、セッションのネットワークアクセスが制限されているかどうか (enabled) と、許可される宛先 (allow) を示します。宛先には、hostname の glob パターン ({"hostname": ...}) 、IPv4 アドレス/CIDR ({"ipv4": ...}) 、または IPv6 アドレス/CIDR ({"ipv6": ...}) があります。

アウトポスト

フィールド	説明
`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 としてストリーミングします。

レスポンス例:

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

Server-Sent Events をストリーム配信します。MODIFIED イベントはセッションのキューエントリが変更されたときに発生し (新たにキューに追加されたセッションも MODIFIED として届きます) 、DELETED イベントはキューエントリが削除されたときに発生します。各 SSE の data フィールドには次が含まれます:

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

{ "acceptor_id": "worker-1" }

指定されたワーカー識別情報に対して、このセッションをアトミックに引き取ります。別のワーカーが先に引き取っていた場合、このリクエストは 409 で失敗します。引き取りに成功したレスポンスには、status.connect_token と status.gateway_url が含まれます。これらは、devin-remote が接続するために必要な認証情報です (spawn contract を参照) 。セッションを引き取ると、サーバーが割り当てた引き取り期限 (status.claim_deadline) までにワーカーの準備が整うことが前提となります。期限切れになった引き取りは、自動的にキューに戻されます。

引き取りを解除する

POST /opbeta/outposts/devins/{session_id}/release

{ "acceptor_id": "worker-1" }

ワーカーによる取得を解除し、セッションを直ちにキューに戻します (たとえば、プロビジョニングに失敗した場合) 。

Outposts

GET    /opbeta/outposts/outposts                 # アウトポストの一覧取得
POST   /opbeta/outposts/outposts                 # アウトポストの作成
GET    /opbeta/outposts/outposts/{outpost_id}    # アウトポストの取得
DELETE /opbeta/outposts/outposts/{outpost_id}    # アウトポストの削除

作成時のリクエストボディ:

{
  "name": "my-outpost",
  "platform": "linux",
  "description": "Dev boxes in our VPC"
}

Create、GET、Delete には orchestrator スコープが必要で、各アウトポストのレスポンスには現在の status.queue_depth と status.active_claims が含まれます。

リモートバイナリの配布

devin worker start コマンドは、適切な devin-remote バイナリを自動的にダウンロードします。Devin CLI を利用しないカスタムオーケストレーターは、以下から直接入手できます。

https://static.devin.ai/devin-rs/remote/

最新バージョンを確認する:

# お使いのプラットフォーム向けに公開された最新バイナリのgit SHAを返します
curl -fsSL "https://static.devin.ai/devin-rs/remote/latest_linux_x64"

ダウンロードして検証する:

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
`macos_arm64`	macOS Apple Silicon
`windows_x64.exe`	Windows x86_64

セッションのキューエントリに spec.remote_binary_sha が含まれている場合は、latest の代わりにその SHA を利用します。これにより、セッションはテスト済みの特定のバージョンに固定されます。

spawn の仕様

オーケストレーターが devin worker start を使わずに devin-remote を直接起動する場合は、次のように起動してください:

devin-remote serve

以下の環境変数を設定します。

Variable	Required	Description
`DEVIN_OUTPOST_GATEWAY_URL`	はい	アウトポストゲートウェイのベース URL。例: `wss://outpost-gateway.devin.ai`。
`DEVIN_OUTPOST_CONNECT_TOKEN`	はい	claim レスポンスで返される、ゲートウェイ用の Bearer 接続トークン。
`DEVIN_OUTPOST_SESSION_ID`	はい	対象のセッション ID。`DEVIN_OUTPOST_*` の 3 つの変数は必ずセットで設定してください。
`DEVIN_REMOTE_STATE_DIR`	強く推奨	リモートが認証情報、トークン、シェル統合ファイルを保存する、セッションごとの状態ディレクトリです。セッションごとに一意のディレクトリを使用してください (例: `~/.devin/worker/sessions/<session_id>`。これは `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) のみを含むクリーンな環境を渡してください。エージェントが見るべきでない情報をリモートに漏らさないでください。これらはエージェントのシェルに引き継がれます。追加のライフサイクル上の想定事項:

作業ディレクトリ: セッションのリポジトリを含むディレクトリからリモートを起動してください (devin worker start と同じルールです) 。
セッション終了: セッションが終了したとき (スリープに入るか終了したとき) 、Devin はリモートに通知し、リモートは自動的に終了ステータス 0 で終了します。正常終了はセッション終了として扱ってください。キューエントリの status.session_status が suspended または terminated であることを確認し (ステータス更新は終了の数秒後になることがあるため、数回読み直してください) 、その後 claim を解放します。フォールバックとして、リモートの実行中も status.session_status をポーリングし、terminated に達した時点 (またはキューエントリが消えた時点) でプロセスを自分で終了してください。

概要

基本ガイドライン

Devin の導入

Devin の使い方

製品ガイド

統合

管理

リリースノート

認証

CLI

`devin worker start`

`devin worker outpost create`

`devin worker outpost delete`

Fleet API

オブジェクト

キューエントリ (`devins`)

アウトポスト

キュー内のセッションを一覧表示

変更の監視

キューエントリを取得

セッションを引き取る

引き取りを解除する

Outposts

リモートバイナリの配布

spawn の仕様

​認証

​CLI

​devin worker start

​devin worker outpost create

​devin worker outpost delete

​Fleet API

​オブジェクト

​キューエントリ (devins)

​アウトポスト

​キュー内のセッションを一覧表示

​変更の監視

​キューエントリを取得

​セッションを引き取る

​引き取りを解除する

​Outposts

​リモートバイナリの配布

​spawn の仕様

認証

CLI

`devin worker start`

`devin worker outpost create`

`devin worker outpost delete`

Fleet API

オブジェクト

キューエントリ (`devins`)

アウトポスト

キュー内のセッションを一覧表示

変更の監視

キューエントリを取得

セッションを引き取る

引き取りを解除する

Outposts

リモートバイナリの配布

spawn の仕様