Sandbox-API-referentie: SDK voor Python en TypeScript

De SDK is een dun laagje over de sandbox-REST-API. Hij bespaart je drie dingen: verzoeken met de hand opbouwen, ze opnieuw proberen als het platform druk is, en vergeten een sandbox te verwijderen als je code een exception gooit. Alles hier hoort bij versie 0.2.0 van beide pakketten.

Heb je nog nooit een sandbox aangemaakt, dan geeft de verbindingshandleiding van 5 minuten je eerst een token. Wat een sandbox is en wat erin zit, staat bij Sandboxes.

Installeren en instellen

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

Hetzelfde programma in beide talen: sandbox aanmaken, code draaien, verwijderen.

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

Sandboxes aanmaken en vinden

Sandbox.create(...) start een sandbox, meestal in ongeveer een seconde. Python neemt keyword-argumenten, TypeScript één object met opties.

Sandbox.connect(id) koppelt aan een bestaande sandbox, meestal een persistente die je gisteren hebt gemaakt. Sandbox.list() geeft alle sandboxes van het account terug, draaiend en gepauzeerd.

Eigenschappen: id (sb_ + 24 hex-tekens), mode, tariff, state (running, starting, paused, pausing, resuming, deleting, deleted), env_keys / envKeys (alleen namen, waarden komen nooit terug) en info (het ruwe object). refresh() laadt ze opnieuw.

kill() verwijdert de sandbox en stopt de facturering. Het aanroepen voor een sandbox die al weg is, is geen fout.

Code draaien

run(code, language="python", timeout=30) stuurt code via stdin naar Python 3.12, Node.js 22 of bash ("python", "node", "bash"). exec(command, cwd=None, stdin=None, timeout=30) voert een shell-commando uit: een string gaat via bash -lc, een lijst wordt als argv zonder shell uitgevoerd.

Beide geven een ExecResult terug:

Een synchrone aanroep duurt hooguit 55 seconden. Beide methodes nemen ook env voor alleen die aanroep; dat vervangt de waarden die bij het aanmaken zijn gezet.

Lange klussen: achtergrondtaken

Geef background=True mee (TypeScript: { background: true }) en je krijgt meteen een Task. Die heeft geen limiet van 55 seconden en kan draaien tot het einde van de levensduur van de sandbox. Tot 8 taken per 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) });

Loopt de eigen timeout van wait af, dan gooit hij SandboxTimeoutError, maar de taak draait door. Een lopende taak voorkomt ook dat een ephemeral sandbox wegens inactiviteit wordt verwijderd.

Bestanden en verbruik

upload(path, content, mode=None) schrijft een bestand naar een absoluut pad en geeft de grootte terug. download(path) geeft bytes terug, download_text(path) / downloadText(path) een string. Eén overdracht is beperkt tot 5 MB.

usage() geeft de looptijd in seconden, verbruikte CPU-seconden, uitgaande bytes, de uurprijs, billed_usd en estimated_total_usd. tariffs() is een gewone functie zonder sleutel die de huidige prijzen en limieten teruggeeft. De factureringsregels staan bij Sandbox-limieten en facturering.

Fouten

Elke API-fout is een subklasse van EqvpsError met status (HTTP), code (stabiele string) en body. retry_after / retryAfter is gevuld als de server die meestuurt.

Twee limieten veroorzaken de meeste 429's: een account voert 2 commando's tegelijk uit en houdt tot 20 sandboxes. De SDK probeert deze opnieuw als de server zegt hoe lang je moet wachten; na drie pogingen krijg je de exception.

Wanneer je de SDK niet nodig hebt

Elke taal met een HTTP-client kan de API direct aanroepen; de endpoints staan in het OpenAPI-bestand op https://eqvps.com/openapi.json. Agents in Claude, Cursor of andere MCP-clients hebben helemaal geen code nodig: de MCP-server heeft dezelfde sandboxtools. En wil je het gewoon zien werken, dan staan op de sandboxpagina de tarieven en de proef van $1 voor nieuwe accounts.