স্যান্ডবক্স API রেফারেন্স: Python ও TypeScript SDK

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 ডাকতে পারে; এন্ডপয়েন্টগুলো https://eqvps.com/openapi.json-এর OpenAPI ফাইলে আছে। Claude, Cursor বা অন্য MCP ক্লায়েন্টের এজেন্টের কোডই লাগে না: MCP সার্ভার-এ একই স্যান্ডবক্স টুল আছে। আর শুধু চলতে দেখতে চাইলে স্যান্ডবক্স পাতা-য় ট্যারিফ আর নতুন অ্যাকাউন্টের $1 ট্রায়াল আছে।