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

# リファレンス

> CLI コマンド、fleet API エンドポイント、ワーカーの spawn 仕様

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

<div id="authentication">
  ## 認証
</div>

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

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

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

<div id="cli">
  ## CLI
</div>

<div id="devin-worker-start">
  ### `devin worker start`
</div>

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

```bash theme={null}
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` を含めることもできます。

<div id="devin-worker-outpost-create">
  ### `devin worker outpost create`
</div>

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

```bash theme={null}
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** から作成することもできます。

<div id="devin-worker-outpost-delete">
  ### `devin worker outpost delete`
</div>

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

```bash theme={null}
devin worker outpost delete <outpost_id>
```

<div id="fleet-api">
  ## Fleet API
</div>

すべてのエンドポイントは `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 回の配信を保証します。

<div id="objects">
  ### オブジェクト
</div>

<div id="queue-entry-devins">
  #### キューエントリ (`devins`)
</div>

キューに入っている各セッションは、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": ...}`) があります。

<div id="outpost">
  #### アウトポスト
</div>

| フィールド                  | 説明                                       |
| ---------------------- | ---------------------------------------- |
| `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 の数。            |

<div id="list-queued-sessions">
  ### キュー内のセッションを一覧表示
</div>

```
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 の開始位置として保存します。

<div id="watch-for-changes">
  ### 変更の監視
</div>

```
GET /opbeta/outposts/devins?watch=true&cursor=<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 を利用してください。

<div id="get-a-queue-entry">
  ### キューエントリを取得
</div>

```
GET /opbeta/outposts/devins/{session_id}
```

1 つのセッションのキューエントリを返します。

<div id="claim-a-session">
  ### セッションを引き取る
</div>

```
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`) までにワーカーの準備が整うことが前提となります。期限切れになった引き取りは、自動的にキューに戻されます。

<div id="release-a-claim">
  ### 引き取りを解除する
</div>

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

```json theme={null}
{ "acceptor_id": "worker-1" }
```

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

<div id="outposts">
  ### Outposts
</div>

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

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

```json theme={null}
{
  "name": "my-outpost",
  "platform": "linux",
  "description": "Dev boxes in our VPC"
}
```

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

<div id="remote-binary-distribution">
  ## リモートバイナリの配布
</div>

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

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

<div id="spawn-contract">
  ## spawn の仕様
</div>

オーケストレーターが `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` | はい       | 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` に達した時点 (またはキューエントリが消えた時点) でプロセスを自分で終了してください。