SDK تایپ‌اسکریپت برای سندباکس در ۵ دقیقه: از npm i @eqvps/sdk تا اولین اجرا

این راهنما یک سندباکس را از جاوااسکریپت یا تایپ‌اسکریپت اجرا می‌کند. یک microVM جداشدهٔ Firecracker بالا می‌آورید، با سه زبان کد اجرا می‌کنید، فایل جابه‌جا می‌کنید و خروجی یک کار طولانی را دنبال می‌کنید. هر گام یک تکه کد کوتاه است.

به Node.js 18+‎ (یا Deno یا Bun) و یک حساب EQVPS نیاز دارید.

۱. توکن بگیرید

SDK با یک توکن معمولی حساب احراز هویت می‌کند. صفحهٔ اتصال حساب نشان می‌دهد چطور آن را از داشبورد، API یا سرور MCP بگیرید.

export EQVPS_API_KEY="your-token"

حساب تازهٔ بدون موجودی وقتی اولین سندباکس را می‌سازد، ۱ دلار اعتبار سندباکس می‌گیرد. این مبلغ برای چندین بار اجرای این راهنما کافی است.

۲. SDK را نصب کنید

npm i @eqvps/sdk

مثال‌ها از ماژول‌های ES و await سطح بالا استفاده می‌کنند. آن‌ها را به شکل فایل .mjs ذخیره کنید، یا به شکل .ts و با npx tsx اجرا کنید.

۳. سندباکس را بالا بیاورید و کد اجرا کنید

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

خروجی شناسهٔ سندباکس (sb_ و ۲۴ نویسهٔ دیگر) است و بعد 0 3.12.x. Sandbox.with وقتی تابع پایان یابد سندباکس را حذف می‌کند، حتی اگر خطا پرتاب کند.

زبان پیش‌فرض Python است. دو زبان دیگر فقط یک گزینه فاصله دارند:

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

اسکریپتی که شکست بخورد چیزی پرتاب نمی‌کند. r.ok را بررسی کنید که وقتی exit_code صفر باشد و دستور به مهلتش نرسیده باشد، true است.

۴. دستورهای shell و بسته‌ها

exec یک رشتهٔ shell یا آرایهٔ argv می‌گیرد. سندباکس به اینترنت دسترسی دارد، پس نصب با npm و pip کار می‌کند:

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

یک فراخوانی هم‌زمان حداکثر ۵۵ ثانیه طول می‌کشد. هر چیز طولانی‌تر به یک کار پس‌زمینه می‌رود (گام ۶).

۵. فایل‌ها

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 یک رشته یا Uint8Array می‌پذیرد. download یک Uint8Array برمی‌گرداند و downloadText یک رشته. هر انتقال حداکثر 5 MB است.

۶. کارهای طولانی با خروجی زنده

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

کار فوراً برمی‌گردد و محدودیت ۵۵ ثانیه ندارد. wait به‌طور پیش‌فرض هر ۲ ثانیه وضعیت را می‌پرسد (pollIntervalMs آن را تغییر می‌دهد). task.kill() کار را متوقف می‌کند و sb.task(id) از یک فرایند دیگر دوباره به آن وصل می‌شود.

خطاها

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

وقتی سرور Retry-After بفرستد، SDK خودش 429 و 503 را تا سه بار دوباره امتحان می‌کند. رایج‌ترین 429 وقتی پیش می‌آید که بیش از دو دستور هم‌زمان روی یک حساب اجرا شود. همهٔ کلاس‌ها در مرجع SDK هستند.

هزینهٔ این راهنما

هر مثال چند ثانیه زنده بود و با حداقل ۶۰ ثانیه حساب شد: روی small مبلغ 0.00055 دلار و روی standard مبلغ 0.0011 دلار. کار گام ۶ حدود ۱۰۰ ثانیه روی standard اجرا شد، یعنی حدود 0.002 دلار. همه روی هم خیلی کمتر از یک سنت است. فهرست کامل قیمت‌ها در محدودیت‌ها و صورتحساب سندباکس آمده است.

گام‌های بعدی

• همین کار با پایتون: SDK پایتون برای سندباکس در ۵ دقیقه.
• یک مدل وصل کنید و بگذارید کد خودش را اجرا کند: اولین کار عامل در سندباکس.
• تعرفه‌ها و آزمایش ۱ دلاری: صفحهٔ سندباکس‌ها.