Referința API-ului de sandboxuri: SDK pentru Python și TypeScript

SDK-ul e un strat subțire peste REST API-ul sandboxurilor. Te scutește de trei lucruri: construirea manuală a cererilor, reîncercarea când platforma e ocupată și uitarea ștergerii unui sandbox când codul tău aruncă o excepție. Tot ce e aici corespunde versiunii 0.2.0 a ambelor pachete.

Dacă n-ai creat niciodată un sandbox, ghidul de conectare în 5 minute îți dă întâi un token. Ce e un sandbox și ce conține e acoperit în Sandboxuri.

Instalare și configurare

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

Același program în ambele limbaje: creează un sandbox, rulează cod, șterge-l.

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

Crearea și găsirea sandboxurilor

Sandbox.create(...) pornește un sandbox, de obicei în aproximativ o secundă. Python primește argumente cu nume, TypeScript un singur obiect de opțiuni.

Sandbox.connect(id) se atașează la un sandbox existent, de obicei unul persistent creat ieri. Sandbox.list() returnează toate sandboxurile contului, care rulează și puse pe pauză.

Proprietăți: id (sb_ + 24 de caractere hex), mode, tariff, state (running, starting, paused, pausing, resuming, deleting, deleted), env_keys / envKeys (doar numele, valorile nu se întorc niciodată) și info (obiectul brut). refresh() le reîncarcă.

kill() șterge sandboxul și oprește facturarea. Apelarea lui pe un sandbox care nu mai există nu e o eroare.

Rularea codului

run(code, language="python", timeout=30) trimite codul pe stdin către Python 3.12, Node.js 22 sau bash ("python", "node", "bash"). exec(command, cwd=None, stdin=None, timeout=30) rulează o comandă de shell: un șir trece prin bash -lc, o listă e executată ca argv, fără shell.

Amândouă returnează un ExecResult:

Un apel sincron poate rula cel mult 55 de secunde. Ambele metode primesc și env pentru acel apel; suprascrie valorile setate la create.

Sarcinile lungi: sarcini de fundal

Trimite background=True (TypeScript: { background: true }) și primești imediat un Task. Nu are limita de 55 de secunde și poate rula până se încheie durata de viață a sandboxului. Până la 8 sarcini pe sandbox.

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

Dacă wait își atinge propriul timeout, aruncă SandboxTimeoutError, dar sarcina rulează mai departe. O sarcină care rulează împiedică și ștergerea unui sandbox efemer pentru inactivitate.

Fișiere și consum

upload(path, content, mode=None) scrie un fișier la o cale absolută și îi returnează mărimea. download(path) returnează octeți, download_text(path) / downloadText(path) un șir. Un transfer e limitat la 5 MB.

usage() returnează secundele de rulare, secundele de CPU folosite, octeții trimiși spre exterior, prețul pe oră, billed_usd și estimated_total_usd. tariffs() e o funcție simplă care nu are nevoie de cheie și returnează prețurile și limitele curente. Regulile de facturare sunt în Limitele și facturarea sandboxurilor.

Erori

Fiecare eroare API e o subclasă a EqvpsError, cu status (HTTP), code (șir stabil) și body. retry_after / retryAfter e setat când serverul îl trimite.

Două limite cauzează cele mai multe 429: un cont rulează 2 comenzi în același timp și ține până la 20 de sandboxuri. SDK-ul le reîncearcă atunci când serverul spune cât să aștepte; după trei încercări primești excepția.

Când te poți lipsi de SDK

Orice limbaj cu un client HTTP poate apela direct API-ul; endpointurile sunt în fișierul OpenAPI de la https://eqvps.com/openapi.json. Agenții din Claude, Cursor sau alți clienți MCP nu au nevoie deloc de cod: serverul MCP are aceleași unelte pentru sandboxuri. Iar dacă vrei doar să-l vezi funcționând, pagina sandboxurilor listează tarifele și proba de $1 pentru conturile noi.