Sandbox API-ის ცნობარი: Python და TypeScript SDK

SDK არის sandbox-ის REST API-ის თხელი გარსი. ის სამ რამეს გაგირიდებთ: მოთხოვნების ხელით აწყობას, გამეორებას, როცა პლატფორმა დატვირთულია, და sandbox-ის წაშლის დავიწყებას, როცა კოდი გამონაკლისს აგდებს. აქ ყველაფერი ორივე პაკეტის 0.2.0 ვერსიას შეესაბამება.

თუ sandbox ჯერ არასოდეს შეგიქმნიათ, 5-წუთიანი დაკავშირების გზამკვლევი ჯერ ტოკენს მოგცემთ. რა არის sandbox და რა არის მის შიგნით, აღწერილია სენდბოქსებში.

ინსტალაცია და კონფიგურაცია

pip install eqvps          # Python 3.8+
npm i @eqvps/sdk           # Node.js 18+, Deno, Bun
export EQVPS_API_KEY=...   # your EQVPS account token

ერთი და იგივე პროგრამა ორივე ენაზე: შექმენით sandbox, გაუშვით კოდი, წაშალეთ.

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-ების შექმნა და მოძებნა

Sandbox.create(...) უშვებს sandbox-ს, ჩვეულებრივ დაახლოებით ერთ წამში. Python სახელდებულ არგუმენტებს იღებს, TypeScript — პარამეტრების ერთ ობიექტს.

Sandbox.connect(id) უკავშირდება არსებულ sandbox-ს, როგორც წესი მუდმივს, რომელიც გუშინ შექმენით. Sandbox.list() აბრუნებს ანგარიშის ყველა sandbox-ს, გაშვებულსაც და დაპაუზებულსაც.

თვისებები: id (sb_ + 24 თექვსმეტობითი სიმბოლო), mode, tariff, state (running, starting, paused, pausing, resuming, deleting, deleted), env_keys / envKeys (მხოლოდ სახელები, მნიშვნელობები არასოდეს ბრუნდება) და info (ნედლი ობიექტი). refresh() მათ ხელახლა ტვირთავს.

kill() შლის sandbox-ს და აჩერებს ბილინგს. უკვე წაშლილ sandbox-ზე მისი გამოძახება შეცდომა არ არის.

კოდის გაშვება

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) უშვებს shell-ის ბრძანებას: სტრიქონი გადის bash -lc-ში, სია სრულდება როგორც argv, shell-ის გარეშე.

ორივე აბრუნებს ExecResult-ს:

სინქრონული გამოძახება მაქსიმუმ 55 წამს მუშაობს. ორივე მეთოდი იღებს env-საც მხოლოდ ამ ერთი გამოძახებისთვის; ის ცვლის შექმნისას მითითებულ მნიშვნელობებს.

გრძელი სამუშაოები: ფონური ამოცანები

გადაეცით background=True (TypeScript-ში { background: true }) და მაშინვე მიიღებთ Task-ს. მას 55-წამიანი ლიმიტი არ აქვს და შეუძლია იმუშაოს sandbox-ის სიცოცხლის დასრულებამდე. თითო sandbox-ზე 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) });

თუ wait საკუთარ ტაიმაუტს მიაღწევს, ის აგდებს SandboxTimeoutError-ს, მაგრამ ამოცანა აგრძელებს მუშაობას. გაშვებული ამოცანა დროებით sandbox-საც იცავს უმოქმედობის გამო წაშლისგან.

ფაილები და ხარჯი

upload(path, content, mode=None) წერს ფაილს აბსოლუტურ გზაზე და აბრუნებს მის ზომას. download(path) აბრუნებს ბაიტებს, download_text(path) / downloadText(path) — სტრიქონს. ერთი გადაცემა 5 MB-ით შემოიფარგლება.

usage() აბრუნებს მუშაობის წამებს, გამოყენებულ CPU წამებს, გამავალ ბაიტებს, საათობრივ ფასს, billed_usd-ს და estimated_total_usd-ს. tariffs() ჩვეულებრივი ფუნქციაა, რომელსაც გასაღები არ სჭირდება და აბრუნებს მიმდინარე ფასებსა და ლიმიტებს. ბილინგის წესები აღწერილია sandbox-ის ლიმიტებსა და ბილინგში.

შეცდომები

API-ის ყველა შეცდომა EqvpsError-ის ქვეკლასია status-ით (HTTP), code-ით (სტაბილური სტრიქონი) და body-ით. retry_after / retryAfter ივსება, როცა სერვერი მას აგზავნის.

429-ების უმეტესობას ორი ლიმიტი იწვევს: ანგარიში ერთდროულად 2 ბრძანებას უშვებს და 20 sandbox-მდე ინახავს. SDK მათ იმეორებს, როცა სერვერი ამბობს, რამდენ ხანს უნდა დაიცადოს; სამი ცდის შემდეგ გამონაკლისს მიიღებთ.

როდის არ გჭირდებათ SDK

ნებისმიერ ენას, რომელსაც HTTP კლიენტი აქვს, შეუძლია API პირდაპირ გამოიძახოს; endpoint-ები OpenAPI ფაილშია მისამართზე https://eqvps.com/openapi.json. Claude-ში, Cursor-ში ან სხვა MCP კლიენტებში აგენტებს კოდი საერთოდ არ სჭირდებათ: MCP სერვერს იგივე sandbox ხელსაწყოები აქვს. თუ უბრალოდ გინდათ ნახოთ, როგორ მუშაობს, sandbox-ის გვერდზე არის ტარიფები და $1-იანი საცდელი კრედიტი ახალი ანგარიშებისთვის.