Referensi API sandbox: SDK Python dan TypeScript

SDK adalah lapisan tipis di atas REST API sandbox. Ia menghemat tiga hal: menyusun permintaan secara manual, mengulanginya saat platform sibuk, dan lupa menghapus sandbox ketika kode melempar exception. Semua di sini sesuai dengan versi 0.2.0 kedua paket.

Kalau belum pernah membuat sandbox, panduan koneksi 5 menit memberi Anda token lebih dulu. Apa itu sandbox dan isinya dijelaskan di Sandbox.

Instal dan konfigurasi

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

Program yang sama dalam dua bahasa: buat sandbox, jalankan kode, hapus.

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
});

Membuat dan menemukan sandbox

Sandbox.create(...) menyalakan sandbox, biasanya dalam sekitar satu detik. Python menerima argumen bernama, TypeScript satu objek opsi.

Sandbox.connect(id) menyambung ke sandbox yang sudah ada, biasanya sandbox persistent yang Anda buat kemarin. Sandbox.list() mengembalikan semua sandbox di akun, yang berjalan maupun dijeda.

Properti: id (sb_ + 24 karakter hex), mode, tariff, state (running, starting, paused, pausing, resuming, deleting, deleted), env_keys / envKeys (hanya nama, nilainya tidak pernah dikembalikan), dan info (objek mentah). refresh() memuat ulang semuanya.

kill() menghapus sandbox dan menghentikan penagihan. Memanggilnya untuk sandbox yang sudah tidak ada bukan error.

Menjalankan kode

run(code, language="python", timeout=30) mengirim kode lewat stdin ke Python 3.12, Node.js 22, atau bash ("python", "node", "bash"). exec(command, cwd=None, stdin=None, timeout=30) menjalankan perintah shell: string lewat bash -lc, list dijalankan sebagai argv tanpa shell.

Keduanya mengembalikan ExecResult:

Panggilan sinkron berjalan paling lama 55 detik. Kedua metode juga menerima env untuk panggilan itu saja; nilainya menggantikan yang diatur saat pembuatan.

Pekerjaan panjang: tugas latar belakang

Berikan background=True (TypeScript: { background: true }) dan Anda langsung mendapat Task. Tidak ada batas 55 detik, dan tugas bisa berjalan sampai masa hidup sandbox habis. Hingga 8 tugas per sandbox.

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) });

Jika wait mencapai batas waktunya sendiri, ia melempar SandboxTimeoutError, tetapi tugas tetap berjalan. Tugas yang sedang berjalan juga mencegah sandbox ephemeral dihapus karena tidak aktif.

File dan pemakaian

upload(path, content, mode=None) menulis file ke path absolut dan mengembalikan ukurannya. download(path) mengembalikan byte, download_text(path) / downloadText(path) mengembalikan string. Satu transfer dibatasi 5 MB.

usage() mengembalikan detik berjalan, detik CPU terpakai, byte keluar, harga per jam, billed_usd, dan estimated_total_usd. tariffs() adalah fungsi biasa tanpa kunci yang mengembalikan harga dan batas terkini. Aturan penagihan ada di Batas dan penagihan sandbox.

Error

Setiap error API adalah subkelas EqvpsError dengan status (HTTP), code (string tetap), dan body. retry_after / retryAfter terisi bila server mengirimkannya.

Dua batas penyebab sebagian besar 429: satu akun menjalankan 2 perintah sekaligus dan menyimpan hingga 20 sandbox. SDK mengulangnya bila server memberi tahu berapa lama harus menunggu; setelah tiga kali, Anda menerima exception.

Kapan tidak perlu SDK

Bahasa apa pun dengan klien HTTP bisa memanggil API langsung; endpoint ada di file OpenAPI di https://eqvps.com/openapi.json. Agen di Claude, Cursor, atau klien MCP lain sama sekali tidak butuh kode: server MCP punya alat sandbox yang sama. Dan kalau Anda hanya ingin melihatnya bekerja, halaman sandbox menampilkan tarif dan uji coba $1 untuk akun baru.