مرجع API سندباکس: SDK برای Python و TypeScript

SDK لایه‌ای نازک روی REST API سندباکس‌هاست. شما را از سه دردسر خلاص می‌کند: ساختن دستی درخواست‌ها، فرستادن دوباره‌شان وقتی پلتفرم شلوغ است، و فراموش کردن حذف سندباکس وقتی کد استثنا می‌دهد. همهٔ مطالب این صفحه با نسخهٔ 0.2.0 هر دو بسته مطابقت دارد.

اگر تا حالا سندباکسی نساخته‌اید، اول با راهنمای اتصال ۵ دقیقه‌ای توکن بگیرید. اینکه سندباکس چیست و داخلش چه هست، در سندباکس‌ها آمده است.

نصب و پیکربندی

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(...) یک سندباکس را راه می‌اندازد، معمولاً در حدود یک ثانیه. Python آرگومان‌های نام‌دار می‌گیرد و TypeScript یک شیء گزینه‌ها.

متد Sandbox.connect(id) به سندباکسی موجود وصل می‌شود، معمولاً سندباکسی ماندگار که دیروز ساخته‌اید. Sandbox.list() همهٔ سندباکس‌های حساب را برمی‌گرداند، چه در حال اجرا و چه متوقف‌شده.

ویژگی‌ها: id (sb_ + ۲۴ نویسهٔ شانزده‌شانزدهی)، 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 برمی‌گردانند:

یک فراخوانی همگام حداکثر ۵۵ ثانیه طول می‌کشد. هر دو متد env را هم فقط برای همان فراخوانی می‌پذیرند که جای مقدارهای تعیین‌شده هنگام ساخت را می‌گیرد.

کارهای طولانی: کار پس‌زمینه

background=True (در TypeScript: { background: true }) را بدهید تا فوراً یک Task بگیرید. محدودیت ۵۵ ثانیه ندارد و می‌تواند تا پایان عمر سندباکس اجرا شود. حداکثر ۸ کار برای هر سندباکس.

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) رشته. هر انتقال حداکثر 5 MB است.

متد usage() ثانیه‌های اجرا، ثانیه‌های CPU مصرف‌شده، بایت‌های خروجی، قیمت ساعتی، billed_usd و estimated_total_usd را برمی‌گرداند. tariffs() تابعی ساده و بدون کلید است که قیمت‌ها و محدودیت‌های فعلی را برمی‌گرداند. قواعد صورتحساب در محدودیت‌ها و صورتحساب سندباکس آمده است.

خطاها

هر خطای API زیرکلاسی از EqvpsError است با status (HTTP)، code (رشتهٔ ثابت) و body. وقتی سرور بفرستد، retry_after / retryAfter پر می‌شود.

بیشتر خطاهای 429 از دو محدودیت می‌آیند: هر حساب همزمان ۲ دستور اجرا می‌کند و حداکثر ۲۰ سندباکس نگه می‌دارد. وقتی سرور زمان انتظار را بگوید SDK دوباره تلاش می‌کند و پس از سه بار، استثنا به شما می‌رسد.

چه وقت SDK لازم نیست

هر زبانی که کلاینت HTTP دارد می‌تواند مستقیم API را صدا بزند؛ نقطه‌های پایانی در فایل OpenAPI در https://eqvps.com/openapi.json آمده‌اند. ایجنت‌ها در Claude، Cursor یا دیگر کلاینت‌های MCP اصلاً به کد نیاز ندارند: سرور MCP همان ابزارهای سندباکس را دارد. و اگر فقط می‌خواهید کارکردش را ببینید، صفحهٔ سندباکس‌ها تعرفه‌ها و آزمایش $1 برای حساب‌های تازه را نشان می‌دهد.