SDK TypeScript untuk sandbox dalam 5 menit: dari npm i @eqvps/sdk sampai run pertama

Panduan ini menjalankan sandbox dari JavaScript atau TypeScript. Anda akan menyalakan microVM Firecracker yang terisolasi, menjalankan kode dalam tiga bahasa, memindahkan file, dan memantau output pekerjaan panjang. Setiap langkah hanya potongan kode pendek.

Anda butuh Node.js 18+ (atau Deno, atau Bun) dan akun EQVPS.

1. Dapatkan token

SDK melakukan autentikasi dengan token akun biasa. Halaman menghubungkan akun menunjukkan cara mendapatkannya dari dasbor, API, atau server MCP.

export EQVPS_API_KEY="your-token"

Akun baru tanpa saldo mendapat kredit sandbox $1 saat pertama kali membuat sandbox. Itu cukup untuk panduan ini berkali-kali.

2. Pasang SDK

npm i @eqvps/sdk

Contoh-contoh ini memakai modul ES dan await tingkat atas. Simpan sebagai file .mjs, atau sebagai .ts lalu jalankan dengan npx tsx.

3. Jalankan sandbox dan eksekusi kode

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

await Sandbox.with({ tariff: "small" }, async (sb) => {
  console.log(sb.id);
  const r = await sb.run("import platform; print(platform.python_version())");
  console.log(r.exit_code, r.stdout);
});

Outputnya adalah id sandbox (sb_ dan 24 karakter lagi), lalu 0 3.12.x. Sandbox.with menghapus sandbox saat callback selesai, termasuk jika callback melempar error.

Bahasa bawaan adalah Python. Dua lainnya cukup satu opsi:

await Sandbox.with({}, async (sb) => {
  const js = await sb.run("console.log(process.version)", { language: "node" });
  const sh = await sb.run("uname -r && nproc", { language: "bash" });
  console.log(js.stdout, sh.stdout);
});

Skrip yang gagal tidak melempar apa pun. Periksa r.ok, yang bernilai true jika exit_code sama dengan 0 dan perintah tidak kena batas waktu.

4. Perintah shell dan paket

exec menerima string shell atau array argv. Sandbox punya akses internet, jadi instalasi lewat npm dan pip berfungsi:

await Sandbox.with({ tariff: "small" }, async (sb) => {
  await sb.exec("mkdir -p /root/app && cd /root/app && npm init -y && npm i lodash", { timeout: 55 });
  const r = await sb.exec(["node", "-e", "console.log(require('/root/app/node_modules/lodash').VERSION)"]);
  console.log(r.stdout);
});

Panggilan sinkron paling lama 55 detik. Apa pun yang lebih lama masuk ke tugas latar belakang (langkah 6).

5. File

await Sandbox.with({}, async (sb) => {
  await sb.upload("/root/input.json", JSON.stringify({ values: [3, 5, 8] }));
  await sb.run("import json; d = json.load(open('/root/input.json')); open('/root/out.txt', 'w').write(str(sum(d['values'])))");
  console.log(await sb.downloadText("/root/out.txt"));   // 16
});

upload menerima string atau Uint8Array. download mengembalikan Uint8Array, downloadText mengembalikan string. Satu transfer dibatasi 5 MB.

6. Pekerjaan panjang dengan output langsung

await Sandbox.with({ tariff: "standard" }, async (sb) => {
  const task = await sb.exec("for i in 1 2 3 4 5; do echo step $i; sleep 20; done", { background: true });
  const res = await task.wait({ onOutput: (out) => process.stdout.write(out) });
  console.log(res.state, res.exit_code);   // done 0
});

Tugas langsung kembali dan tidak punya batas 55 detik. Secara bawaan wait memeriksa setiap 2 detik (pollIntervalMs mengubahnya). task.kill() menghentikannya; sb.task(id) menyambung lagi dari proses lain.

Error

import { Sandbox, InsufficientBalanceError, RateLimitError } from "@eqvps/sdk";

try {
  await Sandbox.with({}, async (sb) => console.log((await sb.run("print(1)")).stdout));
} catch (e) {
  if (e instanceof InsufficientBalanceError) console.log("Top up the balance");
  else if (e instanceof RateLimitError) console.log("Busy, retry in", e.retryAfter);
  else throw e;
}

SDK sendiri mengulang 429 dan 503 hingga tiga kali saat server mengirim Retry-After. 429 yang paling sering muncul karena menjalankan lebih dari dua perintah sekaligus di satu akun. Semua kelas ada di referensi SDK.

Biaya panduan ini

Setiap contoh hidup beberapa detik dan ditagih minimum 60 detik: $0.00055 di small, $0.0011 di standard. Pekerjaan di langkah 6 berjalan sekitar 100 detik di standard, kira-kira $0.002. Semuanya jauh di bawah satu sen. Daftar harga lengkap ada di batas dan penagihan sandbox.

Langkah berikutnya

• Hal yang sama di Python: SDK Python untuk sandbox dalam 5 menit.
• Sambungkan model dan biarkan ia menjalankan kodenya sendiri: tugas agen pertama Anda di sandbox.
• Tarif dan uji coba $1: halaman sandbox.