SDK کون سے Python اور Node.js ورژن سپورٹ کرتا ہے؟

Python پیکیج کو Python 3.8 یا نیا چاہیے اور اس کی کوئی ڈیپنڈنسی نہیں۔ TypeScript پیکیج کی بھی کوئی ڈیپنڈنسی نہیں؛ یہ Node.js 18+، Deno، Bun اور fetch والے براؤزرز میں چلتا ہے۔

SDK میری API کی کہاں سے لیتا ہے؟

api_key / apiKey آرگیومنٹ سے یا EQVPS_API_KEY انوائرنمنٹ ویری ایبل سے۔ کی ایک عام EQVPS اکاؤنٹ کا ٹوکن ہے۔ EQVPS_API_URL API کا پتہ بدلتا ہے؛ اس کی ضرورت صرف ٹیسٹنگ میں ہوتی ہے۔

کیا SDK ناکام ریکویسٹ دوبارہ بھیجتا ہے؟

جب سرور Retry-After بھیجے تو 429 اور 503 کو زیادہ سے زیادہ 3 بار دوبارہ بھیجتا ہے، ہر بار زیادہ سے زیادہ 30 سیکنڈ انتظار کرتا ہے۔ ان اسٹیٹس کا مطلب ہے کہ کچھ چلنے سے پہلے ہی ریکویسٹ رد ہو گئی، اس لیے run اور exec کو دہرانا محفوظ ہے۔ نیٹ ورک ایرر صرف GET کے لیے دہرائے جاتے ہیں؛ run، exec اور upload کبھی دو بار نہیں بھیجے جاتے۔

کیا صفر کے علاوہ ایگزٹ کوڈ ایکسیپشن ہے؟

نہیں۔ run اور exec ایسا نتیجہ لوٹاتے ہیں جس میں exit_code، stdout اور stderr ہوتے ہیں۔ result.ok یا result.exit_code دیکھیں۔ ایکسیپشن صرف API ایرر پر آتے ہیں، جیسے خالی بیلنس یا غلط ٹوکن۔

اگر کوڈ کریش ہو جائے تو سینڈباکس ضرور حذف ہو، یہ کیسے یقینی بناؤں؟

اسکوپ والی شکل استعمال کریں: Python میں with Sandbox.create() as sb، TypeScript میں Sandbox.with(options, fn) یا await using۔ بلاک ختم ہوتے ہی سینڈباکس حذف ہو جاتا ہے، ایکسیپشن کے بعد بھی۔

سینڈباکس API حوالہ: تمام میتھڈز اور 11 errors

EQVPS سینڈباکس SDK کے تمام میتھڈ ایک صفحے پر: پیرامیٹر، ڈیفالٹ قدریں، واپس آنے والی قدریں اور تمام 11 ایرر کلاسز، Python اور TypeScript میں ایک ہی مثال کے ساتھ۔

SDK سینڈباکس REST API کے اوپر ایک پتلی تہہ ہے۔ یہ آپ کو تین جھنجھٹوں سے بچاتا ہے: ریکویسٹ ہاتھ سے بنانا، پلیٹ فارم مصروف ہو تو دوبارہ بھیجنا، اور کوڈ کے ایکسیپشن پھینکنے پر سینڈباکس حذف کرنا بھول جانا۔ یہاں کی ہر بات دونوں پیکیجز کے ورژن 0.2.0 سے مطابقت رکھتی ہے۔

اگر آپ نے کبھی سینڈباکس نہیں بنایا تو پہلے 5 منٹ کی کنکشن گائیڈ سے ٹوکن لیں۔ سینڈباکس کیا ہے اور اس کے اندر کیا ہے، یہ سینڈباکس میں بتایا گیا ہے۔

انسٹال اور کنفیگر

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 ایک آپشن آبجیکٹ۔

Python	TypeScript	ڈیفالٹ	مطلب
`mode`	`mode`	`"ephemeral"`	`"ephemeral"` (فی سیکنڈ) یا `"persistent"` (ہر شروع ہوئے گھنٹے کے حساب سے، ڈسک رکھتا ہے)
`tariff`	`tariff`	`"small"`	`micro`، `small`، `standard`، `plus`، `pro`، `max`
`idle_timeout`	`idleTimeout`	300	عارضی سینڈباکس حذف ہونے سے پہلے بغیر سرگرمی کے سیکنڈ، زیادہ سے زیادہ 3600
`ttl`	`ttl`	—	سیکنڈ میں زیادہ سے زیادہ عمر: عارضی کے لیے 86400 تک، مستقل کے لیے 2592000 تک
`env`	`env`	—	ہر کمانڈ کے لیے انوائرنمنٹ ویری ایبل، انکرپٹ کر کے رکھے جاتے ہیں
`api_key`، `base_url`	`apiKey`، `baseUrl`	انوائرنمنٹ ویری ایبل	`EQVPS_API_KEY` / `EQVPS_API_URL` کی جگہ لیتے ہیں
`timeout`	`timeoutMs`	70 سیکنڈ	ہر ریکویسٹ کا HTTP ٹائم آؤٹ
`max_retries`	`maxRetries`	3	429/503 پر دوبارہ کوششیں

میتھڈ Sandbox.connect(id) کسی موجودہ سینڈباکس سے جڑتا ہے، عام طور پر کل بنائے گئے کسی مستقل سینڈباکس سے۔ Sandbox.list() اکاؤنٹ کے تمام سینڈباکس لوٹاتا ہے، چلتے ہوئے بھی اور رکے ہوئے بھی۔

پراپرٹیز: id (sb_ + 24 ہیکس حروف)، 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 لوٹاتے ہیں:

فیلڈ	مطلب
`exit_code`	پروسیس کا ایگزٹ کوڈ
`stdout`، `stderr`	آؤٹ پٹ، ہر اسٹریم میں 1 MiB تک
`timed_out`	کمانڈ اپنے ٹائم آؤٹ تک پہنچ گئی
`truncated`	آؤٹ پٹ کاٹا گیا
`duration_ms`	کتنی دیر چلا
`ok`	`exit_code == 0` اور کوئی ٹائم آؤٹ نہیں

ایک سنکرونس کال زیادہ سے زیادہ 55 سیکنڈ چلتی ہے۔ دونوں میتھڈ صرف اس کال کے لیے env بھی لیتے ہیں؛ یہ بناتے وقت دی گئی قدروں کی جگہ لیتا ہے۔

لمبے کام: بیک گراؤنڈ ٹاسک

background=True (TypeScript میں { background: true }) دیں اور آپ کو فوراً ایک Task ملتا ہے۔ اس پر 55 سیکنڈ کی حد نہیں اور یہ سینڈباکس کی عمر ختم ہونے تک چل سکتا ہے۔ ہر سینڈباکس میں 8 ٹاسک تک۔

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

میتھڈ	کیا کرتا ہے
`task.logs()`	پچھلی کال کے بعد کا نیا stdout اور stderr
`task.status()`	آؤٹ پٹ پڑھے بغیر حالت: `running`، `done`، `failed`، `killed`، `timeout`
`task.wait(timeout, poll_interval=2, on_output)`	ٹاسک ختم ہونے تک جانچتا ہے، `TaskResult` لوٹاتا ہے
`task.kill()`	ٹاسک اور اس کے پروسیس روکتا ہے
`sb.task(id)` / `sb.tasks()`	کسی ٹاسک سے دوبارہ جڑنا / ٹاسک کی فہرست

اگر 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 بھرا ہوتا ہے۔

کلاس	HTTP	عام `code`	کیا کریں
`AuthenticationError`	401	`unauthenticated`	ٹوکن چیک کریں
`InsufficientBalanceError`	402	`insufficient_balance`	بیلنس ٹاپ اپ کریں
`NotFoundError`	404	`not_found`	غلط id، یا فائل موجود نہیں
`SandboxPausedError`	409	`sandbox_paused`	بیلنس ختم ہونے سے رکا ہے؛ ٹاپ اپ کے بعد پھر چلے گا
`SandboxDeletedError`	410	`sandbox_deleted`	ہمیشہ کے لیے حذف ہو چکا
`FileTooLargeError`	413	`file_too_large`	ٹرانسفر 5 MB سے کم رکھیں
`ValidationError`	422	`invalid_request`	پیرامیٹر درست کریں
`RateLimitError`	429	`too_many_concurrent`، `too_many_tasks`، `rate_limited`	انتظار کر کے دوبارہ کوشش کریں
`BudgetExceededError`	429	`budget_exceeded`	سینڈباکس کی روزانہ یا ماہانہ خرچ کی حد پوری ہو گئی
`CapacityError`	503	`capacity`	تھوڑی دیر بعد کوشش کریں یا چھوٹا ٹیرف لیں
`SandboxTimeoutError`	—	`request_timeout`، `wait_timeout`	کمانڈ کا نہیں، HTTP ریکویسٹ (یا `wait`) کا وقت ختم ہوا

زیادہ تر 429 دو حدوں سے آتے ہیں: ایک اکاؤنٹ ایک وقت میں 2 کمانڈ چلاتا ہے اور 20 تک سینڈباکس رکھ سکتا ہے۔ سرور بتائے کہ کتنا رکنا ہے تو SDK دوبارہ کوشش کرتا ہے؛ تین کوششوں کے بعد آپ کو ایکسیپشن ملتا ہے۔

کب SDK کی ضرورت نہیں

HTTP کلائنٹ والی کوئی بھی زبان براہِ راست API بلا سکتی ہے؛ اینڈپوائنٹ https://eqvps.com/openapi.json پر OpenAPI فائل میں ہیں۔ Claude، Cursor یا دوسرے MCP کلائنٹس میں چلنے والے ایجنٹس کو کوڈ کی ضرورت ہی نہیں: MCP سرور میں وہی سینڈباکس ٹولز ہیں۔ اور اگر صرف اسے چلتا دیکھنا ہے تو سینڈباکس کے صفحے پر ٹیرف اور نئے اکاؤنٹس کے لیے $1 کا ٹرائل ہے۔

سینڈباکس API حوالہ: Python اور TypeScript SDK