サンドボックス API リファレンス：Python と TypeScript の SDK

SDK はサンドボックスの REST API を薄く包んだものです。リクエストを手で組み立てること、プラットフォームが混んでいるときの再試行、コードが例外を投げたときのサンドボックスの消し忘れ、という三つの手間を省きます。このページの内容は両パッケージのバージョン 0.2.0 に対応しています。

まだサンドボックスを作ったことがなければ、5 分でできる接続ガイド でまずトークンを取得してください。サンドボックスとは何か、中に何があるかは サンドボックス にあります。

インストールと設定

pip install eqvps          # Python 3.8+
npm i @eqvps/sdk           # Node.js 18+, Deno, Bun
export EQVPS_API_KEY=...   # your EQVPS account token

両方の言語で同じプログラム：サンドボックスを作り、コードを実行し、削除します。

from eqvps import Sandbox

with Sandbox.create(tariff="small") as sb:
    r = sb.run("print(2 + 2)")
    print(r.exit_code, r.stdout)   # 0 4

import { Sandbox } from "@eqvps/sdk";

await Sandbox.with({ tariff: "small" }, async (sb) => {
  const r = await sb.run("print(2 + 2)");
  console.log(r.exit_code, r.stdout); // 0 4
});

サンドボックスの作成と検索

Sandbox.create(...) はサンドボックスを起動します。通常は約 1 秒です。Python はキーワード引数、TypeScript はオプションのオブジェクトを受け取ります。

Sandbox.connect(id) は既存のサンドボックスに接続します。多くは昨日作ったパーシステントなものです。Sandbox.list() はアカウントのすべてのサンドボックス（稼働中と一時停止中）を返します。

プロパティ：id（sb_ + 16 進 24 文字）、mode、tariff、state（running、starting、paused、pausing、resuming、deleting、deleted）、env_keys / envKeys（名前だけで、値は返りません）、info（生のオブジェクト）。refresh() で再読み込みします。

kill() はサンドボックスを削除し、課金を止めます。すでに存在しないサンドボックスに対して呼んでもエラーにはなりません。

コードの実行

run(code, language="python", timeout=30) はコードを stdin 経由で Python 3.12、Node.js 22、bash（"python"、"node"、"bash"）に渡します。exec(command, cwd=None, stdin=None, timeout=30) はシェルコマンドを実行します。文字列は bash -lc を通り、リストはシェルを介さず argv として実行されます。

どちらも ExecResult を返します：

同期呼び出しは 最長 55 秒 です。どちらのメソッドもその呼び出しだけに効く env を受け取り、作成時に設定した値を上書きします。

長いジョブ：バックグラウンドタスク

background=True（TypeScript では { background: true }）を渡すと、すぐに Task が返ります。55 秒の制限はなく、サンドボックスの寿命が尽きるまで動かせます。1 サンドボックスあたり最大 8 タスクです。

task = sb.exec("cd /root/app && python3 -m pytest -q", background=True)
result = task.wait(on_output=lambda out, err: print(out, end=""))
print(result.state, result.exit_code)   # done 0

const task = await sb.exec("cd /root/app && npm test", { background: true });
const result = await task.wait({ onOutput: (out) => process.stdout.write(out) });

wait 自身のタイムアウトに達すると SandboxTimeoutError を投げますが、タスクは動き続けます。実行中のタスクがあると、エフェメラルなサンドボックスが無操作で削除されることもありません。

ファイルと使用量

upload(path, content, mode=None) は絶対パスにファイルを書き込み、サイズを返します。download(path) はバイト列を、download_text(path) / downloadText(path) は文字列を返します。1 回の転送は 5 MB までです。

usage() は稼働秒数、使用した CPU 秒数、送信バイト数、時間あたりの料金、billed_usd、estimated_total_usd を返します。tariffs() はキー不要の普通の関数で、現在の料金と制限を返します。課金ルールは サンドボックスの制限と課金 にあります。

エラー

API のエラーはすべて EqvpsError のサブクラスで、status（HTTP）、code（安定した文字列）、body を持ちます。サーバーが送ってきた場合は retry_after / retryAfter が入ります。

429 の大半は二つの制限から来ます。1 アカウントで 同時に実行できるコマンドは 2 つ、保持できるサンドボックスは 20 個まで です。待ち時間をサーバーが示したとき SDK は再試行し、3 回失敗すると例外になります。

SDK が不要な場合

HTTP クライアントがあればどの言語からでも API を直接呼べます。エンドポイントは https://eqvps.com/openapi.json の OpenAPI ファイルにあります。Claude や Cursor、その他の MCP クライアントで動くエージェントにはコードすら不要です。MCP サーバー に同じサンドボックスのツールがあります。動くところを見てみたいだけなら、サンドボックスのページ にプランと新規アカウント向けの $1 トライアルが載っています。