Outpostsは早期アクセス版です。ここで説明するAPIとCLIコマンドは変更される可能性があります。
組織でOutpostsを有効にするには、担当のアカウントチームにお問い合わせください。
- セッションを自社ネットワーク内で実行し、社内サービス、レジストリ、シークレットの近くで動かしたい
- カスタムのハードウェアプロファイル (例: GPU、大容量メモリマシン、特定のOSイメージ) が必要
- 既存の開発環境、VM、またはKubernetesインフラストラクチャでDevinのワークロードをホストしたい
- ネットワークアクセス、ビルド出力、モニタリングに対するEnterprise向けの制御機能が必要
仕組み
-
ワーカー (例:
devin worker start) — キューに入っている 1 つのセッションを処理するために、マシン上で実行するバイナリです。Devin のクラウドへのアウトバウンド接続を確立し、セッションのツール呼び出しをローカルで実行します。このバイナリは Cognition が提供するため、自分で実装する必要はありません。Devin CLI には、このバイナリを取得して実行するためのロジックが含まれています。 - オーケストレーター — 利用者が作成するソフトウェア (または調整して使う参照実装) です。fleet API を監視して ワーカー を待機中のセッションを見つけ、セッションごとに VM またはコンテナをプロビジョニングし、その中で ワーカー を起動します。Kubernetes などの一般的なプラットフォーム向けに、いくつかの参照実装を提供していますが、これらは自由に調整して利用したり (オープンソースです!)、独自に作成したりできます。
前提条件
- Outposts が有効化されている組織
- 適切な Outposts スコープを持つ v3 APIトークン:
- outposts を管理するオーケストレーター向けの
account.outposts.orchestrator(マシンスコープを含む) - キューの読み取りとセッションの引き取り・解放を行うワーカー向けの
account.outposts.machine
- outposts を管理するオーケストレーター向けの
- 以下を備えたマシンイメージ (VM またはコンテナ) :
- Devin CLI がインストールされている
- 以下の マシンの依存関係
- リポジトリがクローンされ、リモートが設定されている
- セッションに必要なビルドツール、パッケージレジストリ、シークレット、内部サービスにアクセスできる
マシンの依存関係
任意 — 特定の機能を有効にするには、以下をインストールしてください。
クイックスタート: アウトポストを作成してワーカーを起動する
devin worker start を使って 1 台のマシン上にアウトポストを作成し、運用します。オーケストレーターは不要です。これは開発用マシンで Outposts を試す最も手早い方法であり、大規模運用ではオーケストレーターも同じワーカーコマンドを実行します。
1. サービスユーザー トークンを作成する
UseOutpostsMachine → account.outposts.machine、ManageOutpostsOrchestrator → account.outposts.orchestrator) が付与されます。Devin の web app で次を行います。
- Outposts へのアクセス権を持つ ロールを作成 します。Settings → Roles で Enterprise ロールを追加し、Outpost permissions で Use outpost machine (
UseOutpostsMachine) を有効にします。このサービスユーザーがアウトポストを作成または削除する場合は、Manage outposts (ManageOutpostsOrchestrator) も有効にします。 - サービスユーザーをプロビジョニングします。 Settings → Devin API → Service users で Provision service user をクリックし、名前 (例:
outposts-worker) を付け、手順 1 で作成したロールを割り当てて、有効期限を設定します。 - トークンをコピーします。
cog_...トークンは作成時に 一度だけ 表示されます。今すぐコピーしてください。後から取得することはできません。
2. アウトポストを作成する
outpost_env-...) が表示されます。次のステップで使うので、控えておいてください。アウトポストは、Webアプリの Settings → Outposts から、または outposts API 経由でも作成できます。
作成したアウトポストは、セッション開始時に、Devin Cloud のマシンオプションとして (Ubuntu や Windows などと並んで) 表示されます。
3. ワーカーを起動する
devin-remote バイナリをダウンロードして、そのセッションを実行します。セッションが終了すると、キューに戻って次のセッションを待機します。代わりに、1 つのセッションを実行したら終了するには --once を、特定の 1 つのセッションを引き取って実行するには --session=<session_id> を指定します。
--token と DEVIN_OUTPOSTS_TOKEN の両方が未設定の場合、コマンドはエラーになります。対話型ターミナルで --outpost を省略すると、ワーカーはアカウントのアウトポストから選択するよう求めます。
4. アウトポストでセッションを開始する
Kubernetes 上で実行していますか? オープンソースの
devin-outpost-k8s
オペレーターは Helm でインストールでき、任意の認定済み
クラスター (GKE、EKS、…) 上でアウトポスト用のワーカーを実行できます。そのリポジトリをクローンした環境から、次を実行します。
基本的な流れ
1. アウトポストを登録する
rhel、gpu-h200、my-outpost など) 。devin worker outpost create を使って作成します。
fleet API では、アウトポスト は
outposts リソースとして表され、
アカウント単位でスコープされます (所属するすべての組織で共有されます) 。2. fleet APIをポーリングして待機中のセッションを確認する
items に格納されます:
first をページサイズ (最大 200) に設定し、その後、
has_next_page が true の間は各レスポンスの cursor を次のリクエストに
渡します:
metadata.session_id でエントリをアップサートしてください。has_next_page が false になったら、返されたカーソルを watch API の開始位置として保存してください。
変更を監視する
MODIFIED イベントを送信し、
削除されると DELETED イベントを送信します。新たにキューに入ったセッションも
MODIFIED イベントとして届きます。各 SSE data フィールドには、次の形式の JSON が含まれます:
cursor を保存してください。接続が
切れた場合は、最後に保存したカーソルで再接続し、切断中に発生した
変更を再取得します。watch の配信も少なくとも 1 回であるため、クライアントは
重複イベントを許容する必要があります。ストリームは最長 5 分で終了する
ため、再接続する watch ループを前提としています。
outpost フィルターは list リクエストと watch リクエストの両方に適用されます。phase と
acceptor_id のフィルターは list リクエストにのみ適用され、watch=true の場合は
無視されます。watch しているイベントは、各イベントの object にあるフィールドを使って
絞り込んでください。カーソルを省略すると先頭から開始されるため、
通常の整合処理には list-then-watch を利用してください。
セッション用のマシンを起動する前に、他のワーカーに取得されないよう、アトミックに引き取ってください。acceptor_id を渡します。これは、ワーカーが自身で申告する識別情報です:
409 が返されます。引き取りを行うと、サーバーによって割り当てられた引き取り期限 (status.claim_deadline) までにワーカーの準備が整うことが保証されます。期限切れになった引き取りは自動的にキューに戻されます。プロビジョニングに失敗した場合は、引き取りを解放してセッションがただちにキューに戻るようにしてください:
3. マシンを起動してワーカーを実行する
devin worker start を実行する作業ディレクトリを基準とした相対パスでチェックアウトされている必要があります。
repos
app
.git
infra
.git
repos/ で devin worker start を実行すると、セッションは作業ディレクトリからの相対パスとして app/ と infra/ を認識します。
便利なフラグ:
使用例:
4. リモートバイナリを直接取得する
devin worker start コマンドは、適切な devin-remote バイナリを自動的にダウンロードします。Devin CLI を利用しないカスタムオーケストレーターを構築する場合は、次の場所からバイナリを直接取得できます。
セッションのキューエントリに
spec.remote_binary_sha が含まれている場合は、latest ではなくその SHA を利用してください。これにより、セッションは特定のテスト済みバージョンに固定されます。
起動時の仕様
devin-remote を直接起動する場合は、次のようにします:
リモートには、上記の変数に加えて、基本的なシステム変数 (
PATH、HOME、USER、LOGNAME、TMPDIR、LANG、TZ、および Linux/X11 でデスクトップストリームの画面キャプチャに必要な DISPLAY、WAYLAND_DISPLAY、XAUTHORITY) だけを含むクリーンな環境を渡してください。エージェントに見せるべきでないものは、リモートに漏らさないでください。これらはエージェントの Shell に引き継がれます。
追加のライフサイクルに関する前提:
- 作業ディレクトリ: セッションのリポジトリを含むディレクトリからリモートを起動します (
devin worker startと同じルールです) 。 - セッション終了: セッションが終了したとき (sleep 状態になる、または終了する) 、Devin はリモートに通知し、リモートは自動的にステータス 0 で終了します。正常終了はセッション終了として扱ってください。キューエントリの
status.session_statusがsuspendedまたはterminatedであることを確認し (ステータス更新は終了から数秒遅れることがあるため、数回読み直してください) 、その後 引き取りを解放します。フォールバックとして、リモートの実行中にもstatus.session_statusをポーリングし、terminatedに達した時点 (またはキューエントリが消えた時点) で自分でプロセスを終了してください。
5. ワーカーの終了時にマシンを終了する
devin worker start が終了すると、セッションも終了するか、一時停止状態になります。VM またはコンテナを終了してください。outpost が再開に対応している場合は、セッション再開時に復元できるよう、終了前にマシンのスナップショットを作成してください。
オーケストレーターは、引き取ったセッションとその状態を追跡できます。
status.session_status として pending、running、suspended、または terminated を返します。
中央集約なしのスケジューリング
約16台を超えるコーディネーター (outpost を監視して引き取るワーカーまたはオーケストレーター) を実行する予定がある場合は、まず担当のアカウントチームにご連絡ください。大規模なフリートでは引き取り競合とキュー読み取り負荷が増大するため、その規模に対応できるよう outpost が適切にプロビジョニングされていることを事前に確認したいからです。
- 調整の仕組みは引き取りだけです。 すべてのワーカーはそれぞれ独立してキューを監視し、保留中のセッションの引き取りを競います。引き取りはサーバー上で原子的に実行される compare-and-swap です。勝てるワーカーは必ず1台だけで、負けたワーカーは
409を受け取り、そのまま次の保留中セッションに進みます。引き取り競争に負けるのはエラーではなく、通常の動作です。 - 各ワーカーは固有の ID を持ちます。
acceptor_idによって、そのワーカーの引き取り、更新、再起動後の復旧は、そのワーカー自身にのみ紐づけられます。devin worker startはマシンごとにこれを自動生成して保存するため、フリート側で ID を設定する必要はありません。マシン間で acceptor ID (またはコピーしたワーカーデータディレクトリ) を共有しないでください。ワーカー同士が衝突し、互いの引き取りを奪い合う原因になります。 - 障害は自動的に回復します。 ワーカーが引き取り後に停止した場合でも、引き取り期限 に達するとその引き取りは失効し、セッションは別のワーカーが取得できるようキューに戻ります。フリート全体のヘルス状態を追跡する必要はありません。
- 完全な一覧を何度も取得するのではなく、watch エンドポイントを利用してください。 まずページネーション付きの一覧取得を1回実行して初期状態を構築し、その後は返された カーソル から watch stream を維持してください。すべてのワーカーがキュー全体を再ポーリングするとスケールしにくくなり、引き取りの遅延も増えます。watch stream であれば、変更を発生時に受け取れます。
- 1つの outpost で約16台を超える前にご相談ください。 調整不要の引き取りは小規模なフリートではうまく機能しますが、フリートが大きくなるほど引き取り競合とキュー読み取り負荷が増大します。単一の outpost に対して約16台を超えるワーカーを実行する予定がある場合は、まず担当のアカウントチームにご連絡ください。その規模に対応できるよう、outpost が適切にプロビジョニングされていることを確認します。
API リファレンス
https://api.devin.ai/opbeta 配下にあり、共通のリソース形式 (metadata / spec / status) を持ちます。一覧レスポンスは items、cursor、has_next_page、total を返します。
Devins (/outposts/devins)
Outposts (/outposts)
status.queue_depth と status.active_claims は、オートスケーリングの判断に役立つシグナルです。キューに処理待ちが溜まっている場合、オーケストレーターはウォームマシンをさらにプロビジョニングできます。

