createos-deploy

CreateOS にデプロイする

ゲートウェイのウォレット認証 HTTP フローを使用します。ブラウザーセッションや OAuth は不要です。

デフォルトのゲートウェイ：https://mpp-createos.nodeops.network

支払いの再試行時にもデプロイする本文を正確に保持し、アップロードからシークレットを除外し、新しい認証 nonce を使い、最終エンドポイントを検証するため、同梱スクリプトの使用をおすすめします。

cd path/to/createos-deploy
bun install

# Inspect the 402 and stop before signing a payment.
bun run deploy -- --dir /path/to/project --name my-app --port 3000

# Pay the selected native MPP offer and deploy.
bun run deploy -- --dir /path/to/project --name my-app --port 3000 --chain arbitrum --yes

# Select x402 instead. It must be advertised by the gateway for that chain.
bun run deploy -- --dir /path/to/project --name my-app --port 3000 --chain bsc --protocol x402 --yes

PRIVATE_KEY はプロセス環境、またはこのスキルと同じディレクトリにある .env で指定してください。アップロードするプロジェクトには絶対に含めないでください。別のゲートウェイをテストするには、CREATEOS_GATEWAY を設定してください。

安全上の境界

• デプロイ前にアプリケーションのソースを調べ、実際のリスニングポートを特定してください。古いデプロイメタデータを信用しないでください。
• プロジェクト名はウォレットごとではなく、プラットフォーム全体で一意である必要があります。名前には必ずランダムなサフィックスを付けてください。同梱スクリプトは自動で付加します。GET /agent/projects に表示されるのは自分のプロジェクトだけなので、別のアカウントが使用している名前は検出できません。
• POST /agent/deploy での 5xx は、通常ゲートウェイの障害ではなく、この名前の衝突が原因です。まず名前の競合として扱い、新しいサフィックスで再試行してください。別のアカウントが使用している名前に対して、ゲートウェイは 409 を返しません。
• ウォレットに未使用のクレジットが十分ある場合、最初の POST /agent/deploy ですぐにデプロイされることがあります。見積もりのみのモードでは新たな支払いを防げますが、API に個別の見積もりエンドポイントがないため、クレジットによるこの動作は防げません。
• --yes を指定しない場合は、選択したプロトコル、ネットワーク、送金先、USDC の金額を提示した時点で停止してください。
• 実行時の 402 ヘッダーを正としてください。検出メタデータにあるデフォルトの支払いチェーンをハードコードしないでください。
• Authorization: Payment ... と PAYMENT-SIGNATURE の両方を送信しないでください。
• 支払い認証情報を送信した後、エラーから復旧するためだけに別の認証情報を作成して送信しないでください。利用できる場合は、レシートまたはチャレンジとトランザクション参照を提示してください。クレジットがすでに付与されている可能性がある場合、支払いヘッダーなしで再試行するのは安全です。
• プロジェクトを削除する直前に、必ずユーザーに確認してください。削除は取り消せません。

支払いの動作

デフォルトのプロトコルはネイティブ MPP です。

• Base、Arbitrum、Arbitrum Sepolia では、EIP-3009 の USDC 承認を使用します。エージェントが承認に署名し、ゲートウェイのセトラーがブロードキャストしてガス代を支払います。
• BSC では、Binance B402 Permit2 Exact を使用します。ウォレットが USDC の支払い先として正規の Permit2 を承認していれば、ガスレスで支払えます。スクリプトは現在の支払い額と同額の上限付き承認を使用します。承認自体には BNB のガス代が必要です。

x402 はオプションです。

• チェーンが PAYMENT-REQUIRED.accepts に含まれている場合に限り、x402 で支払い可能です。
• Base および Arbitrum 系の x402 オファーでは、EIP-3009 を使用します。
• BSC の x402 では、Binance B402 Permit2 Exact を使用します。
• x402 の amount は、トークンの最小単位で表した値です。ワイヤースキーマには decimals が含まれないため、信頼できるローカルのアセットメタデータを使用してください。

ゲートウェイは現在、サポート対象のすべてのチェーンで USDC を扱っています。既知のチェーン ID と、既知の正確なトークンコントラクトのみを必ず受け入れてください。

デプロイのワークフロー

1. プロジェクトを確認して port を特定し、デプロイリクエストを送信する前にプロジェクト名を検証します。一意の名前にはランダムなサフィックスを付け、クリーンな名前は表示名として保持します。
2. GET /agent/projects を使用して既存の名前を検出し、共有クレジットによってランタイムに影響を受ける可能性のあるアクティブなプロジェクトを表示します。この確認で対象となるのはご自身のウォレットのみなので、サフィックスは必須です。
3. 新しいウォレット認証ヘッダーを付け、支払い認証情報を付けずに POST /agent/deploy を送信します。
4. 200 が返された場合、クレジットを使用したデプロイはすでに開始されています。
5. 402 が返された場合は、ネイティブ MPP については WWW-Authenticate を、x402 については PAYMENT-REQUIRED を確認します。ユーザーが承認したプロトコルと、十分な USDC がある広告対象のチェーンのみを選択します。
6. 認証情報を1つ作成し、同一のボディを Authorization または PAYMENT-SIGNATURE のいずれかを付けて再送信します。
7. エラー報告では Payment-Receipt と PAYMENT-RESPONSE の値を保持します。
8. 新しい認証 nonce を毎回使用し、所有するデプロイを5秒ごとにポーリングして、ready または failed になるまで待ちます。
9. エンドポイントを取得する前に待機します。ready はプラットフォームのステータスであり、コンテナーのステータスではありません。アプリは引き続き起動してポートにバインドする必要があるため、最初のプローブでは通常 404 が返るか、接続が拒否されます。最大2分間、10秒ごとにプローブし、その後にのみポートを判定します。ウィンドウ全体を通して 404 が続く場合は、アプリが / で実際に返している応答の可能性があります。まったく応答がない場合は、--port の指定が誤っていると考えられます。

同梱スクリプトを使わずにフローを実装する場合や、ゲートウェイの応答を診断する場合は、references/api.md をお読みください。