API-reference for sandboxes: SDK til Python og TypeScript

SDK'et er et tyndt lag oven på sandboxenes REST-API. Det sparer dig for tre ting: at bygge kald i hånden, at prøve dem igen, når platformen er travl, og at glemme at slette en sandbox, når koden kaster en exception. Alt her svarer til version 0.2.0 af begge pakker.

Har du aldrig oprettet en sandbox, giver forbindelsesguiden på 5 minutter dig først et token. Hvad en sandbox er, og hvad der er i den, står under Sandboxes.

Installér og konfigurér

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

Det samme program på begge sprog: opret en sandbox, kør kode, slet 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
});

Opret og find sandboxes

Sandbox.create(...) starter en sandbox, som regel på omkring et sekund. Python tager navngivne argumenter, TypeScript ét objekt med indstillinger.

Sandbox.connect(id) kobler sig på en eksisterende sandbox, typisk en vedvarende, du oprettede i går. Sandbox.list() returnerer alle kontoens sandboxes, kørende og satte på pause.

Egenskaber: id (sb_ + 24 hex-tegn), mode, tariff, state (running, starting, paused, pausing, resuming, deleting, deleted), env_keys / envKeys (kun navne, værdierne kommer aldrig tilbage) og info (det rå objekt). refresh() genindlæser dem.

kill() sletter sandboxen og stopper afregningen. At kalde den for en sandbox, der allerede er væk, er ikke en fejl.

Kør kode

run(code, language="python", timeout=30) sender kode via stdin til Python 3.12, Node.js 22 eller bash ("python", "node", "bash"). exec(command, cwd=None, stdin=None, timeout=30) kører en shell-kommando: en streng går gennem bash -lc, en liste køres som argv uden shell.

Begge returnerer et ExecResult:

Et synkront kald kører højst 55 sekunder. Begge metoder tager også env til netop det kald; det erstatter værdierne, der blev sat ved oprettelsen.

Lange job: baggrundsopgaver

Angiv background=True (TypeScript: { background: true }), og du får straks en Task. Den har ingen grænse på 55 sekunder og kan køre, til sandboxens levetid slutter. Op til 8 opgaver pr. 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) });

Hvis wait rammer sin egen timeout, kaster den SandboxTimeoutError, men opgaven kører videre. En kørende opgave forhindrer også, at en midlertidig sandbox slettes på grund af inaktivitet.

Filer og forbrug

upload(path, content, mode=None) skriver en fil til en absolut sti og returnerer dens størrelse. download(path) returnerer bytes, download_text(path) / downloadText(path) en streng. Én overførsel er begrænset til 5 MB.

usage() returnerer kørte sekunder, brugte CPU-sekunder, udgående bytes, timeprisen, billed_usd og estimated_total_usd. tariffs() er en almindelig funktion uden nøgle, der returnerer aktuelle priser og grænser. Afregningsreglerne står under Grænser og afregning for sandboxes.

Fejl

Hver API-fejl er en underklasse af EqvpsError med status (HTTP), code (stabil streng) og body. retry_after / retryAfter er sat, når serveren sender det.

To grænser giver de fleste 429: en konto kører 2 kommandoer ad gangen og har op til 20 sandboxes. SDK'et prøver igen, når serveren siger, hvor længe der skal ventes; efter tre forsøg får du exceptionen.

Når du ikke har brug for SDK'et

Ethvert sprog med en HTTP-klient kan kalde API'et direkte; endpoints står i OpenAPI-filen på https://eqvps.com/openapi.json. Agenter i Claude, Cursor eller andre MCP-klienter behøver slet ingen kode: MCP-serveren har de samme sandbox-værktøjer. Og vil du bare se det virke, viser sandbox-siden tarifferne og prøveperioden på $1 for nye konti.