Run402

run402：AI エージェント向けフルスタックバックエンドインフラストラクチャ

Postgres、認証、ストレージ、サーバーレス関数、段階的デプロイを備えています — CLI を通じてエージェントがプロビジョニング、運用、支払いを行い、スクリプト作成には型付き SDK、ツールネイティブなホストには MCP を利用できます。クラウドコンソールもサインアップも不要です。オープンソースです。

Run402 は、AI エージェントとコーディングエージェント向けのオープンソースのバックエンドインフラストラクチャです。人ではなくマシンを対象としたバックエンド・アズ・ア・サービスです。自律型エージェントは、Postgres データベース、ユーザー認証、ファイルストレージ、サーバーレス関数、サイトホスティングをプロビジョニングし、単一の段階的デプロイワークフローでリリースして、使用料を自ら支払います。機能面では Supabase、Firebase、Vercel に相当しますが、始めるためにサインインが必要なダッシュボードがない点（コンソールは人向けに存在しますが、エージェントが使う必要はありません）と、人が発行した API キーをコピーする必要がない点が異なります。

これは、Kychee のオープンなプロダクトが稼働するバックエンドです。エージェントがエンドツーエンドで操作でき、各アプリに必要となるものを柔軟に追加できるレイヤーが必要でした。既製品では必要な機能をすべて備えたものがなかったため、これを構築し、アプリと同じ方法で公開しました。このリポジトリにはエージェント向けインターフェース（MIT）が含まれ、run402-core にはオープンソースでセルフホスト可能なランタイム部分（Apache-2.0。マネージド Cloud のコントロールプレーンは引き続きプロプライエタリです。詳細は CLOUD_VS_CORE.md を参照してください）が含まれます。kysigned は、この上で稼働する最初のプロダクトです。

run402 を 1 回呼び出すだけで、エージェントはフル機能の Postgres データベース、REST API、ユーザー認証、コンテンツアドレス可能なファイルストレージ、静的サイトホスティング、サーバーレス関数、画像生成を利用できます。支払いには x402（Base 上の USDC）、MPP（Tempo 上の pathUSD、または Bitcoin Lightning 経由の sats）、あるいはカードでチャージした利用枠を使えます。プロトタイプ向けのティアはテストネットで無料です。

Run402 がエージェントファーストなのは、エージェントが第一級の参加者であり、人がいなくなるからではありません。 人もエージェントも、それぞれ独自の Run402 プリンシパルと認証器を通じて操作し、その操作は追跡可能な状態に保たれます。アイデンティティによって誰が操作したかを特定し、メンバーシップ、ロール、権限付与、権限付与キー、鮮度、支出ポリシーによって、そのプリンシパルが何を実行できるかを決定します。

自律型エージェントは、自ら作成した 1 人組織の正当なオーナーであり続けることができます。人は明示的な共同所有を通じて参加できます。他者の組織に参加するエージェントには、人のアカウントを借りるのではなく、範囲を限定した権限が与えられます。異なるキー。対等な立場。明示的な権限。

プロビジョニング、デプロイ、調査、復旧には、デフォルトで CLI を使用してください。プログラムによる TypeScript／JavaScript のワークフローを作成する場合は、型付きの、意見の明確な SDK を使用してください。シェルスクリプトや CI では、引き続き CLI を使用できます。MCP ネイティブなホストには MCP を、意図的に低レベルの統合を行う場合は直接 HTTP を使用できます。

このモノレポには、以下のインターフェースが含まれています。

インターフェース	使用する場面
run402 CLI	ターミナル、スクリプト、CI、エージェントが制御するシェル：JSONを入力し、JSONを出力します。失敗時は終了コードを返します
@run402/sdk	TypeScriptからrun402を呼び出す場合：型付きカーネル、同形対応（Node 22 / Deno / Bun / V8 isolates）で、ローカルのキーストア＋ウォレット＋x402 / Lightning fetchを自動で読み込むNodeエントリを備えています
run402-mcp	Claude Desktop、Cursor、Cline、Claude Code：run402の主要な操作をMCPツールとして提供します
OpenClaw skill	OpenClawエージェント（MCPサーバーは不要です）
Run402 for Buzz	Buzzのユーザーとエージェント：run402.comからインストールし、1つのエージェント専用のIDを事前確認して連携し、コンテキストに応じたデモをデプロイしてから、通常のHTTPS/passkeyによる引き継ぎで人間による共同所有を提案します。Buzzは変更されません
@run402/functions	デプロイ済み関数の_内部_からインポートする場合（db(req?)、adminDb()、auth.user()、email、ai、assets）、およびエディターでTypeScriptの自動補完を利用する場合。ソースは公開されているrun402-coreリポジトリのpackages/functionsにあり、関数のzipをバンドルする際にrun402 Cloudが公開済みnpmパッケージを使用します。
@run402/astro	SSR、ISRキャッシュ、ホスト型認証コンポーネント、画像バリアント向けのAstro統合

これらのインターフェースでは、適切な箇所で単一の型付きカーネル、@run402/sdkを共有します。MCPツール、CLIサブコマンド、OpenClawスクリプトは、SDK呼び出しを薄く包むものです。@run402/functionsはデプロイ済みコード内で実行する関数内ヘルパーであり、レジストリ上のnpmパッケージはCloudがバンドルする成果物です。@run402/astroは、SDKとfunctionsランタイムをAstroのビルドおよびSSRのフローに組み込みます。HTTP APIが基盤となり、SDKがクライアント間で共有するワークフローとオーケストレーションを担い、CLIとMCPがそれらをマシン向けの形式で公開します。ネイティブのSDK/MCPリファレンスでは、意図的に設けられた代替手段について説明しています。

デプロイの概要では、SDKのワークフロー表示を共有します。CLIは.run402/diagnostics/に詳細情報を秘匿化して保存し、MCPはexpand_resultを通じて詳細情報を保持します。型付きSDKの呼び出し元には、完全な結果が返されます。スナップショットの収集では、プラットフォームのランタイムファイルが自動的に除外されます。

30秒で開始

まず、最初のデプロイの手順に従って、完全なrun402.jsonとindex.htmlを作成します。これらのコマンドは、そのアプリケーションのディレクトリで実行してください。--nameは新しいプロジェクトの作成を要求します。

npm install -g run402@latest
run402 up --name my-app -y                           # bootstrap wallet/tier/project/link, then deploy manifest
run402 up verify                                     # rerun app HTTP verification without deploying
run402 up --verify                                   # deploy, then wait for gateway/edge coherence

これは、本物のPostgresデータベースとデプロイ済みの静的サイトであり、テストネットのUSDCで自律的に支払われます。

同じウォレットを使って、任意のx402販売者から、デフォルトの上限$0.10で購入できます。

run402 pay https://seller.example/translate --method POST \
  --body '{"text":"hello"}' --max-usd 0.05 \
  --idempotency-key translation:1 --require-receipt

SDKでは、同等の処理を r.pay.fetch(url, init, { maxUsdMicros, idempotencyKey, requireReceipt })で行います。 MCPの呼び出し元は、runスニペットとして同じSDK呼び出しを実行します。3つのインターフェースはいずれも、決済、資金移動／再試行、配信、オファー、販売者のレシート、署名者との関係、ポリシー、生の証拠フィールドを含む同一のx402-commerce-result.v1決済結果を返します。また、価格設定のないURLはpayment: nullのまま通過させます。レシートを必須にすると、ウォレットを起点とするオファーのうち適用可能なものがない場合、支払い前に拒否されます。決済後に約束されたレシートを検証できない場合、PaymentPolicyErrorは上流のレスポンスと支払い済みの結果を保持し、支払いを繰り返さずに照合するよう呼び出し元に伝えます。 信頼されたRun402のPAYMENT_INTENT_PENDINGでは、3つのインターフェースすべてで復旧手順が1つに定められています。Retry-Afterを待ち、同じ支払者とキーで同じリクエストを再実行します。キーは絶対に変更しないでください。SDKとMCPでは、プロセスが稼働している間、曖昧な証明を再提示することもできます。カスタム／任意の販売者の場合は曖昧な状態が残るため、照合が必要です。 リポジトリに run402.deploy.json または app.json がある場合は、run402 up を優先してください。CLI は Node SDK のアクションランナー（r.actions.run(...) / r.up(...)）を薄く包むだけです。最初にマニフェストを検証し、不足している前提条件のみを再帰的に満たします。プロジェクトの解決順序は、--project、.run402/project.json、マニフェストの project_id、--name による承認済みの作成です。グローバルなアクティブ状態がデプロイ先を選ぶことはありません。--name はプロジェクトの作成／リンク用メタデータに限られ、デプロイマニフェストの一部ではなく、既存プロジェクトの名前も変更しません。適用前のローカル検証には --check、ゲートウェイによるレビュー済みの意図の確認には --plan を使用してください。ローカル検証では、マニフェストが参照するすべてのファイル（マイグレーションの sql_path / sql_file、関数のソースと files、サイトのパスと dir() の対象、assets.put のソース）を確認します。不足しているファイルがある場合は、ゲートウェイへの呼び出し前に、すべてのモードと run402 deploy で MANIFEST_FILE_MISSING（{ field_path, path, kind } の配列である details.missing[]、ファイルごとに 1 つの create_file 次アクション）を返して失敗します。作業ディレクトリにマニフェストがない場合、UP_MANIFEST_REQUIRED は 1 階層下を調べ、見つかったものを示します（details.nearby_manifests[]、候補が 1 つなら読み取り専用の run_in_directory アクション、複数のアプリがある場合は順位付けされない select_application アクションが 1 つ）。存在しないファイルを指定する --manifest <path> は、型付きエラー MANIFEST_NOT_FOUND になります。

アプリのマニフェストに verify.http[] が定義されている場合、run402 up はデプロイ後にその URL を検証します。run402 の新しいエッジセンチネルで見つからない場合は、バインディングの反映中に限り、恒久的な失敗ではなく propagation_pending として報告されます。この待機時間は --propagation-budget-s（既定値は 120）で調整するか、--no-propagation-wait を指定してすぐに戻れます。run402 up verify は、アップロード、デプロイ、プロジェクト作成、リソース変更を行わずに、同じ HTTP チェックを再実行します。

CLI は run402 の新しいリリースがあるかを機会に応じて確認し、確認に失敗しても処理を続行します。成功時の標準出力にはコマンドの結果が出力されます。古いバージョンに関する通知は標準エラー出力に助言的な JSON として出力されるか、--json-stream では cli.update_available NDJSON イベントとして出力されます。run402 doctor --refresh は明示的に npm をライブチェックし、インストール環境と、ローカル、グローバル、一時的なインストールそれぞれに最も安全なアップグレードコマンドを報告します。run402 doctor は { ok, blocking[], warnings[], checks[] } を返します。ok が true になるのは blocking[] が空の場合に限ります。各チェックには severity: "blocking" | "advisory" | "info" が含まれます。助言的な検出事項（パスキーが未バインド、CLI が古い、Vault の不足、他の組織のプロジェクトにはアクセスできるものの、自組織にティアがない状態：TIER_MISSING_ON_OWN_ORG）は、ok と終了コードを変えずに warnings[] に入ります。tier チェックの status は固定の語彙（ok | inactive | frozen | past_due | dormant | purged | missing | unknown | error。ティア名は含みません）で、名前と未加工のライフサイクル状態は value.tier / value.lifecycle に含まれます。

型付きデプロイ設定でも同じコマンドを使用します。実行可能な設定は信頼されたローカルコードであるため、v1 では明示的に指定された場合にのみ実行されます。

run402 up --manifest run402.deploy.ts --check
run402 up --manifest run402.deploy.ts --plan
run402 up --manifest run402.deploy.ts --require-plan plan_...

--check と --print-spec はローカルのみで実行されます（どちらも参照先のすべてのファイルが存在することを検証します）。--plan は、plan_id、plan_fingerprint、警告、差分、次のアクション 1 つを含むレビュー済みプランをゲートウェイに要求します。--require-plan は、正規化された仕様とレビュー済みのゲートウェイイベントが引き続き一致する場合にのみ、再適用します。

import { defineConfig, dir, nodeFunction, sqlFile } from "@run402/sdk/config";

export default defineConfig(({ env }) => ({
  project_id: env.required("RUN402_PROJECT_ID"),
  database: { migrations: [sqlFile("db/001_init.sql")] },
  site: { replace: dir("dist"), public_paths: { mode: "implicit" } },
  functions: { replace: { api: nodeFunction("dist/functions/api.js") } },
  secrets: { require: ["OPENAI_API_KEY"] },
}));

ヘルパーは JSON マニフェストと同じ ReleaseSpec に正規化されます。dir() は決定論的に走査し、明示的に許可されていない安全でないファイルを拒否します。sqlFile() は指定がない場合、ファイル名からマイグレーション ID を導出します。nodeFunction() は現在 JavaScript の出力を想定しているため、TypeScript 関数はビルド済みの .js ファイルを指定してください。

パターン

そのまま貼り付けて使えるアセット：SRI 付きのコンテンツアドレス方式 URL

CLI でファイルをアップロードします。アプリケーションデータに参照を保存する際は、変更不可能な識別子と画像バリエーションを含む、返された AssetRef をそのまま保持してください。コンテンツハッシュやバリエーション URL を自分で再構築しないでください。

run402 assets put ./logo.png ./app.js ./app.css --project prj_example

これらのファイルをリリースとともに有効化する必要がある場合は、マニフェストのアセットスライスを使用してください。HTML 出力とプログラムによる組み立てについては、ストレージガイドとネイティブ SDK の AssetRef ヘルパーを参照してください。バイナリファイルはバイト列のまま扱ってください。アップロード前に UTF-8 として読み込んではいけません。

デフォルトで非公開のテーブルと公開マニフェスト

作成したテーブルは、マニフェストで宣言するまで /rest/v1/* 経由ではアクセスできません。これにより、「エージェントがテーブルを作成したが、RLS の設定を忘れてデータが漏えいした」という落とし穴を防ぎます。既存の未宣言テーブルに対して有効な anon キーを使用すると、構造化された 403 TABLE_NOT_EXPOSED が返されます（単なる Postgres の 42501 が返されることはありません）。その next_actions には、expose_table（宣言して再デプロイする）、edit_request（公開エンドポイント）、または use_function（非公開のままにして adminDb() を使った関数から読み取る）と、必要な対応が明確に示されます。これは RLS の問題ではありません。マニフェストは収束性を備えています。2 回適用しても何も変更されません。適用の間に削除された項目については、ポリシー、権限、トリガー、ビューが削除されます。

cat > manifest.json <<'EOF'
{
  "$schema": "https://run402.com/schemas/manifest.v1.json",
  "version": "1",
  "tables": [
    { "name": "items",  "expose": true,  "policy": "user_owns_rows",
      "owner_column": "user_id", "force_owner_on_insert": true },
    { "name": "audit",  "expose": false }
  ],
  "views": [
    { "name": "leaderboard", "base": "items", "select": ["user_id", "score"], "expose": true }
  ],
  "rpcs": [
    { "name": "compute_streak", "signature": "(user_id uuid)", "grant_to": ["authenticated"] }
  ]
}
EOF

run402 projects validate-expose <project_id> --file manifest.json
run402 projects apply-expose    <project_id> --file manifest.json
run402 projects get-expose   <project_id>

組み込みポリシー：user_owns_rows（owner_column = auth.uid() に該当する行。force_owner_on_insert: true を設定すると、BEFORE INSERT トリガーで値が設定されます）、public_read_authenticated_write（誰でも読み取り可能で、認証済みユーザーは誰でも書き込み可能）、public_read_write_UNRESTRICTED（完全に公開。i_understand_this_is_unrestricted: true が必要）、および custom（独自の CREATE POLICY SQL を記述するための拡張ポイント）。

適用前に変更を加えずにフィードバックを得るには、run402 projects validate-expose を使用してください。任意のマイグレーション SQL はマニフェスト参照の確認にのみ使用されます。PostgreSQL のドライランとして実行されるわけではなく、デプロイマニフェストの検証も行いません。

SDLC としての認証： 同じ JSON を v2 の ReleaseSpec 内の database.expose に指定してください。ゲートウェイはデプロイ時にマイグレーション SQL と照合して検証し、不一致がある場合は、すべての違反を列挙した構造化された errors 配列を返して拒否します。

ディレクトリのデプロイ（高度なプリミティブ）

既存のプロジェクト上で、単独の静的ディレクトリをデプロイする場合：

run402 sites deploy-dir ./dist --project prj_example > result.json 2> events.log

デプロイマニフェストを使ってアプリケーション全体をデプロイするには、run402 up を使用してください。ファイルのハッシュ計算、アップロードの重複排除、リリースのオーケストレーションは SDK が担い、CLI は進行状況と結果を表示します。

同一オリジンの Web ルート：静的サイト + 関数のイングレス

Apply-v1 のルートと静的な公開パスはリリースリソースです。run402 deploy の必要なデプロイ段階が完了すると、リリースポインターが有効になります。そのポインターを変更しても、適用済みのマイグレーションや外部への副作用はロールバックされません。リリース内の静的アセットパス（events.html など）と、ブラウザーから見える静的公開パス（/events など）は異なります。通常の、末尾に拡張子を付けない静的 URL には site.public_paths を使用し、ルートは関数のイングレスと、正確なパスおよびメソッドを指定する静的エイリアスに使用してください。

{
  "project_id": "prj_...",
  "site": {
    "replace": {
      "index.html": { "data": "<!doctype html><main id='app'></main><script>fetch('/api/hello')</script>" },
      "events.html": { "data": "<!doctype html><h1>Events</h1>" }
    },
    "public_paths": {
      "mode": "explicit",
      "replace": {
        "/events": { "asset": "events.html", "cache_class": "html" }
      }
    }
  },
  "functions": {
    "replace": {
      "api": {
        "runtime": "node22",
        "source": {
          "data": "export default async function handler(req) { const url = new URL(req.url); return Response.json({ ok: true, path: url.pathname }); }"
        }
      },
      "login": {
        "runtime": "node22",
        "source": { "data": "export default async function handler(req) { return Response.json({ ok: true }); }" }
      }
    }
  },
  "routes": {
    "replace": [
      { "pattern": "/api/*", "methods": ["GET", "POST", "OPTIONS"], "target": { "type": "function", "name": "api" } },
      { "pattern": "/login", "methods": ["POST"], "target": { "type": "function", "name": "login" } }
    ]
  }
}

site.public_paths.mode: "explicit" は、完全な public_paths.replace テーブルに含まれるパスだけが、静的 URL として直接アクセス可能であることを意味します。この例では、/events はリリースアセット events.html を返しますが、別途宣言しない限り /events.html は公開されません。mode: "implicit" にすると、ファイル名から導出された公開アクセスが再び有効になり、アクセス可能な範囲が広がる可能性があります。確定する前に、ゲートウェイの警告を確認してください。 routes を省略するか、routes: null を渡すと、ベースルートが引き継がれます。ルートテーブルをクリアするには、routes: { "replace": [] } を使用します。ルートエントリーは、パスをキーとするマップではなく、順序付きの replace リストです。関数のターゲットには、{ "type": "function", "name": "<materialized function name>" } を使用します。静的ルートのターゲットでは、完全一致のパターンのみを使用でき、メソッドは ["GET"] または ["GET","HEAD"] に限られます。また、{ "pattern": "/events", "methods": ["GET","HEAD"], "target": { "type": "static", "file": "events.html" } } の形式を使用します。この file はリリースの静的アセットパスであり、公開パス、URL、CAS ハッシュ、リライト、リダイレクトではありません。静的な GET /login と関数の POST /login のような、メソッドごとのエイリアスには静的ルートのターゲットを使用します。公開パスを明示するモードでは、ファイル名によってバックエンドのアセットを非公開のままにできます。直接の /functions/v1/:name 呼び出しは引き続き API キーで保護されます。ブラウザーからルーティングされるパスは、公開された同一オリジンの入口です。

関数ルートのエントリーに pricing: { "mode": "always", "amount_usd_micros": 250000, "pay_to": "org_default_payout" } を追加すると、ハンドラーの実行前に、テナントに対して x402 の固定料金を課金できます。250000 は、一致するアクションごとに $0.25 を意味します。ポータブルな ReleaseSpec コントラクトでは、有料の関数ルートに receipt: "on_fulfillment" を指定することもできます。互換性のあるホストでは、レシートを発行する前に、関数が payment.fulfilled(response) を返す必要があります。標準の委任署名者キャリアが利用可能になるまで、Run402 ホストの広告機能は無効のままです。レシートの意図が暗黙のうちにダウングレードされることはありません。本番メインネットのみの場合は networks を省略し、テストネットで受け付ける場合は "testnet" を明示的に含めてください。静的エイリアスには料金を設定できず、関数の直接呼び出しは収益化されません。また、サービスキーや管理者キーを使っても、有料のブラウザールートを回避することはできません。所有する組織には、解決可能なペイアウトウォレットが必要です。run402 orgs payout-wallet <org_id> <wallet_address> で設定してください。条件付きクレジットシステムでは、POST /api/credits のような固定料金のルートを1つ公開し、残りのアプリは料金なしのルートとアプリ内認可で保護してください。

照合は、完全一致または末尾のプレフィックスワイルドカードのみです。/admin と /admin/ は、末尾のスラッシュを除いて同一の完全一致として扱われます。/admin/* は子パスに一致しますが、/admin、/admin/、/admin.css、/administrator には一致しません。そのため、ルーティング対象セクションのルートには /admin と /admin/* の両方をデプロイしてください。照合時にクエリ文字列は無視され、ハンドラーの完全な公開 req.url では保持されます。完全一致ルートはプレフィックスルートより優先され、最長のプレフィックスが選ばれます。メソッドが一致する動的ルートは、静的アセットより優先されます。POST /login ルートは、静的な GET /login の HTML と共存できます。安全でないメソッドが一致しない場合は 405 が返されます。一致した動的ルートでエラーが発生した場合、静的ファイルへのフォールバックは行われません。

ルーティングされる関数では、Node 22 の Fetch Request -> Response コントラクトを使用します。export default async function handler(req) { ... } の形式です。req.method はブラウザーのメソッドであり、req.url は、管理対象サブドメイン、ホスト、検証済みカスタムドメインにおける完全な公開 URL です。たとえば、new URL("/admin/oauth/google/callback", new URL(req.url).origin) のようにして OAuth コールバックの URL を導出します。複数の Cookie を追加するには、headers.append("Set-Cookie", value) を使用します。リダイレクト、Cookie、クエリ文字列は保持されます。有料ルートでは、@run402/functions から getRoutedPaymentContext をインポートし、const paymentContext = getRoutedPaymentContext(req) を読み取り、アプリ側の冪等性キーには paymentContext.paymentId を使用してください。レシートが有効なルートでは、レスポンスが配信完了を表す場合に限り、payment.fulfilled(response) を返してください。このヘルパーは、決済が確定済みで、現在のレシート有効ルートで呼び出された場合以外は、安全側に倒して失敗します。コンテキストヘルパーは、ゲートウェイが確認した x-run402-payment-* ヘッダーを読み取り、有料でない呼び出しや直接呼び出しでは null を返します。生の run402.routed_http.v1 エンベロープは内部仕様です。ルートハンドラーでこれを直接扱わないでください。 レシピ：静的なホームページ＋SPA シェル。 SPA サイトでは、index.html をすべての未一致ルートに対応するシェルとして配信するため（spa_fallback に一致）、デフォルトでは GET / もシェルを配信します。アプリのルートではシェルを維持しながら、/ で実際の静的なホームページを配信するには、サイトルートに index.html と並べて home.html を配置し、ルートに完全一致する静的ルートエイリアスを追加します："routes": { "replace": [ { "pattern": "/", "target": { "type": "static", "file": "home.html" } } ] }。ルートの照合はすべての静的解決（暗黙の / → index.html ルートマッピングを含む）より先に実行され、SPA フォールバックの導出はルートテーブルとは独立しているため、GET / は home.html（route_static_alias）を配信し、/dashboard などの未一致のアプリルートは引き続きシェル（spa_fallback）を配信し、名前付きの静的ページは変更なく（static_exact）配信されます。ブロッキングではないプランの lint が 2 つ表示されます：STATIC_ALIAS_SHADOWS_STATIC_PATH（警告：エイリアスが / で本来配信されるファイルを上書きします。このケースでは正確で、想定どおりです）と STATIC_ALIAS_DUPLICATE_CANONICAL_URL（情報：暗黙の公開パスモードでは /home.html に引き続き直接アクセスできます。重複コンテンツが SEO 上問題になる場合は、home.html に <link rel="canonical"> を追加してください）。後続のデプロイで routes を省略すると、エイリアスは引き継がれます。routes.replace は全置換のため、これを送信するパイプラインでは毎回エイリアスを含める必要があります。run402 deploy resolve --url https://<your-site>/ --method GET（または r.project(id).apply.resolve）を実行して確認し、match: "route_static_alias" と target_file: "home.html" が表示されることを確認してください。

すべての静的ファイルをルーティングすること、デフォルトで広範なメソッド一覧を指定すること、ワイルドカードの静的ルートターゲット、先頭にスラッシュを付けた静的ファイル、ディレクトリの省略記法、ルートの上限を使い切るようなページごとの静的ルートターゲットの一覧は避けてください。また、直接アクセス可能な公開静的パスをシャドーイングするワイルドカード関数ルートにも注意してください。対処すべき警告コードには STATIC_ALIAS_SHADOWS_STATIC_PATH、STATIC_ALIAS_RELATIVE_ASSET_RISK、STATIC_ALIAS_DUPLICATE_CANONICAL_URL、STATIC_ALIAS_EXTENSIONLESS_NON_HTML、STATIC_ALIAS_TABLE_NEAR_LIMIT があります。アクティブルート、static_public_paths、解決診断を確認し、ルートパターンと参照先の asset_path を区別してください。

CLI またはその MCP／SDK の同等機能を使って公開 URL を解決します：

run402 deploy resolve https://example.com/events --project prj_123 --method GET
run402 deploy resolve --url https://example.com/events?utm=x#hero --project prj_123 --method GET
run402 deploy resolve --host example.com --path /events --project prj_123 --method GET

r.project(id).apply.resolve({ url, method: "GET" })（MCP の run スニペット）は、would_serve、diagnostic_status、match、正規化されたリクエストデータ、警告、解決結果の完全な JSON、edge_propagation、次の手順を返します。返された場合、asset_path、reachability_authority、direct は、公開 URL の配信元となるリリースアセットと、到達可能性が暗黙のファイルパスモード、明示的な site.public_paths、ルートのみの静的エイリアスのいずれに由来するかを示します。安定ホストの診断には、authorization_result、cas_object（sha256、exists、expected_size、actual_size）、ホスト名固有の response_variant、allow、route_pattern、target_type、target_name、target_file などのルート／静的フィールド、edge_propagation（settled、propagating、sync_pending）も含まれる場合があります。既知の match リテラルは host_missing、manifest_missing、active_release_missing、unsupported_manifest_version、path_error、none、static_exact、static_index、spa_fallback、spa_fallback_missing、route_function、route_static_alias、route_method_miss です。将来追加される未知の文字列はそのまま保持してください。既知の authorization_result 値には、authorized、not_public、not_applicable、manifest_missing、target_missing、active_release_missing、unsupported_manifest_version、path_error、missing_cas_object、unfinalized_or_deleting_cas_object、size_mismatch、unauthorized_cas_object があります。既知の fallback_state 値には active_release_missing、unsupported_manifest_version、negative_cache_hit があります。将来追加される未知の文字列はそのまま保持してください。result は診断本文のステータスであり、SDK 呼び出しの HTTP ステータスではありません。そのため、ホストが見つからない場合でも、would_serve: false のまま CLI／MCP／SDK 呼び出しが成功することがあります。resolve／diagnose をフェッチ、キャッシュのパージ、キャッシュポリシーの判定手段として扱わないでください。ルートのメソッド不一致では allow を確認し、CAS の認可／健全性エラーでは該当する静的アセットを確認するか再デプロイしてください。また、新しいホストが見つからない場合は edge_propagation を確認するか、run402 up verify を再実行してください。cache_class などの構造化 JSON フィールドに基づいて分岐し、未知のキャッシュクラスはそのまま保持してください。

リリースの可観測性により、安定したアセット ID と公開到達性を確認できます。インベントリには、release_generation、static_manifest_sha256、値が null の場合がある static_manifest_metadata（file_count、total_bytes、cache_classes、cache_class_sources、spa_fallback）、返される場合は static_public_paths[] が含まれます。site.paths はリリースの静的アセットを列挙します。static_public_paths[] はブラウザーからアクセスできる公開パスを列挙し、public_path、asset_path、reachability_authority、direct、キャッシュクラス、コンテンツタイプを含みます。プラン差分とリリース差分には、静的アセットのカウンター static_assets が公開されます。これには、未変更／変更／追加／削除の数、newly_uploaded_cas_bytes、reused_cas_bytes、deployment_copy_bytes_eliminated、legacy_immutable_warnings、previous_immutable_failures、cas_authorization_failures が含まれます。

分岐対象となるランタイムのルート失敗コード：ROUTE_MANIFEST_LOAD_FAILED（マニフェスト／伝播）、ROUTED_INVOKE_WORKER_SECRET_MISSING（カスタムドメインの Worker シークレット）、ROUTED_INVOKE_AUTH_FAILED（内部呼び出しの署名）、ROUTED_ROUTE_STALE（選択されたルートのリリース再検証失敗）、ROUTE_METHOD_NOT_ALLOWED（メソッド不一致）、PAYOUT_WALLET_REQUIRED／PAYOUT_WALLET_AMBIGUOUS／PAYOUT_WALLET_UNRESOLVED（価格設定済みルートの支払い設定）、PAYMENT_PROOF_MISMATCH（古い、または誤った x402 証明）、ROUTED_RESPONSE_TOO_LARGE（6 MiB を超える本文）。

GitHub Actions OIDC デプロイ：一度リンクすれば、同じ CLI でデプロイできます

リポジトリ主導のデプロイでは、run402 は GitHub のシークレットにサービスキーやウォレットファイルを必要としません。ローカルでリンクコマンドを一度実行します。

run402 ci link github --project prj_... --manifest run402.deploy.json
# Optional route authority for CI route declarations:
run402 ci link github --project prj_... --manifest run402.deploy.json --route-scope /admin --route-scope /api/*

これにより、デプロイに限定された /ci/v1/* バインディングが作成され、id-token: write を許可し、リポジトリをチェックアウトして、既存のデプロイプリミティブを実行するワークフローが書き込まれます。

permissions:
  contents: read
  id-token: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to run402
        run: npx --yes [email protected] deploy --manifest 'run402.deploy.json' --project 'prj_...'

CI デプロイの対象は意図的に限定されています。site、functions、database、未指定または現在の base、およびバインディングに対象となる --route-scope パターンがある場合に限ったルート宣言です。ルートスコープがない場合、CI から routes をデプロイすることはできません。シークレット、ドメイン、サブドメイン、チェック、現在以外の base、およびより広範な信頼設定の変更は、ローカルのウォレットを使用したデプロイで行ってください。ゲートウェイが CI_ROUTE_SCOPE_DENIED を返す場合は、/admin のような完全一致スコープ、または /api/* のような末尾ワイルドカードスコープを指定して再リンクするか、ローカルでデプロイしてください。バインディングは run402 ci list と run402 ci revoke で管理します。

関数内ヘルパー：呼び出し元コンテキストと BYPASSRLS

デプロイ済み関数内では、@run402/functions からインポートします。2 種類の DB クライアントを使い分けることで、RLS を適切に保てます。

import { db, adminDb, auth, email, ai } from "@run402/functions";

export default async (req: Request) => {
  const user = await auth.requireUser();

  // Caller-context: db() mints a 60s actor JWT so run402.current_user_id() resolves in RLS.
  // No .eq("user_id", user.id) needed: RLS already binds the visitor's rows; the redundant
  // filter is a deploy-fail (R402_AUTH_REDUNDANT_USER_FILTER) under @run402/functions v3.0+.
  const mine = await db().from("items").select("*");

  // BYPASSRLS: for platform-authored writes (audit logs, cron cleanup, webhook handlers).
  await adminDb().from("audit").insert({ event: "items_read", user_id: user.id });

  // Send mail from the configured default outbound mailbox.
  if (mine.length === 0) {
    await email.send({ to: user.email, subject: "Welcome", html: "<h1>hi</h1>" });
  }

  return Response.json(mine);
};

adminDb().sql(query, params?) は、パラメーター化された SQL を直接実行し、常に RLS をバイパスします。現在のランタイムは rows や row_count などを含むゲートウェイのエンベロープを返します。result[0] ではなく result.rows を参照してください。以前のヘルパーの型定義は、誤って単純な配列として記述されていました。詳しくは該当ランタイムのリファレンスを参照し、ローカルのヘルパー型をデプロイで使用するランタイムのバージョンに合わせてください。

@run402/functions はデプロイ済みコードに自動でバンドルされます。TypeScript の完全な自動補完を利用するには、エディターにインストールしてください（RUN402_SERVICE_KEY と RUN402_PROJECT_ID を設定すると、静的サイト生成のビルド時にも使用できます）。

ai.generateImage({ prompt, aspect? }) は、生成アバターや OG 画像など、実行中のアプリのフローで利用できるデプロイ済み関数向けの機能です。RUN402_SERVICE_KEY を使ってプロジェクトのランタイム画像エンドポイントを呼び出すため、デプロイ済み関数でウォレットや x402 署名コードは必要ありません。アスペクト比は square、landscape、portrait から選択できます。戻り値は { image, content_type, aspect } で、画像バイト列は base64 形式です。ランタイムでの画像生成は課金対象であり、プロジェクトの組織に対するレート制限と利用額上限が適用されます。公開ルートの関数から呼び出す前に、ユーザー認証とレート制限を行ってください。

assets.put(key, source, opts?) は、デプロイ時のアセットと同じ CAS ベースの適用基盤を使って、デプロイ済み関数内からバイト列をアップロードします。RUN402_SERVICE_KEY を使用し、文字列、Uint8Array、または { content | bytes } を受け取り、SDK 互換の AssetRef と変更可能および不変の URL を返します。

関数の外部から運用データを扱う場合： プロジェクトを明示して CLI を使用してください。意図的な HTTP 連携については、ネイティブ HTTP リファレンスで管理者 REST と呼び出し元スコープの REST の違いを確認してください。サービスキーをブラウザーに公開してはいけません。

run402 projects sql prj_example "SELECT count(*) FROM audit"

repos：マシンから持ち出す前に暗号化する、リポジトリの履歴

run402 repos は Git リモートです。内容は自分のマシン上で暗号化され、署名済みで承認された head のチェーンとして保存されます。これは、リポジトリの履歴を作成元のマシンがなくなった後も保持するためのものであり、そのために Run402 に平文を渡す必要はありません。ワイヤープロトコルは r402s/v0 です。1 つの名詞と 17 個の動詞：KyGit はブランド名、vault はリソース、repo は手元にあるものです。コマンドラインでは run402 repos、SDK では r.repos を使います。17 個の動詞のうち 2 組は、1 回限りの bearer key を発行して引き継ぎます。handoff／resume は、チェックアウト済みの作業ツリー（未コミットの変更を含む）を、送信側が停止して別のエージェントに引き継ぎます。invite／join は、最初のエージェントが作業を続けながら、2 番目のエージェントを同じ作業に参加させ、連携ルームを共有します。詳しくは、以下の「引き継ぎ／再開」と「招待／参加」を参照してください。 主張は 3 つ。それぞれ強さが異なります。この機能で承認されている主張は、以下のとおりです。

1. Run402 は、あなたのボルトやリポジトリの履歴を復号できません。デプロイ成果物は、開示済みの平文管理境界に残ります。 Run402 自体に対する暗号学的な保証です。ボルトレーンでは、ソースペイロードとリポジトリ履歴の内容は暗号文のみです。基盤に保持される平文メタデータは列挙されたものに限られ、ボルトキーは一切保持されません。デプロイレーンは分離され、開示されています。プラットフォームは、すべてのデプロイの平文成果物を管理下で保持します。デプロイしたものは読み取れますが、デプロイしていないものは読み取れません。
2. デフォルトでは、アクティベーションにはボルトへの参加が必要です。明示的に監査可能なオーバーライドを行えば、これを迂回できます。 これはプラットフォームの運用上の不変条件であり、強制および監査が可能です。これを強制するプラットフォームに対する暗号学的な保証ではありません。
3. 保持はプラットフォームによる運用上の約束であり、プラットフォームに対する暗号学的な保証ではありません（ホストがタイムスタンプとバイト列を管理します）。

ボルト専用トラック — 3 行で、操作はそのまま、費用はかかりません：

run402 init                                   # once per machine
run402 repos create my-notes                  # project + vault + origin remote, one free call
git push -u origin main                       # publishes, encrypted before it leaves the machine

origin は追加で設定されます。ディレクトリにまだ origin がない場合、スキャフォールドは origin という名前でこちらのリモートを設定するため、git push origin main がそのまま使え、別のリモート名を覚える必要はありません。既存の origin に手を加えることはありません。その場合は代わりに run402 を設定し、どちらになったか、その理由を応答で知らせます。別のリポジトリ内にあるアプリ（モノレポのワークスペース）は、そのリポジトリにスキャフォールドされません。スキップ時には create_nested_repo の次のアクションが示され、run402 repos create --nested --project <project_id>（または run402 up --nested）を実行すると、アプリのルートに独自のネストされたリポジトリと run402 リモートが作成されます。さらに、親リポジトリのローカル .git/info/exclude に 1 行だけ追記し、ほかの箇所には手を加えません。repos create が git push の次のアクションを表示するのは、実際に追加したリモートに限られます。無料で使える範囲に制限はありません。スラッグも料金も手続きも不要です。見やすい run402::<org-slug>/<name> 形式のアドレス（名前によるクローン、プッシュによる作成）を使いたい場合は、組織のスラッグを一度だけ取得してください。これは、以下で説明する任意の名前付きアドレスへのアップグレードです。

名前付きアドレス。 run402::<org-slug>/<name> は、同じスロットで ID 形式の run402::<org_id>/<project_id> と併用できます。組織のスラッグを一度だけ取得すれば（run402 orgs slug <slug>、オーナーのみ、小額の一度限りの料金）、その組織のすべてのリポジトリで run402::<slug>/<name> を使えます。まだ存在しない名前にプッシュすると、プッシュによって作成されます。プロジェクトとボルトはアトミックに割り当てられ、同時にプッシュして負けた側はエラーにならず、勝者のリポジトリに正常に解決されます。作業が失われるわけではなく、作成者にならなかっただけです。チェックアウトで名前付きリモートが初めて解決されると、解決された ID がそのチェックアウトのローカル Git 設定にピン留めされます。その後のプッシュやフェッチはすべてこのピンを直接参照するため、後で組織のスラッグやリポジトリ名が変更されても、既存のクローンに影響しません。ID 形式のアドレスにはピン留めは不要です（プロジェクト ID は変更されません）。また、これはコールドスタート時のフォールバックとして使えます。ローカル状態を失っても、プロジェクトに対する権限を保持しているエージェントなら、いつでも run402::<org_id>/<project_id> にフォールバックできます。

あらかじめ知っておいてほしいことが 1 つあります。ボルトには単一のキーではなく、書き込み可能なメンバーの集合があります。 参加を許可されたメンバーや引き継ぎ先は、各自のキーストアキーを使ってボルトを開き、プッシュします（run402 repos access で一覧を確認できます）。参加を許可された主体がこのキーストアだけのボルトは、このキーストアと同じ安全性です。以下の「キーストアを失った場合」を参照するか、2 つ目の主体を参加させてください。

明示的で手順を踏む形式も引き続き使えます。初回利用時に git push と同じ方法で割り当てられます。スクリプトでの利用や、レシートを stderr ではなく JSON の stdout に出力したい場合に便利です。

# 1. Provision. Inside a repository that already exists, this adds the origin
#    remote (run402::<org_id>/<project_id>). Not a repository yet?
#    `run402 init --git-remote` creates one first. It needs a project selected
#    (`run402 projects use <project_id>`, or RUN402_PROJECT_ID).
run402 init

# 2. Allocate the repo's vault explicitly. Separate from `run402 init` on
#    purpose: this is the step that mints key material on this machine and
#    prints a one-shot recovery receipt. Idempotent — an existing vault comes
#    back deduplicated. (Skip this step and git push / repos capture
#    against an unallocated project allocates the SAME way, lazily, on
#    first use — the two paths don't stack; this one just does it now,
#    explicitly, so the receipt lands in JSON stdout instead of stderr.)
run402 repos create --project <project_id>

# 3. Snapshot — capture the working tree, encrypt it, publish a signed head.
run402 repos capture --message "wip: refactor the parser"
git push origin main            # ...or push your own branches, via git-remote-run402

# 4. View, then fsck: walk the head chain from your authenticated pin.
run402 repos view
run402 repos fsck --budget 500

# Restore anywhere, with plain git.
git clone run402::<org_id>/<project_id> restored

クローンするには、このマシンに Run402 の主体、つまりウォレットと、このボルトへのエンベロープを保持するキーストアが必要です。これは暗号化された Git であり、共有可能なリンクではありません。 新規にクローンすると、ブランチから到達できない、保持対象のすべてのデプロイキャプチャ先端に対して、ローカルの refs/r402/retain/<oid> ref がインストールされるため、通常の git fsck では何も表示されません。保持されているものは git for-each-ref refs/r402/ で一覧表示できます。これより古いクライアントで作成したクローンや、ref の書き込みが劣化したチェックアウトでは、git fsck に dangling commit が表示されることがありますが、無害であり、破損ではありません。run402 repos fsck を一度実行すれば、不足している ref がインストールされます。ローカルに保持された ref は、Vault がキャプチャをプルーニングするまで、その履歴を git gc から保護します。プルーニング後、次回のフェッチで ref が取り消されます。

repos capture は CAPTURE レーンです。プロトコルのデプロイ ref と HEAD の参照先が対象です。ダーティなツリーは、どのブランチにも属さない合成コミットとしてキャプチャされるためです。独自のブランチやタグは、git push origin <branch> で Vault に送信されます。

Vault を割り当てても、プロジェクトのデプロイが制限されることはありません。 vault_policy は設定するまで未設定のままです。最初の git push または repos create で作成された Vault が、デプロイ方法を暗黙に変更することはありません。Vault があり、ポリシーによる制限が設定されていないプロジェクトへのデプロイは、制限なしで実行され、結果には run402 repos policy required を提案する、型付きの next_actions エントリーが含まれます。以降の制限なしのデプロイには、ポリシーをどちらかに設定するまで、変更との不一致を示す warnings[] エントリーが含まれます。ブロックも、対話型プロンプトも表示されません。vault_policy が required に設定されると、デプロイにはコミット時点の Vault キャプチャが必要です。キーストアがあるマシンでは、run402 deploy が自動的にキャプチャを作成します。run402 repos policy grandfathered --reason "<why>" で制限を解除できます（所有者の権限昇格が必要で、監査され、run402 repos policy required で元に戻せます）。どちらの場合も、ソースを Vault に保管することにデプロイ上の制限はありません。run402 doctor はポリシー、このマシンで要件を満たせるかどうか、キーストアの場所を報告します。

capture が何かを保存したと報告する前に、クライアントはすべての確定レシートをローカルの期待マニフェストと照合し、ストレージから登録済みの head を読み戻します。200 が返っただけでは不十分です。メンテナンス用の動詞は run402 repos gc の1つです。git gc が行う2つの処理（チェックポイントの公開とプルーニング計画）を実行します。ただし、削除手順がより厳格なため、「git gc とまったく同じ」とは説明しません。ローカルで計画し、この CLI と独立した r402s-verify からそれぞれ1つずつ、両方の検証レシートを受け取った場合に限り、--submit --intent-core <path> --verifier-receipt <path> を指定して送信します。何が削除されたかを示すのは、コントロールプレーンが署名した完了通知だけです。

SDK からも同じセマンティクスで利用できます。Vault の読み取りはどこからでも実行できますが、git の作業ツリーまたはディスク上のキーストアにアクセスする動詞は Node 専用です。

型付きリポジトリ自動化については、ネイティブ SDK KyGit リファレンスをご覧ください。

暗号化された2つ目のリモート — 移行不要のパターン。 GitHub／GitLab をプライマリ（共同作業、CI、レビューはこれまでどおり）として維持し、2つ目のリモートとして KyGit を追加します。git remote add vault run402::<org_id>/<project_id> と git push vault --all を実行すると、ストレージプロバイダー自身も読み取れない、履歴の完全なコピーが継続的に更新されます。これが重要な理由を、非難ではなく能力の問題として率直に述べます。プライベートリポジトリを読み取れるホストは、将来のポリシー、買収、学習パイプライン、召喚状、または侵害によって、リポジトリをインデックス化したり、モデルのトレーニングに使用したり、他者に渡したりする可能性があります。Run402 は、Vault やリポジトリの履歴を復号できません。デプロイ成果物は、開示済みの平文管理の境界に引き続き置かれます。

Vault 専用プロジェクトも正式にサポートされています。 run402 init（または run402 repos create <name>）の後に git push origin … を実行し、続けて gc／fsck／access を使います。デプロイを一切行わない形も、サポート対象であり、機能が制限された形ではありません。1つ、明記しておくべき点があります。Vault 専用プロジェクトにはデプロイレーンがないため、開示済みの平文管理の境界は空であり、その結果、管理下での復元経路もありません。 キーストアを失った場合。 ボールトは、プリンシパルのキーストアが存続している間、ホスト側での損失からソース履歴を保護します。この「間」という条件は重要です。V0-A では、人間用エンベロープが提供されるまでは、マシン全体またはキーストア全体を失うと、ボールトの履歴は復旧不能になります。run402 repos view はこの文をそのまま表示します。run402 repos view が keystore.root として報告し、ターミナルでの損失に関する記述の下に表示するキーストアディレクトリをバックアップしてください。デフォルトのウォレットでは ~/.config/run402/vault、名前付きウォレットでは ~/.config/run402/profiles/<wallet>/vault です。復旧レシートは整合性アンカーであり、復号キーではありません。提供されたボールトが自分で作成したものだと証明しますが、何も復号しません。秘密情報ではないため、コピーは多いほど安全です。ボールトの価値が高まるにつれて、リマインダーも目立つようになります。ジェネシス時点では表示されず、ボールトが ≥10 世代／≥10 MB／ジェネシスから ≥14 日のいずれかを超えると、run402 doctor に STANDING 警告が表示されます。この警告を解除できるのは、2 つ目のプリンシパルを追加した場合のみです。V0 ではアテステーションが真実であることを検証できないため、アテステーションでは解除されません。

退出経路：自分のコピーをミラーリングする。 run402 repos mirror <destination> [--profile <name> | --ambient]（S3 または通常のディレクトリ）を使って、ボールトの暗号文を自分で管理する 2 つ目のコピーに設定できます。保存先と認証情報の名前は、キーストアの隣にある設定ファイルに保存され、run402.config.json に保存されることも、生のシークレットが保存されることもありません。設定すると、各キャプチャーが自動的にミラーリングされ、ボールトの結果と並ぶ独立した mirror_push フィールドに報告されます。ミラーの失敗によって、実際の公開がブロックされたり、遅れたり、変更されたりすることはありません。run402 repos mirror --backfill（冪等で再開可能）を実行すると、必要に応じて最新状態にできます。run402 repos fsck --mirror はキーを必要としない整合性プローブで、キー素材に触れることなく復旧可能な世代を報告します。run402 repos recover <source> --out <dir> はサーバーを一切必要としません。ミラーを読み込み、チェーンを検証し、ローカルのキーストアだけで復号します。git では restore に別の意味がすでにあるため、名前付きのコマンドには restore ではなく recover を使います。これを頼りにする前に、知っておくべきことが 2 つあります。これは有効性を証明しますが、最新性は証明しません。古いミラーも、履歴が本当に短い場合と同じように見えます。また、ミラーリングしても 2 つ目のキーは作成されないため、キーストアまたは同等のキーなしのミラーからは何も復旧できません。上記の V0 のターミナル損失に関する記述が適用されます。

人間によるバックアップ経路（vault-recovery-custody）。 console.run402.com/account でソース登録を完了した組織の人間のメンバーは、キーストアなしで同等のキーを保持します。メンバーキーはシールされたラッパー（パスキー PRF および／またはソース復旧コード）として保存され、run402 repos recovery-bundle でバージョン付き復旧バンドル（キー ID とラッパーの暗号文。プラットフォームが開けるものは含まれません）をダウンロードできます。ボールトのミラーと一緒に保管します。バンドルをミラーのプレフィックス内の member-recovery-bundles/<name>.json にコピーしてください。このバンドルとソース復旧コード、ボールトの復旧レシートがあれば、run402 サーバーもキーストアも使わずにリポジトリを復旧できます。run402 repos recover <source> --out <dir> --receipt <pin.json>（コードは非表示入力でプロンプトされます。バンドルがミラーにない場合は --bundle <file> を指定します）。生のパスキー PRF 出力は、意図的に復旧入力として使えないようになっています。人間がサーバーなしで復旧する経路は、復旧コードです。run402 doctor の recovery_posture チェックでは、ボールトを所有する各組織にこのバックアップ手段が設定されているかどうかを確認できます。

run402 repos mirror s3://acme-vault-mirror --profile acme --region us-east-1
run402 repos mirror --backfill
run402 repos recover s3://acme-vault-mirror --out ./restored --repo src_1a2b3c
run402 repos recovery-bundle --out ./bundle.json     # the member's no-keystore recovery half
run402 repos recover ./mirror-copy --out ./restored --receipt ./recovery-receipt.json --bundle ./bundle.json

ハンドオフ／再開 — 作業ツリーを、未コミットの変更も含めて別のエージェントに引き継ぎます。 run402 repos handoff は実際の作業ツリーをキャプチャします。ステージ済み、未ステージ、未追跡の変更をすべて、git stash push -u とまったく同じように取り込み、使い捨てのベアラーキー kgh1_… を生成して標準出力に一度だけ表示します（--json でも標準エラーには出力されません。なくした場合、ほかに確認できる場所はありません）。このキーを別のエージェントに渡せば、別のマシンや別のセッションからでも、キーストアやウォレットを共有せずに利用できます。run402 repos resume kgh1_… はそのキーを取得し、新しいチェックアウトをクローンして、git stash apply --index で未コミットの変更を正確に再適用します。再開するエージェントは、処理開始時に独自の run402 ウォレットも取得します。有効なティアがない場合、resume は取得の前に create と同じコールドスタートの流れ（ウォレット → ファウセット → x402 プロトタイプ決済 1 回）を実行します。--no-init でこれを省略でき、取得処理がその完了を待つことはありません。ハンドオフノートも併せて引き継がれます。これは、完了したこと、進行中の作業、失敗していること、次の手順をまとめた短い JSON 形式の概要で、resume ではデフォルトで Markdown として表示されます。このキーは実際の権限を付与します。デフォルトでは送信者自身の組織ロールが付与され、取得されるか TTL（デフォルトは 1h、--ttl <seconds>）が切れるまで有効です。発行レスポンスにその旨が記載され、CLI はキーを表示する前に警告を出します。機密性の高い未追跡ファイル（.env、*.pem、*.key、SSH/AWS/GPG ディレクトリ、およびほかの 18 個のパターン）は、デフォルトでキャプチャ対象から除外されます。--include-sensitive <glob> を指定すると、除外されたファイルを個別に対象へ戻せます。

run402 repos handoff --note-file handoff.json     # captures the working tree, mints the key, prints it ALONE to stdout
run402 repos resume kgh1_…                         # on the other machine: redeem it, clone, restore, print the note

どちらの動詞にも MCP ツールはありません。handoff はベアラーシークレットを発行し、resume は組織のメンバーシップを変更するため、上記の create／delete と同様、「変更を伴う動詞は CLI 専用」とする判断に基づいています。

複数の書き込み者。 ボールトは、各メンバー自身のキーストア ID に対応するライターキーの集合から、ヘッドを受け入れます（プロトコル rev 47）。resume は処理を返す前に受信者をライターとして登録するため、受信者自身のキーを使って git push をすぐに実行でき、送信者の環境はその後削除できます。run402 orgs members add で追加されたメンバー（developer 以上）も、同じ方法でライターになります。追加する側のクライアントは可能な場合、新しいキーをその場で登録し、登録できない場合は追加を拒否します（VAULT_WRITER_NOT_ADMITTED、request_writer_sync）。そのため、読み取りはできてもプッシュできない状態のメンバーが残ることはありません。run402 repos view は writers[] と pending_writers[] を表示し、run402 repos access sync は保留中のキーを必要に応じて登録します。メンバーの削除は次のエポックローテーション時に反映され、そのキーを再登録することはできません。誰のシードもコピーされません。ライターは、稼働中のライターの署名によって登録されるか、送信者が署名したハンドオフ許可を受け取り、受信者が自身のキーで完了することで登録されます。 招待／参加 — ダーティーなツリーも含め、同じ作業にもう1つのエージェントを迎え、共有ルームでやり取りできます。 Handoff は作業を引き継ぎますが、Invite はチームを拡大します。run402 repos invite は handoff とまったく同じように作業ツリーを取得します。招待者自身のワークツリー、インデックス、ブランチ、refs、アクセス権はすべて変更されず、その間もプッシュを続けます。また、連携ルーム（プロジェクトのデフォルトルーム、または名前付きの組織ルームを指定する --room <key>）に招待者自身のプレゼンスを登録し、1回限りのベアラーキー kgi1_… を生成して、標準出力に一度だけ表示し、チェックポイントと招待 ID を記したルームメッセージを1件投稿します（キーは決して投稿しません）。キーの生成には、handoff と同様に ACTIVE な書き込みキーが必要です。修正方法は INVITE_MINT_REQUIRES_WRITER に run402 repos access sync として示されます。そのキーを別のエージェントに渡すと、run402 repos join kgi1_… は参加側が費用を負担して参加します。参加するエージェントは、引き換えの前に resume と同じコールドスタートの一連の手順（ウォレット → フォーセット → x402 のプロトタイプ決済を1回）を自分で済ませるため、自身の run402 ウォレットに支払いを済ませた状態で参加します。新しいチェックアウトをクローンし、コマンドの終了前に自身のキーでボールトの書き込み権限を取得します（招待者からコピーされるものはありません）。さらに、正確なダーティー状態を復元し、招待のルームをローカルに設定して、自身のプレゼンスを登録し、到着メッセージを1件投稿します。また、誰が招待したか（名前、ラベル、まだアクティブかどうか）、ルームに誰がいるか、直近のメッセージを報告します。両方のエージェントがそれぞれ自身のキーで署名しながら、交互にプッシュします。そこから run402 messages wait はエージェントの耳となります。ゲートウェイの保持読み取りを使って相手が発言するまで待機し（または指定されたタイムアウトが経過するまで待ち）、応答がなくてもエラーにはならず、どちらの場合も誰がまだアクティブかを報告します。生成されるロールはデフォルトで developer で、招待者自身のロールを超えることはありません。Handoff Note と同じ形式の Invite Note も一緒に渡され、join ではデフォルトで Markdown として表示されます。アクセス権を取り消すには run402 orgs members rm を使います。これによりボールトのエポックがローテーションされ、削除されたキーはプッシュできなくなりますが、ほかのエージェントは作業を続けられます。

run402 repos invite --note-file invite.json       # captures the working tree, mints the key, prints it ALONE to stdout
run402 repos join kgi1_…                           # on the other machine: pay in, redeem, become a writer, clone, restore
run402 messages wait                               # then: block until the other agent speaks (or the timeout elapses)

handoff／resume と同様に、invite と join にも MCP ツールはありません。invite はベアラーシークレットを生成し、join は組織のメンバーシップを変更して作業ツリーを書き込むためです。これは上記の create／delete／handoff／resume と同じ理由です。

クライアントを信頼せずに検証できます。 r402s-verify は同じプロトコルを検証する、独立した系統の検証ツールです。SDK とは別の言語、別の作成者、別のプリミティブスタックを使い、実装コードを意図的に共有しません。コードを共有しないことが重要です。検証対象のコードを再利用する差分検証ツールでは、何も検証できません。このツールは、このリポジトリの r402s-verify ブランチにあり、独自のワークフローを備え、ビルド済みのリリースバイナリを提供します。また、cargo build --release でもビルドできます。検証対象のプロトコル仕様と脅威モデルの全文は docs/kygit/ で公開されており、固定済みの適合性ベクトルは test-vectors/r402s-v0/ にあります。

コスト。 repos 専用の料金はありません。ボールトのバイト数は組織で共有するボールトクォータ（sourceBytes：prototype は 1 GB、hobby は 10 GB、team は 50 GB）の対象となります。これはプロジェクトが共有するストレージとは別のプールで、一意のオブジェクトごとに1回だけ課金されます。また、オブジェクトごとの計算上の下限は 4 KiB、ボールトごとの最低容量は 1 MiB です。

SDK: @run402/sdk

npm install @run402/sdk

エントリーポイントは 2 つです。

• @run402/sdk：アイソモーフィックです。CredentialsProvider（セッショントークンのシム、リモートボールト、プロジェクトキーと認証ヘッダーを解決するものなど）は独自に用意してください。Node 22、Deno、Bun、V8 分離環境で動作します。
• @run402/sdk/node：Node 専用の便利な機能を提供します。ローカルのプロファイル状態とプロジェクトキーの認証情報キャッシュ（credentials/project-keys.v1.json）を読み込み、1 つの決定的なソース（明示的な不透明な paymentSigner、明示的な walletPath、指定されたプロバイダーの readWallet()、またはデフォルトのアクティブプロファイルのウォレット）から x402 決済に署名します。認証と支払い元は意図的に異なる場合があります。選択した決済ソースが、暗黙のウォレットにフォールバックすることはありません。r.paymentPayer() は、安全な支払い元の公開情報のみを返します。また、sites.deployDir(...)、fileSetFromDir(...)、型付きデプロイマニフェストヘルパー（loadDeployManifest、normalizeDeployManifest）、および CLI と同じ Core/Cloud のターゲットを必要とするアプリのビルドスクリプト向けの resolveRun402TargetProfile() も公開します。

import { run402 } from "@run402/sdk/node";

const r = run402();
// Prepare the complete first-deploy manifest and referenced app files.
const result = await r.up({ name: "my-app", manifest: "run402.json" }, { approval: "yes" });
console.log(result);

SDK は用途別の名前空間で構成されています。actions（Node 用の再帰的なアクションランナー）、pay（任意の URL に対応する上限付き x402 購入者）、projects、snapshots、branches、archives、assets、cache、ci、sites、functions、jobs、secrets、subdomains、domains、email（webhooks を含む）、auth、apps、tier、billing、contracts、ai、wallets（ローカルウォレット：status、create、export、faucet。サーバーラベルも含みます）、service、admin、session（個人のサインインセッション：run402 login のループバックと --device の接続口、およびブラウザー画面）、writeApproval（run402 approve で使われるパスキーによる書き込み承認）、me（アカウントの概要とステータス）、wallets（サーバー側で署名されたウォレットラベル）、orgs（組織が所有するコントロールプレーンと r.org(id) サブクライアント）、grants（プロジェクトごとの機能付与）、identityLinks（公開され、プロトコルで区別される人間／エージェントの Nostr 帰属情報）に加え、段階的な複数リソースの書き込み向けに const project = await r.project(id); await project.apply(spec) を利用できます（リリーススライスと /apply/v1/* 経由のアセットスライス）。失敗時には、すべての操作が型付きの Run402Error サブクラスをスローします：PaymentRequired、PaymentBuyerError、ProjectNotFound、Unauthorized、ApiError、NetworkError、LocalError、Run402DeployError。apply() は安全な現在のベースに対する BASE_RELEASE_CONFLICT の競合を自動で再計画し、apply.retry の進行状況イベントを発行します。sdk/README.md を参照してください。

Buzz/Nostr のアイデンティティリンク

人間とエージェントは、別々に保有する Buzz/Nostr アイデンティティを Run402 のプリンシパルに公開して帰属させることができます。エージェントのリンクでは EOA と kind-1 のプロトコルを使用します。人間のリンクでは、通常のブラウザー、新しいパスキー、および https://console.run402.com/identity-links/connect で公開される Buzz の同意手続きを使用します。どちらも、識別用の proof_protocol を持つ同じ公開 idlnk_… リソース形式になります。1 つのプリンシパルに複数のアクティブな Nostr サブジェクトを関連付けることができますが、1 つのアクティブな Nostr サブジェクトを関連付けられるプリンシパルは 1 つだけです。これは帰属情報に限られます。Nostr アイデンティティが認証、認可、支払い、デプロイ、送金の受け取りに使われることはありません。Run402 は nsec、Nostr の秘密鍵、ニーモニック、シード、パスキー、セッション認証情報、導出パスを受け入れたり、そこから情報を導出したりすることはありません。

人間向けのインストール方法は Buzz のメッセージです。ターミナルは不要です。

Please install the run402.com skill.

これが人間向けの指示のすべてです。管理された Buzz のコンテキストでは、ファーストパーティの検出機能がこの指示を run402-buzz にルーティングします。エージェントは apex のインストールルーターを読み取り、自己完結型のスキルをワークスペース（通常はユーザーのホームディレクトリにある .buzz ディレクトリ）にインストールします。このリクエストはインストールと接続の両方を意味します。動作しないファイルであることを確認した後、エージェントはインストール済みのスキルを直接読み込み、同じターン内に事前確認、セットアップ、アイデンティティリンクの手続きを続けます。「次のターンで利用可能」として止まったり、セットアップについて再度質問したりすることはありません。Codex ランタイムの場合は、作業ディレクトリと環境をエージェントのコマンドランナーに別々に渡す方法を推奨します。

working_directory: <user-home>/.buzz
environment: { "DO_NOT_TRACK": "1" }
command: npx --yes skills@latest add https://run402.com -s run402-buzz -a codex -y

シェルのみの POSIX 環境では、次を使用します。

cd "$HOME/.buzz"
DO_NOT_TRACK=1 npx --yes skills@latest add https://run402.com -s run402-buzz -a codex -y

Windows PowerShell では、次を使用します。

Set-Location (Join-Path $HOME '.buzz')
$env:DO_NOT_TRACK = '1'
npx --yes skills@latest add https://run402.com -s run402-buzz -a codex -y

Claude Code では -a claude-code、Goose では -a goose を使用します。.agents/skills の利用が確認されている場合は -a universal を使用でき、Claude Code と Codex の両方では -a claude-code codex を使用します。universal は共有パスであり、すべてのランタイムを対象とするものではありません。また、無効な明示的ターゲット -a claude は使用しないでください。スキルのバイト列は、run402.com にある不変のダイジェスト検証済みアーティファクトから取得されますが、初回実行時の npx では npm が必要になる場合があります。GitHub は可用性のみを理由とする唯一のフォールバックであり、整合性の検証に失敗した場合はセットアップ前に停止します。成功すると、実際に確認されたファーストパーティのダイジェストと、管理対象ワークスペースの正確なパスが報告されます。GitHub ソースやグローバルなランタイムパスが、ファーストパーティのものとして誤って表示されることはありません。

ファイルのインストール段階では、何も実行されません。オンボーディングを続けると、永続的な公開 kind-1 Nostr イベントと、2 つの公開 ID を結び付ける永続的な Run402 証明が公開されます。取り消しを行っても履歴は消去されず、Buzz が管理するイベントでは、その所有者の公開 NIP-OA 証明も公開される場合があります。エージェントは必要な場合にのみ初期化を行い、リンクを作成または再利用して独立して検証したうえで、コンテキストに関連した簡易テストまたはデモを直ちに提示します。展開されたレシートには Deployment: none が保持されます。Windows ではセットアップヘルパーが、shell: false を使用して、npm と Run402 の JavaScript エントリーポイントを管理対象の正確な Node ランタイム経由で実行するため、.cmd のプロセス境界に関する障害を回避できます。ビルドまたはデプロイの前に、明示的な承認を待ちます。稼働中のアプリを独立して検証した後、実行されない永続的なオファーを作成し、通常の HTTPS「所有者になる」引き継ぎを投稿します。人間によるログイン／パスキーと、既存の Buzz の 6 桁の同意コールバックはブラウザーが担います。人間がターミナルでコマンドを実行したり、Buzz を変更したりする必要はありません。

前提条件、シークレットを使わない署名者モデル、リリース済みクライアントのフィクスチャ、移行ガイダンス、ワークフロー全体については、buzz/ ガイドを参照してください。または、skills.sh の正確な run402-buzz 掲載ページを確認してください。低レベルの CLI コマンドはデバッグ用に引き続き利用できますが、別のオンボーディング手段として用意されているものではありません。

コミュニティのコントロールプレーンでは、4 つの概念を分けて扱います。スキルのインストールは、何も実行しない共有機能です。コミュニティのインストールは、両者の同意後に Buzz リレーのコミュニティを Run402 組織に関連付けます。人間による採用では、ターミナル上の同意レシートを記録し、人間の公開 Buzz ID リンクを作成して、創設者エージェントの権限を降格させることなく通常の所有者メンバーシップを追加します。エージェントの登録では、後から参加する各エージェントのプリンシパルに対し、名前が指定された既存プロジェクトへの有効期限付きの限定的な許可のみを付与します。完了済みのレシート、公開の帰属情報、メンバーシップはそれぞれ独立しています。リンクを取り消しても組織の権限は削除されず、メンバーシップを削除してもリンクは取り消されず、レシートも書き換えられません。Buzz 自体には変更を加えません。同意の承認には、すでにリリース済みのブラウザーフラグメント／kind-1 の動作と、リリース済みの NIP-11／NIP-43 の証拠を使用し、オファー、組織、ディスクリプターの検出、ライフサイクルは Run402 が担います。run402 buzz status は機能検出によって古いゲートウェイを判別します。MCP は正確な HTTPS／CLI の次の手順のみを表示します。Fizz/Honey ワークフローを参照してください。 Astro SSR + ISR キャッシュ。 Astro アプリでは、@run402/astro 1.0 以降を使用してください。astro.config.mjs で export default run402(); を設定すると、SSR アダプター（Lambda + SnapStart + ISR キャッシュ + AsyncLocalStorage リクエストコンテキスト）、画像インテグレーション、ビルド時検出器を組み合わせた AstroUserConfig が返されます。関数は ReleaseSpec の FunctionSpec.class: "ssr" で SSR クラスを選択します。ゲートウェイは SnapStart をプロビジョニングし、(host, path, search, method, locale, release_id) をキーとして HTML レスポンスをキャッシュします。キャッシュはデフォルトでバイパスされます（Cache-Control で明示的に許可され、かつ Set-Cookie がなく、auth.* ヘルパーや決済プリミティブによる認証汚染フラグもない場合を除き、no-store です）。関数内コードまたは外部から無効化できます。SDK では r.cache.invalidate(url) / r.cache.invalidatePrefix({ host, prefix }) / r.cache.invalidateAll({ host })、CLI では run402 cache invalidate <url> を使用します。キャッシュ状態は r.cache.inspect(url) / run402 cache inspect <url> で確認できます。エージェント向け DX ヘルパーも CLI で利用できます。run402 doctor（5 つのヘルスチェック）、run402 dev（.env.local を使用した Astro 開発）、run402 logs --request-id req_...（関数間の相関付け）。詳細なリファレンスは astro/README.md と cli/llms-cli.txt（R402_* SSR Runtime Error Codes セクション）をご覧ください。

CLI：run402

npm install -g run402@latest

すべてのサブコマンドは stdout に JSON、stderr に JSON エラーを出力し、成功時は 0、失敗時は 1 で終了します。人間ではなく、エージェントのシェル向けに設計されています。詳細なリファレンスは cli/llms-cli.txt（https://docs.run402.com/llms-cli.txt にもあります）をご覧ください。これは初回デプロイに必要な契約全体を含むインデックスで、取得可能なトピック別スライス（/llms-cli-deploy.txt、/llms-cli-commands.txt、/llms-cli-functions.txt、…）の表も含まれています。/llms-cli-full.txt は全内容をまとめた単一のドキュメントです。

run402 up --name my-app -y                # recursive SDK action runner: init/tier/project/link/deploy
run402 up verify                          # rerun app HTTP verification without a deploy
run402 up --nested -y                     # app root inside another repo: its own nested repo + encrypted remote
run402 doctor                             # { ok, blocking[], warnings[], checks[] }: ok means this agent can ship
run402 logs --request-id req_abc123       # every function in the project; app output only (--all for the raw stream)
run402 init                              # one-shot wallet + faucet + tier check
run402 pay https://seller.example/resource --max-usd 0.05 --require-receipt
run402 status                            # organization snapshot (wallet, rail, balances, tier, projects)
run402 projects provision --name my-app
run402 projects sql <project_id> "CREATE TABLE …"
run402 projects validate-expose <project_id> --file manifest.json
run402 projects apply-expose <project_id> --file manifest.json
run402 sites deploy-dir ./dist
run402 deploy verify op_... --project <project_id> --wait  # confirm gateway/edge release coherence
run402 deploy releases active --project <project_id>  # inspect current-live release inventory
run402 deploy resolve https://example.com/events --project <project_id> --method GET
run402 deploy --manifest app.json --json     # deploy only; rehearses automatically when a live release has migrations to protect
run402 snapshots list prj_...
run402 branches create prj_... --ttl-days 7 --json
run402 functions deploy <project_id> <name> --file fn.ts
run402 functions runs create <project_id> <name> --event-type reminder.send --idempotency-key reminder:123 --delay 10m
run402 ci link github --project <project_id>       # GitHub Actions OIDC deploy binding (--route-scope for CI routes)
run402 assets put ./asset.png --immutable
run402 assets diagnose <url>             # inspect live CDN state for a public URL
run402 cdn wait-fresh <url> --sha <hex>  # poll until a mutable URL serves the new SHA

複合 CLI コマンドは up のみです。SDK アクションランナーを呼び出して steps[] を出力し、ワークスペースのプロジェクトを記録する必要がある場合は .run402/project.json に書き込みます。run402 Core に対して実行する場合、Cloud のウォレット／ティアの前提条件はスキップされ、Core プロジェクトが選択されていない場合は安全側に倒して失敗します。

リハーサルは自動で行われます。稼働中のリリースがあるプロジェクトに対して、マイグレーションを含む run402 up / run402 deploy を実行すると、隔離されたブランチでリハーサルされ、レポートが合格した場合にのみコミットされます（result.deploy.rehearsal）。初回デプロイでは保護すべきものがないため、直接コミットされます（reason: "no_live_release"）。マイグレーションがすべて適用済みでチェックサムも同一の再デプロイは migrations_unchanged としてスキップされるため、マイグレーションを含んだままのページのみの再デプロイは数秒で完了します。--no-rehearse を指定するとスキップできます。上級者向け：run402 deploy rehearse [<plan_id>] [--manifest <path>] はコミットせずにリハーサルを行います。保存済みのプラン、または現在のディレクトリにあるマニフェストを使用できます（プラン、アップロード、リハーサル）。手動の復元ポイントは run402 snapshots create|list|get|restore|delete で管理できます。復元はプラン／確認の 2 段階フローです。ブランチプロジェクトは run402 branches create|list|renew|delete で管理します。デフォルトの TTL は 7 日間で、メールはデフォルトでサンドボックス化され、noindex に設定されます。親プロジェクトに稼働中のリリースがない場合、ブランチは空になります。 HTML にキーを貼り付ける必要はありません。すべての Run402 ホストは、解決先のプロジェクトに応じて /_run402/config.js（window.RUN402 = { project_id, api_base, anon_key }）を提供します。run402 up は、このプリンシパルに名前がない場合にも名前を設定します。ランタイムで宣言されている場合は RUN402_AGENT_NAME を使い（既存の名前より優先されます）、そうでなければ検出されたクライアント（claude-code、codex、cursor、grok）を使います。独自のマーカーを持たないクライアントは RUN402_CLIENT=<name> で宣言でき、最初に確認されます。何も判明しない場合は何も書き込まれません。これにより、プロモーションのクレジットにあなたの名前が表示されます。run402 whoami --set-name <name> を使えば、いつでも名前を設定できます。result.identity は常に detected（今回の実行で検出されたクライアント）と detection: { applied, reason } を報告します。name_already_set は、クライアントが検出されたものの、プリンシパルにすでに名前が設定されていたことを意味します。projects provision は git に一切触れません。up はアプリのルートにのみ run402 リモートを作成します。アプリのルートが別のリポジトリ内にある場合は、--nested を渡さない限りスキップされ、次のアクションとして create_nested_repo が提示されます。--nested を渡すと独立したネストされたリポジトリになり、外側のリポジトリのローカル .git/info/exclude に1行が追加されます。それ以外には何も触れません。

ポータブルアーカイブは、Cloud プロジェクトのうち、ローカルの Core にインポートできる、サポート対象の run402 Core ランタイムの範囲をエクスポートします。これはロックインのない信頼経路であり、利用枠／支出上限による財務リスク制御とは別のものです。

run402 archives create <project_id> --target cloud --scope portable-runtime-v1 --auth stubs --consistency pause-writes --wait --output ./project.r402ar --json
run402 archives verify ./project.r402ar --json
run402 archives import ./project.r402ar --target core --name imported-project --env-file ./required.env --json

--target は、各動詞が対象とするデプロイ先を指定します。create、status、download は Run402 Cloud からエクスポートします（--target cloud がデフォルト）。import はローカルの Run402 Core に読み込みます（--target core がデフォルト）。アーカイブ v1 には、シークレットの値、認証情報、ログ、請求／利用枠の状態、Cloud の操作メタデータ、Cloud へのインポート、および既存プロジェクトへのマージインポートは含まれません。検証はローカルかつオフラインで行われ、整合性と互換性を確認します。Core へのインポートで検証され、ステージングされるまでは、アーカイブは信頼できない入力として扱われます。

アクティブなプロジェクトは保持されます。run402 projects use <project_id> は <project_id> をサーバーで検証し、以降の <project_id> を受け取るサブコマンドのデフォルトとして保存するため、ほとんどのコマンドで指定を省略できます。ローカルのキー素材は run402 credentials project-keys ... で別途管理されます。このキャッシュがプロジェクト一覧に含まれることはありません。

MCP サーバー：run402-mcp

npx -y run402-mcp                        # standalone test

ホストのコンテキストに含まれるスキーマは数キロバイトで、ツールは8つです。最初のデプロイに使う up と deploy、そして status、whoami、doctor、docs、run、expand_result です。それ以外の処理はすべて、Node SDK クライアントである r に対する run スニペットとして、独自のファイルシステム、プロセス、ネットワークを持たない WebAssembly 上の QuickJS サンドボックスで実行されます。Node.js 22.13 以降が必要です。**ローカルで動作するため、実際に支払いができます。**x402 の支払いには署名キーが必要なので、ウォレットを持たないリモートサーバーでは支払いを実行できません。

リモートエンドポイント（インストール不要）

ホスト型のストリーミング可能な HTTP MCP サーバーが https://mcp.run402.com/mcp で稼働しており、無料の検出ツールのみを提供します。ツールは run402_quickstart、x402_price_check（任意の URL の x402 チャレンジを支払いなしでデコード）、experiment_scoreboard です。資金を扱うことはありません。有料機能（画像生成、デプロイ、支払い）には、あなたのウォレットを保持する以下のローカルサーバーが必要です。レジストリエントリ com.run402/mcp には、両方（npm の packages[] と remotes[]）が登録されています。リモート自体も run402 関数として実行されます。つまり、このプラットフォーム自身が MCP サーバーをホストしています。

Stdio MCP トランスポートでは、stdout を JSON-RPC 専用にする必要があります。パッケージの bin（npx -y run402-mcp）を使うか、ビルド済みチェックアウトから node dist/index.js を実行してください。ホストが npm start を要求する場合は、npm_config_loglevel=silent を設定してください。npm のライフサイクルバナーは stdout に出力されるため、設定しないと JSON ではない前置テキストとして表示されます。リポジトリの .npmrc と Docker イメージでは、ソース／コンテナのホスト向けにこの設定を行っています。

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "run402": { "command": "npx", "args": ["-y", "run402-mcp"] }
  }
}

Cursor

.cursor/mcp.json に追加します。

{
  "mcpServers": {
    "run402": { "command": "npx", "args": ["-y", "run402-mcp"] }
  }
}

Cline

Cline の MCP 設定に追加します。

{
  "mcpServers": {
    "run402": { "command": "npx", "args": ["-y", "run402-mcp"] }
  }
}

Claude Code

claude mcp add run402 -- npx -y run402-mcp

OpenClaw スキル

cp -r openclaw ~/.openclaw/skills/run402
cd ~/.openclaw/skills/run402/scripts && npm install

各スクリプトは cli/lib/*.mjs から再エクスポートします。OpenClaw のコマンドサーフェスは、構造上、CLI のコマンドサーフェスと同一です。openclaw/README.md を参照してください。

MCP ツール

ツール	機能
up	初回デプロイを行います。不足しているセットアップ（ウォレット、ティア、プロジェクト、ワークスペースリンク）を整えてから、デプロイします。run402.up.result エンベロープを返します。
deploy	ReleaseSpec をプロジェクトに適用します（r.project(id).apply）。データベース、関数、サイト、site.public_paths、アセット、サブドメイン、routes.replace が対象です。DeployResult を返します。
status	r.status()：サーバーが動作するウォレット（local_label、server_label、アドレス）、ティアとリース、利用可能額、プロジェクト、アクティブなプロジェクトを返します。
whoami	r.orgs.whoami()：リモートのプリンシパル、その認証手段、組織のメンバーシップ、サインインセッションのグレードを返します。
doctor	r.doctor()：{ ok, blocking[], warnings[], checks[] } を返します。
docs	パッケージに同梱されている SDK リファレンスと run の入門資料です。topic（名前空間またはセクション）か search を指定します。
run	サンドボックス内で SDK に対して TypeScript スニペットを実行し、値、取得したログ、実行した SDK 呼び出しを返します。
expand_result	保存された結果（run の値またはログ、docs の回答、up の詳細）をページ分割して返します。

スニペットは非同期関数の本体です。最後の式の値が結果になります。

{ "code": "const { projects } = await r.projects.list();\nprojects.filter((p) => !p.site_url).map((p) => p.id)" }

結果は { status, value, value_ref, shown, total, logs, logs_ref, calls, duration_ms, wallet, error? } です。大きな値は項目単位で全体が保存され（配列の要素、結果の rows など）、先頭からの項目全体が structuredContent 内も含めて value_window に返されます（残りは expand_result で項目単位にページ分割して取得します）。calls[] には結果とともにすべての SDK 呼び出しが記録され、タイムアウト（デフォルトは 60 秒、最長 300 秒）時にも、完了した呼び出しが記録されます。SDK エラーは独自の code と next_actions を保持したまま返されます。

構造化された結果。 すべてのツールは、宣言された outputSchema に基づく結果も structuredContent として返すため、ホストはテキストを解析せずにフィールドを読み取れます。オブジェクトには status: "ok" | "error" が含まれます。固定ツールは SDK オブジェクトを result の下に格納し、すべてのエラーには error.code、error.message、error.next_actions が含まれます。テキスト内のフェンス付き JSON は同じオブジェクトです。

一度限りのシークレットは CLI 内にとどまります。 一度限りのシークレットを返す、または使用する操作（グラントキーの発行やローテーション、Handoff または Invite Key、Room Invite Key、プロジェクトのプロビジョニングや認証情報のローテーション、プロジェクトトークン、ウォレットの作成、インポート、エクスポート、Lightning のペアリング）は、run 内での実行を拒否し、SECRET_REQUIRES_CLI と 1 つの次のアクション { "type": "run_cli_command", "command": "run402 …" } を返します。このアクションには、ユーザーに実行してもらう正確なコマンドが指定されます。この拒否はリクエストを送る前に SDK メソッド自体で行われるため、シークレットが結果に含まれることはありません。

完全なリファレンス： llms-mcp.txt 。

設定

変数	デフォルト	用途
RUN402_API_BASE	https://api.run402.com	API のベース URL（ステージング環境で上書きします）
RUN402_CONFIG_DIR	~/.config/run402	ローカル認証情報の保存先ベースディレクトリ（名前付きウォレットは profiles/<name>/ に保存されます）
RUN402_WALLET	default	アクティブな名前付きウォレット（プロファイル）。--wallet <name> およびディレクトリごとの .run402.json で上書きされます。RUN402_PROFILE はエイリアスです。run402 wallets を参照してください。
RUN402_WALLET_PATH	{config_dir}/wallet.json	カスタムウォレットファイルのパス
RUN402_GRANT_KEY	(未設定)	run402 grants create --key で取得するグラントキーのベアラー値。設定すると、これだけが認証情報として送信されるため、ウォレットのないプロセスでもデプロイできます。

ローカル状態は次の場所に保存されます。

• プロファイルの state.json：アクティブなプロジェクトのポインターとプロファイルの状態
• プロファイルの credentials/project-keys.v1.json（0600）：明示的に認証情報が必要な操作で使用するローカルの匿名キー／サービスキーのキャッシュ
• ~/.config/run402/wallet.json（0600）：x402／MPP の署名に使用するウォレット

レガシー形式の projects.json ファイルは、一方向の移行入力としてのみ使用されます。anon_key と service_key に有効期限はありません。リースの適用はサーバー側で行われます。run402 credentials project-keys status --project <project_id> でキャッシュの状態を確認し、シークレットのエクスポートには run402 credentials project-keys export --project <project_id> --reveal のみを使用してください。

開発

npm run build           # builds core/, sdk/, then the MCP server
npm test                # SKILL + sync + unit tests
npm run test:e2e        # builds generated CLI SDK mirrors, then runs CLI end-to-end tests
npm run test:sync       # checks MCP/CLI/OpenClaw/SDK stay in sync
npm run test:skill      # validates SKILL.md frontmatter + body

アーキテクチャ：すべてのツール／サブコマンド／スキルスクリプトは、@run402/sdk の呼び出しをラップする薄いシムです。core/ には、SDK の Node プロバイダーでラップされた Node 専用のファイルシステムプリミティブ（キーストア、ウォレット、SIWE 署名）が含まれます。全体の構成については、CLAUDE.md を参照してください。

リンク

• ウェブサイト：https://run402.com
• セルフホストバックエンド（run402 Core）：https://github.com/kychee-com/run402-core
• API ドキュメント（HTTP）：https://run402.com/llms.txt · https://run402.com/openapi.json
• CLI ドキュメント：https://docs.run402.com/llms-cli.txt（インデックスと取得可能な分割版。リファレンス全体は https://docs.run402.com/llms-cli-full.txt を参照）
• ステータス：https://api.run402.com/status
• ヘルス：https://api.run402.com/health

ライセンス

このリポジトリ（エージェント向けインターフェース：SDK、CLI、MCP サーバー、Astro インテグレーション、OpenClaw スキル）は MIT ライセンスです。バックエンド全体である run402-core は Apache-2.0 ライセンスです。