Dokumentacja API sandboxów: SDK dla Python i TypeScript

SDK to cienka warstwa nad REST API sandboxów. Oszczędza trzech rzeczy: ręcznego składania żądań, ponawiania ich, gdy platforma jest zajęta, i zapominania o usunięciu sandboxa, gdy kod rzuci wyjątek. Wszystko poniżej odpowiada wersji 0.2.0 obu pakietów.

Jeśli nigdy nie tworzyłeś sandboxa, przewodnik po połączeniu w 5 minut najpierw da ci token. Czym jest sandbox i co ma w środku, wyjaśnia strona Sandboxy.

Instalacja i konfiguracja

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

Ten sam program w obu językach: utwórz sandbox, uruchom kod, usuń go.

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

Tworzenie i wyszukiwanie sandboxów

Sandbox.create(...) uruchamia sandbox, zwykle w około sekundę. Python przyjmuje argumenty nazwane, TypeScript jeden obiekt opcji.

Sandbox.connect(id) podłącza się do istniejącego sandboxa, zwykle trwałego, utworzonego wczoraj. Sandbox.list() zwraca wszystkie sandboxy konta, działające i wstrzymane.

Właściwości: id (sb_ + 24 znaki szesnastkowe), mode, tariff, state (running, starting, paused, pausing, resuming, deleting, deleted), env_keys / envKeys (same nazwy, wartości nigdy nie wracają) i info (surowy obiekt). refresh() je odświeża.

kill() usuwa sandbox i zatrzymuje naliczanie. Wywołanie dla już usuniętego sandboxa nie jest błędem.

Uruchamianie kodu

run(code, language="python", timeout=30) przekazuje kod przez stdin do Pythona 3.12, Node.js 22 albo bash ("python", "node", "bash"). exec(command, cwd=None, stdin=None, timeout=30) wykonuje polecenie powłoki: napis idzie przez bash -lc, lista jest wykonywana jako argv bez powłoki.

Obie zwracają ExecResult:

Wywołanie synchroniczne trwa najwyżej 55 sekund. Obie metody przyjmują też env na jedno wywołanie; nadpisuje ono wartości ustawione przy tworzeniu.

Długie zadania: tryb w tle

Przekaż background=True (w TypeScripcie { background: true }), a od razu dostaniesz Task. Nie ma limitu 55 sekund i może działać do końca życia sandboxa. Do 8 zadań na 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) });

Jeśli wait przekroczy własny limit czasu, rzuca SandboxTimeoutError, ale zadanie działa dalej. Działające zadanie nie pozwala też usunąć efemerycznego sandboxa z powodu bezczynności.

Pliki i zużycie

upload(path, content, mode=None) zapisuje plik pod ścieżką bezwzględną i zwraca jego rozmiar. download(path) zwraca bajty, download_text(path) / downloadText(path) napis. Jeden transfer to maksymalnie 5 MB.

usage() zwraca sekundy działania, zużyte sekundy CPU, bajty wychodzące, cenę za godzinę, billed_usd i estimated_total_usd. tariffs() to zwykła funkcja bez klucza, zwraca aktualne ceny i limity. Zasady naliczania opisuje strona Limity i rozliczenia sandboxów.

Błędy

Każdy błąd API to podklasa EqvpsError z polami status (HTTP), code (stały napis) i body. retry_after / retryAfter jest ustawione, gdy serwer je przyśle.

Większość 429 wywołują dwa limity: konto wykonuje 2 polecenia jednocześnie i trzyma do 20 sandboxów. SDK ponawia takie żądania, gdy serwer poda, ile czekać; po trzech próbach dostaniesz wyjątek.

Kiedy SDK jest zbędne

Każdy język z klientem HTTP może wywoływać API bezpośrednio; endpointy są opisane w pliku OpenAPI pod adresem https://eqvps.com/openapi.json. Agenci w Claude, Cursor i innych klientach MCP nie potrzebują żadnego kodu: serwer MCP ma te same narzędzia sandboxów. A jeśli chcesz tylko zobaczyć, jak to działa, na stronie sandboxów są taryfy i próbny $1 dla nowych kont.