Riferimento dell'API sandbox: SDK Python e TypeScript

L'SDK è un sottile strato sopra l'API REST delle sandbox. Ti risparmia tre cose: costruire le richieste a mano, ripeterle quando la piattaforma è occupata e dimenticarti di eliminare una sandbox quando il codice solleva un'eccezione. Tutto ciò che segue corrisponde alla versione 0.2.0 di entrambi i pacchetti.

Se non hai mai creato una sandbox, la guida alla connessione in 5 minuti ti dà prima un token. Che cos'è una sandbox e cosa contiene è spiegato in Sandbox.

Installare e configurare

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

Lo stesso programma nei due linguaggi: crea una sandbox, esegui codice, eliminala.

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

Creare e trovare sandbox

Sandbox.create(...) avvia una sandbox, di solito in circa un secondo. Python accetta argomenti con nome, TypeScript un oggetto di opzioni.

Sandbox.connect(id) si collega a una sandbox esistente, di solito una persistente creata ieri. Sandbox.list() restituisce tutte le sandbox dell'account, attive e in pausa.

Proprietà: id (sb_ + 24 caratteri esadecimali), mode, tariff, state (running, starting, paused, pausing, resuming, deleting, deleted), env_keys / envKeys (solo i nomi, i valori non tornano mai) e info (l'oggetto grezzo). refresh() li ricarica.

kill() elimina la sandbox e ferma la fatturazione. Chiamarlo su una sandbox già eliminata non è un errore.

Eseguire codice

run(code, language="python", timeout=30) invia il codice su stdin a Python 3.12, Node.js 22 o bash ("python", "node", "bash"). exec(command, cwd=None, stdin=None, timeout=30) esegue un comando di shell: una stringa passa per bash -lc, una lista viene eseguita come argv senza shell.

Entrambi restituiscono un ExecResult:

Una chiamata sincrona dura al massimo 55 secondi. Entrambi i metodi accettano anche env per quella sola chiamata; sostituisce i valori impostati alla creazione.

Lavori lunghi: task in background

Passa background=True (TypeScript: { background: true }) e ricevi subito un Task. Non ha il limite di 55 secondi e può durare fino alla fine della vita della sandbox. Fino a 8 task 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) });

Se wait raggiunge il proprio timeout solleva SandboxTimeoutError, ma il task continua. Un task in corso impedisce anche che una sandbox effimera venga eliminata per inattività.

File e consumi

upload(path, content, mode=None) scrive un file in un percorso assoluto e ne restituisce la dimensione. download(path) restituisce byte, download_text(path) / downloadText(path) una stringa. Un trasferimento è limitato a 5 MB.

usage() restituisce i secondi di esecuzione, i secondi di CPU usati, i byte in uscita, il prezzo orario, billed_usd ed estimated_total_usd. tariffs() è una semplice funzione senza chiave che restituisce prezzi e limiti attuali. Le regole di fatturazione sono in Limiti e fatturazione delle sandbox.

Errori

Ogni errore dell'API è una sottoclasse di EqvpsError con status (HTTP), code (stringa stabile) e body. retry_after / retryAfter è valorizzato quando il server lo invia.

Due limiti causano la maggior parte dei 429: un account esegue 2 comandi alla volta e tiene fino a 20 sandbox. L'SDK ripete queste richieste quando il server dice quanto aspettare; dopo tre tentativi ricevi l'eccezione.

Quando fare a meno dell'SDK

Qualsiasi linguaggio con un client HTTP può chiamare l'API direttamente; gli endpoint sono nel file OpenAPI su https://eqvps.com/openapi.json. Gli agenti in Claude, Cursor o altri client MCP non hanno bisogno di codice: il server MCP ha gli stessi strumenti per le sandbox. E se vuoi solo vederlo in azione, la pagina delle sandbox mostra le tariffe e la prova da $1 per i nuovi account.