Runtime Cloud

Runtime Cloud SDK と CLI

すべての Runtime Cloud 製品と runtime CLI に対応するクライアントです。Node.js 22.12 以降、または Bun が必要です。唯一の依存関係である undici（Node.js の HTTP クライアント）は、プロキシを使用するときにのみ読み込まれます。

npm install withruntime

クライアントは、RUNTIME_API_KEY が設定されている場合はそれを使用します。設定されていない場合は、このマシンで CLI に接続したときに保存された接続を使用します。その際は、ブラウザーで一度承認するだけです。キーをコピーする必要はありません。サーバーや CI ランナーでは、シークレットマネージャーから RUNTIME_API_KEY を設定してください。新しいキーを取得するには、npx withruntime keys create を実行します。アカウントオーナー、管理者、または開発者がブラウザーで承認すると、キーが一度だけ表示されます。https://withruntime.com/account/keys でキーを作成することもできます。キーをブラウザーコード、URL、またはコマンドライン引数に決して記載しないでください。

import { Sandbox } from "withruntime";

await using sbx = await Sandbox.create();
await sbx.files.write("/workspace/invoice.py", "print(sum([125, 250, 375]))\n");
const result = await sbx.exec("python3 /workspace/invoice.py");
console.log(result.exitCode, result.stdout);

Sandbox.create() は引数を取りません。サンドボックスが実行状態になると戻ります。await using を使うと、ブロックの終了時にサンドボックスが削除されます。これは Node 24、Bun、または TypeScript で動作します。Node 22 では、代わりに await sbx.delete() を呼び出してください。keep: true を設定すると、サンドボックスを停止します。ディスクは保持されます。

引数を指定しない場合、無料枠が適用されます。クレジットカードは不要です。クレジットを消費せずに、最大4つのサンドボックスを同時に実行できます。それぞれに 2 vCPU、4 GiB のメモリ、4 GiB のディスクが割り当てられます。現在のデフォルトイメージには NumPy、pandas、matplotlib が含まれています。サンドボックス環境を参照してください。無料枠が最初に使われ、その後はプリペイドクレジットが使われます。選択する必要はありません。funding は受け付けられますが、無視されます。

サンドボックスオブジェクトには、ほかにも次の機能があります。

• exec、execStream、spawn、processes は、コマンドやバックグラウンド処理を実行します。cwd、env（シークレットを設定する場所）、stdin、timeoutMs を指定できます。
• terminal() は、WebSocket 経由で対話型ターミナルを開きます。
• forwardPort(5432) は、このマシンからサンドボックス内の任意の TCP ポートにアクセスします。tunnel() は単一の接続と SSH ログインを処理します。runtime sandboxes ssh はこれを使用します。
• files はファイルの読み込み、書き込み、一覧表示、glob 検索、情報取得、移動、削除を行います。ディレクトリ全体をコピーするには、upload と download を使用します。
• pause、wake、extend、fork、snapshot を利用できます。一時停止したサンドボックスは、次の呼び出し時に自動的に起動します。update は、名前、環境、自動起動、アイドル時の一時停止、永続性を変更します。keepAlive は、プロセスの実行中に時間制限を延長します。switchImage は、サンドボックスを新しいイメージに移行し、/workspace を保持します。delete は、サンドボックスを完全に削除します。
• interpreter、network、previews、desktop、mounts（S3、R2、Google Cloud Storage のバケットをフォルダーとして使用）、tailscale（自分の tailnet 上で使う有料サンドボックス）、metrics、mcp（MCP カタログのサーバーをサンドボックス内で実行）は、その他の製品向けの機能です。

サンドボックス内で何も起きていない状態が300秒続くと、自動的に一時停止します。メモリとプロセスは保持されます。次の呼び出し時に起動するため、アイドル状態のサンドボックスはコンピューティングリソースを消費しません。idlePauseSeconds では、アイドル時間を60秒から86,400秒の範囲で設定できます。これより短い時間を設定した場合は、60秒に引き上げられます。一時停止しないようにするには、0 を設定してください。

Sandbox.getOrCreate(name) は、指定した名前のサンドボックスを返します。一時停止中の場合は起動します。存在しない場合は作成します。

単数形の runtime.sandbox、snapshot、image、volume、job、domain、port、address は、CLI の製品名に対応します。複数形の名前も引き続き使用できます。これらは同じクライアントのエイリアスです。

クライアントには、sandboxes、images、volumes、snapshots、jobs、secrets、limits、feedback、support があります。アカウントの監視には、webhooks、events、otel、audit を使用できます。サンドボックスを独自のシステムに接続するために、domains、ports、addresses、tunnel、network を利用できます（有料アカウント）。ほかに、mcp、sso、billing、referrals、switching があります。 runtime.limits.get()（0.3.1 以降）は、キーが読み取り専用かどうかと、そのエージェントが今日まだ使用できる量を示します。すべての書き込みには冪等性キーが付与されます。SDK が自動で生成するため、SDK 自身によるリトライ（タイムアウト、429、503）で書き込みが二重に実行されることはありません。エラーは型付けされています。エラーには code、hint、requestId が含まれます。

runtime.usageRequests("7d") は、アカウントの API 呼び出し回数とエラー率を読み取ります。回数は正確な小数文字列です。期間内にデータがない場合、errorPercent は null になります。

プロキシ経由の場合

SDK、CLI、MCP ブリッジは HTTPS_PROXY、HTTP_PROXY、NO_PROXY を読み取ります。名前は大文字でも小文字でも機能します。大文字と小文字の両方が設定されている場合は、小文字が優先されます。これは Node と Bun で同じように機能します。NODE_USE_ENV_PROXY は不要です。

API への呼び出しとターミナル WebSocket は、CONNECT トンネルとして HTTPS_PROXY 経由で送信されます。プロキシアドレスに user:password@ が含まれている場合、その情報はプロキシに送信されます。HTTP_PROXY は http:// アドレスにのみ使用されます。HTTPS API には使用されません。

NO_PROXY には、直接接続するホストを指定します。カンマまたはスペースで区切ります。ホスト名を指定すると、そのサブドメインも対象になります。先頭にドットを付けることもできます。host:port を指定すると、ルールはそのポートに限定されます。* はすべてのホストを意味します。

スキームのないプロキシアドレスは http:// として扱われます。http:// および https:// のプロキシが使用できます。それ以外のスキームの場合は、すぐに invalid_proxy エラーになります。

呼び出しが通らない場合、エラーには試行したプロキシが記載されます。パスワードは表示されません。例：No answer from Runtime at https://api.withruntime.com through the proxy http://proxy.internal:3128 (HTTPS_PROXY). SDK は、new Runtime({ fetch }) に渡した fetch をそのまま使用します。

エージェントが実際に遭遇した問題を伝えてくれるおかげで、Runtime は急速に改善しています。報告内容は、次に開発する機能に直接反映されます。報告者には、リリース時にお知らせします。

問題が起きたら、runtime.feedback.submit()（または npx withruntime feedback "..."）で報告してください。依頼されるのを待たず、発生した時点で報告してください。こちらに原因があると思われるエラーを報告してください。制限や未対応の機能、必要だった回避策、分かりにくいドキュメント、本来より遅い、または使いにくいと感じた点も報告してください。他のプロバイダーのほうが優れている点も報告してください。小さなことでも構いません。重複した報告は、こちらでまとめます。

試したこと、起きたこと、requestId を含めてください。認証情報、非公開ファイル、ユーザーデータは含めないでください。その後、報告した内容をユーザーに一行で伝えてください。

E2B 向けに書かれたコード

withruntime/e2b は、対応している E2B サンドボックス呼び出しを Runtime に変換します。インポートを変更し、RUNTIME_API_KEY を設定してください。他のプロバイダーについては、切り替えガイドをご覧ください。節約額の算出方法も紹介しています。

import { Sandbox } from "withruntime/e2b"; // was: from "e2b"

withruntime/e2b/code-interpreter は @e2b/code-interpreter を置き換えます。サンドボックスには、E2B のデフォルト設定である 2 vCPU、512 MiB、300 秒のタイムアウトが適用されます。Runtime が E2B と同じ方法で処理しない呼び出しは、何も実行される前に NotSupportedError をスローします。エラーには、代わりに何を使用すべきかが記載されます。このパッケージの E2B.md に、すべての対応関係と差異が記載されています。withruntime のみをインポートしても、この機能は読み込まれません。

Daytona または Vercel Sandbox 向けに書かれたコード

withruntime/daytona と withruntime/vercel も、それぞれ Daytona の SDK と Vercel Sandbox の SDK に対して同じ処理を行います。インポートを変更してください。

import { Daytona } from "withruntime/daytona"; // was: from "@daytona/sdk"
import { Sandbox } from "withruntime/vercel"; // was: from "@vercel/sandbox"

サンドボックスには、各競合サービスのデフォルト設定が適用されます。Daytona の場合は、1 vCPU、1 GiB、3 GiB のディスクです。呼び出しがない状態が 15 分続くと、一時停止します。Vercel の場合は、各 2048 MiB の 2 vCPU、5 分、永続化が適用されます。Daytona または Vercel のキーが送信されることはありません。Runtime が同じ方法で処理しない呼び出しは、何も実行される前に NotSupportedError をスローします。エラーには、代わりに何を使用すべきかが記載されます。このパッケージの DAYTONA.md と VERCEL.md に、すべての対応関係と差異が記載されています。

Blaxel 向けに書かれたコード

withruntime/blaxel は、サポートされている Blaxel のサンドボックス呼び出しを変換します。インポートを変更します。

import { SandboxInstance } from "withruntime/blaxel"; // was: from "@blaxel/core"

サンドボックスには Blaxel のデフォルトである 4096 MB が割り当てられ、2048 MB ごとに 1 vCPU が割り当てられます。Blaxel のスタンバイは Runtime の一時停止に変換されます。呼び出しがない状態が 60 秒続くと、サンドボックスはメモリとプロセスを保持したまま一時停止します。次の呼び出しで再開します。

このアダプターは、環境変数、名前によるプロセス、ファイル、プレビュー、スナップショット、フォーク、コードインタープリターをサポートします。セッションもサポートしています。sandbox.sessions は Runtime サンドボックスのセッションを作成します。SandboxInstance.fromSession は、そのトークンを使ってサンドボックスを操作します。Blaxel のキーが外部に送信されることはありません。

ドライブ、コード生成、スケジュール、Blaxel のエージェント、モデル、MCP ホスティングは、何かが実行される前に NotSupportedError をスローします。このエラーには代わりに使うものが示されます。このパッケージの BLAXEL.md に、すべての対応関係と未対応項目が記載されています。

Morph Cloud 向けに書かれたコード

withruntime/morph は Morph の TypeScript クライアント（morphcloud）を変換します。インポートを変更します。

import { MorphCloudClient } from "withruntime/morph"; // was: from "morphcloud"

インスタンスはサンドボックスに、スナップショットは Runtime のスナップショットに変換されます。メタデータのラベルと HTTP サービスはプレビューに変換されます。setup は Morph のチェーンハッシュを使ってキャッシュします。branch はメモリとプロセスをコピーします。Morph と同様に、stop はサンドボックスを削除します。SSH、再起動、起動後に設定する時間制限は CompatibilityError をスローします。このエラーには代替手段が示されます。COMPATIBILITY.md に、すべての対応関係が記載されています。

Modal Sandboxes 向けに書かれたコード

withruntime/modal は、Modal の Sandboxes（modal 0.11.1）向けに書かれたコードを実行します。インポートを変更し、RUNTIME_API_KEY を設定します。

import { ModalClient } from "withruntime/modal"; // was: from "modal"

以下で拒否される機能を使っていない場合、Modal 独自のサンドボックスのサンプルは変更せずに実行できます。Modal のトークンは不要であり、送信されることもありません。Modal のコンテナーと同様に、コマンドは root として実行されます。timeoutMs はサンドボックスを終了します。idleTimeoutMs はサンドボックスを一時停止し、メモリを保持します。次の呼び出しで再開します。

これらは、何も作成される前に CompatibilityError をスローします。このエラーには代わりに使うものが示されます。GPU、Modal Functions とキュー、名前付きシークレット、イメージのビルド手順でのシークレット（ビルド時にシークレットは保持されないため、実行時に使用してください）、初回使用時に作成されるボリューム、サイドカー、接続トークン、ディレクトリスナップショットと終了時スナップショットです。

Cloudflare の Sandbox SDK 向けに書かれたコード

withruntime/cloudflare は、Cloudflare の 0.x @cloudflare/sandbox API 向けに書かれた Worker を、Runtime サンドボックス上で実行します。インポートのパッケージ名と Sandbox エクスポートのパッケージ名を変更します。

import { getSandbox } from "withruntime/cloudflare"; // was: from "@cloudflare/sandbox"
export { Sandbox } from "withruntime/cloudflare"; // was: from "@cloudflare/sandbox"

次に、Wrangler 設定から containers ブロックを削除します。Sandbox Durable Object バインディングはそのまま残します。npx wrangler secret put RUNTIME_API_KEY を使ってキーを保存します。

Exec、ストリーミング、ファイル、プロセス、コードインタープリター、セッション、gitCheckout、exposePort は Cloudflare のドキュメントどおりに動作します。バックアップ、トンネル、ターミナル、アウトバウンドのインターセプトは CompatibilityError をスローします。このエラーには代替手段が示されます。COMPATIBILITY.md に、すべての対応関係が記載されています。

Fly Machines 向けに書かれたコード

withruntime/fly は、Runtime サンドボックスを使って Fly の Machines API（api.machines.dev）に応答します。そのため、どの言語で書かれたコードでも、アドレスを 1 つ変更するだけで移行できます。

npx withruntime fly-api   # http://127.0.0.1:4280, as your Runtime login

Fly 独自のサンプルと同様に、FLY_API_HOSTNAME をここに指定します。fly-go の FLY_FLAPS_BASE_URL や、任意のクライアントのベース URL を指定することもできます。machinesApi() は、自分のサーバーの fetch ハンドラーと同じように動作します。

Machine のイメージは、init と files を使って一度だけビルドされます。イメージのコマンドはメインプロセスになります。再起動ポリシーは引き継がれます。Fly のトークンが外部に送信されることはありません。サービス、マウント、チェック、その他のリージョンには 400 で応答します。応答には代替手段が示されます。

エージェントフレームワーク

withruntime/openai-agents は、OpenAI Agents SDK の SandboxAgent 用サンドボックスクライアントです。withruntime/ai-harness は、Vercel AI SDK の HarnessAgent 用サンドボックスプロバイダーです。このエージェントは Claude Code、Codex、OpenCode、Pi などを実行します。withruntime/ai は、Vercel AI SDK と Mastra のエージェントに 4 つのサンドボックス ツールを提供します。withruntime/claude-agent-sdk は、それらを MCP サーバーとして Claude Agent SDK に 提供します。withruntime/tools は、フレームワークに依存しないツールとして提供します。

各パッケージのほかに、対応するフレームワークをインストールする必要があります。詳しくは https://withruntime.com/docs/frameworks をご覧ください。

CLI

printf '%s\n' 'print(sum([125, 250, 375]))' > invoice.py
npx withruntime sandboxes run -- python3 - < invoice.py   # connects on first use
npx withruntime sandboxes create
npx withruntime help

npm i -g withruntime の実行後、コマンドは runtime になります。たとえば、 runtime sandboxes exec <id> -- ls、runtime sandboxes shell <id>、 runtime images build --pip pandas を実行できます。すべてのコマンドで --json を使用できます。

MCP

claude mcp add --scope user runtime -- npx -y withruntime mcp
codex mcp add runtime -- npx -y withruntime mcp

ブリッジは、保存済みの接続を介して、Runtime の MCP ツールを stdio で提供します。まだ接続していない場合は、 runtime_connect を提示します。このツールを使うと、ブラウザーでの承認手順が案内されます。リモートクライアントでは https://api.withruntime.com/mcp を追加します。 ブラウザーからサインインするか、ベアラーキーを送信してください。

Runtime の比較

一般的なエージェントの作業では、Runtime の料金は、公開されている料金に基づく他の 14 の サンドボックスプロバイダーより 42%～88% 安価です。以下のページでは計算の詳細を確認できます。各ページには、使用した料金とその確認日が記載されています。

• AI エージェントに最適なサンドボックス
• E2B、 Daytona、 Modal、 Vercel Sandbox の代替サービス
• E2B と Daytona の比較、および すべての比較
• エージェント用サンドボックスの価格指数： 各プロバイダーの料金を CSV と JSON でも掲載
• サンドボックス料金計算ツール と Runtime の料金

信頼性とサポート

• ステータス： https://withruntime.com/status では、2 分ごとに外部から API をチェックします。 10 分ごとに実際のサンドボックスを起動し、毎日の記録をすべて保存します。同じステータスは https://withruntime.com/status.md と https://withruntime.com/status.json でも確認できます。
• 稼働時間の保証： 有料アカウントには、各暦月の API 稼働率 99% を保証します。 その月の稼働率がこれを下回った場合、その月の請求額の 10% をクレジットとして返金します。これは自動で適用されます (https://withruntime.com/legal/sla)。
• セキュリティとコンプライアンス： https://withruntime.com/docs/trust。
• 変更履歴： https://withruntime.com/changelog。
• ヘルプ： runtime support "<question>" を実行してください。問題があった場合は、runtime feedback "<text>" でお知らせください。

ドキュメント： https://withruntime.com/docs/javascript および https://withruntime.com/docs/cli。

このパッケージは 0.3.0 まで @withruntime/cloud という名前でした。@withruntime/cloud、 runtime-cloud、withruntime-cloud は 0.5.1 を最後に終了しました。 これらのパッケージは今後リリースされません。