試すのにクレジットカードは必要ですか？

不要です。新しいアカウントは、残高が足りない状態で初めてサンドボックスを作成したときに 1 ドルのサンドボックス用クレジットを受け取ります。このガイド全体で使うのはそのうち 1 セントにも届きません。その後は暗号資産で残高をチャージします。

サンドボックスの中で pip でパッケージを入れられますか？

入れられます。サンドボックスは外向きのインターネットに接続でき、pip は virtualenv なしでシステムにインストールします。torch のような大きなパッケージはディスクとメモリを多く使うので、plus 以上のプランを選んでください。

コマンドが 30 秒で止まるのはなぜですか？

run と exec のデフォルトのタイムアウトは 30 秒で、同期呼び出しの上限は 55 秒です。それより長い処理は、この上限がない background=True で実行してください。

スクリプトがクラッシュしてもサンドボックスは削除されますか？

with ブロックを使えば削除されます。ブロックを抜けた時点で、例外が起きた場合も含めて削除されます。使わない場合、一時サンドボックスは 5 分間操作がないと削除され、その 5 分も課金されます。

Python コードサンドボックス SDK を 5 分で：6 ステップ

EQVPS の Python SDK をインストールし、Firecracker サンドボックスを起動して、コードの実行、パッケージのインストール、ファイルの受け渡し、長いジョブのバックグラウンド実行までを行います。6 ステップでコマンドはすべて掲載、費用は合計 1 セント未満です。

このガイドでは、ゼロから Python で動くサンドボックスまでを進めます。隔離された Firecracker の microVM を起動し、コードを実行し、パッケージを入れ、ファイルを出し入れし、時間のかかる処理をバックグラウンドで動かします。どのステップも、貼り付けるだけの数行です。

必要なのは Python 3.8 以降と EQVPS アカウントです。SDK に依存パッケージはありません。

1. トークンを用意する

サンドボックスの料金はアカウント残高から支払われるため、SDK にはアカウントトークンが必要です。アカウントの接続に、ダッシュボード、API、MCP サーバーの 3 つの取得方法が載っています。取得したら環境変数に設定します。

export EQVPS_API_KEY="your-token"

まだ残高がなくても大丈夫です。新しいアカウントが残高不足のまま初めてサンドボックスを作成すると、14 日間有効な 1 ドルのサンドボックス用クレジットが付与されます。

2. SDK をインストールする

pip install eqvps

3. サンドボックスを起動してコードを実行する

次の内容を hello.py として保存し、実行します。

from eqvps import Sandbox

with Sandbox.create(tariff="small") as sb:
    print(sb.id)
    r = sb.run("import platform; print(platform.python_version())")
    print(r.exit_code, r.stdout)

サンドボックスの id（sb_ に続く 24 文字）、続いて 0 3.12.x が表示されます。サンドボックスは約 1 秒で起動し、コードを実行し、with ブロックが終わると削除されました。

結果について知っておきたい点：

終了コードが 0 でタイムアウトしていなければ r.ok は true になります。
0 以外の終了コードは例外ではありません。r.ok は自分で確認してください。
stdout と stderr はそれぞれ 1 MiB までで、出力が切り詰められたかどうかは r.truncated でわかります。

4. パッケージを入れてシェルコマンドを実行する

サンドボックスの中では、Python、Node.js、git、curl が入った小さな Linux システムの root です。exec は任意のシェルコマンドを実行します。

from eqvps import Sandbox

with Sandbox.create(tariff="small") as sb:
    sb.exec("pip install --quiet requests", timeout=55)
    r = sb.run("import requests; print(requests.get('https://example.com').status_code)")
    print(r.stdout)   # 200

デフォルトのタイムアウトは 30 秒、同期呼び出しは最長 55 秒です。大きなインストールはバックグラウンドタスクで実行しましょう（ステップ 6）。

5. ファイルを出し入れする

from eqvps import Sandbox

with Sandbox.create() as sb:
    sb.upload("/root/data.csv", "a,b\n1,2\n3,4\n")
    sb.run("""
import csv
rows = list(csv.DictReader(open('/root/data.csv')))
open('/root/sum.txt', 'w').write(str(sum(int(r['b']) for r in rows)))
""")
    print(sb.download_text("/root/sum.txt"))   # 6

パスは絶対パスで指定します。1 回の転送は 5 MB までです。download はバイト列を、download_text は文字列を返します。

6. 長いジョブをバックグラウンドで動かす

background=True を渡すと、待たずにすぐタスクが返ってきます。55 秒の上限はありません。

from eqvps import Sandbox

with Sandbox.create(tariff="standard") as sb:
    task = sb.exec("for i in 1 2 3 4 5; do echo step $i; sleep 20; done", background=True)
    result = task.wait(on_output=lambda out, err: print(out, end=""))
    print(result.state, result.exit_code)   # done 0

task.wait() は 2 秒ごとに状態を確認し、新しい出力が届くたびに表示します。task.logs() を自分で呼ぶことも、task.kill() で止めることもできます。タスクが動いている間は、操作がないことを理由にサンドボックスが削除されることはありません。

かかった費用

上の with ブロックはそれぞれ数秒しか存在せず、最低料金の 60 秒分で課金されました。small では 1 ブロックあたり 0.00055 ドルなので、5 つの例をすべて合わせても約 3 分の 1 セントです。全プランの料金、永続モード、支出上限はサンドボックスの制限と課金にあります。

うまくいかないとき

API のエラーは、捕捉できる例外です。

from eqvps import Sandbox, InsufficientBalanceError, RateLimitError

try:
    with Sandbox.create() as sb:
        print(sb.run("print(1)").stdout)
except InsufficientBalanceError:
    print("Top up the balance")
except RateLimitError as e:
    print("Too many at once, retry in", e.retry_after)

サーバーが待ち時間を返した場合、SDK は 429 と 503 の応答を最大 3 回まで自動で再試行します。11 種類のエラークラスはすべて SDK リファレンスに載っています。

次のステップ

同じ手順を JavaScript で：5 分で始めるサンドボックス用 TypeScript SDK
AI モデルにコードを書かせてここで実行する：サンドボックスで最初のエージェントタスク
プラン、お試しクレジット、サンドボックスの中身：サンドボックスのページ

5 分で始めるサンドボックス用 Python SDK：pip install eqvps から最初の実行まで