API-referens för sandlådor: SDK för Python och TypeScript

SDK:t är ett tunt lager ovanpå sandlådornas REST-API. Det besparar dig tre saker: att bygga anrop för hand, att försöka igen när plattformen är upptagen och att glömma ta bort en sandlåda när koden kastar ett undantag. Allt här motsvarar version 0.2.0 av båda paketen.

Har du aldrig skapat en sandlåda ger anslutningsguiden på 5 minuter dig först en token. Vad en sandlåda är och vad den innehåller står under Sandlådor.

Installera och konfigurera

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

Samma program på båda språken: skapa en sandlåda, kör kod, ta bort den.

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

Skapa och hitta sandlådor

Sandbox.create(...) startar en sandlåda, oftast på ungefär en sekund. Python tar namngivna argument, TypeScript ett objekt med alternativ.

Sandbox.connect(id) ansluter till en befintlig sandlåda, oftast en beständig som du skapade i går. Sandbox.list() returnerar alla sandlådor på kontot, körande och pausade.

Egenskaper: id (sb_ + 24 hexadecimala tecken), mode, tariff, state (running, starting, paused, pausing, resuming, deleting, deleted), env_keys / envKeys (bara namn, värdena kommer aldrig tillbaka) och info (det råa objektet). refresh() laddar om dem.

kill() tar bort sandlådan och stoppar debiteringen. Att anropa den för en sandlåda som redan är borta är inget fel.

Köra kod

run(code, language="python", timeout=30) skickar kod via stdin till Python 3.12, Node.js 22 eller bash ("python", "node", "bash"). exec(command, cwd=None, stdin=None, timeout=30) kör ett skalkommando: en sträng går via bash -lc, en lista körs som argv utan skal.

Båda returnerar ett ExecResult:

Ett synkront anrop får köra högst 55 sekunder. Båda metoderna tar också env för just det anropet; den ersätter värdena som sattes vid skapandet.

Långa jobb: bakgrundsuppgifter

Skicka background=True (TypeScript: { background: true }) så får du direkt en Task. Den har ingen gräns på 55 sekunder och kan köra tills sandlådans livstid tar slut. Upp till 8 uppgifter per sandlåda.

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

Om wait når sin egen timeout kastar den SandboxTimeoutError, men uppgiften fortsätter köra. En körande uppgift hindrar också att en tillfällig sandlåda tas bort på grund av inaktivitet.

Filer och förbrukning

upload(path, content, mode=None) skriver en fil till en absolut sökväg och returnerar dess storlek. download(path) returnerar bytes, download_text(path) / downloadText(path) en sträng. En överföring är begränsad till 5 MB.

usage() returnerar körda sekunder, använda CPU-sekunder, utgående bytes, timpriset, billed_usd och estimated_total_usd. tariffs() är en vanlig funktion utan nyckel som returnerar aktuella priser och gränser. Debiteringsreglerna finns under Sandlådors gränser och debitering.

Fel

Varje API-fel är en underklass till EqvpsError med status (HTTP), code (stabil sträng) och body. retry_after / retryAfter är satt när servern skickar det.

Två gränser orsakar de flesta 429: ett konto kör 2 kommandon samtidigt och har upp till 20 sandlådor. SDK:t försöker igen när servern säger hur länge man ska vänta; efter tre försök får du undantaget.

När du inte behöver SDK:t

Alla språk med en HTTP-klient kan anropa API:t direkt; ändpunkterna finns i OpenAPI-filen på https://eqvps.com/openapi.json. Agenter i Claude, Cursor eller andra MCP-klienter behöver ingen kod alls: MCP-servern har samma sandlådeverktyg. Och vill du bara se det fungera finns tarifferna och provperioden på $1 för nya konton på sandlådesidan.