Référence de l'API sandbox : SDK Python et TypeScript

Le SDK est une fine couche au-dessus de l'API REST des sandboxes. Il vous épargne trois choses : construire les requêtes à la main, les relancer quand la plateforme est occupée et oublier de supprimer une sandbox quand votre code lève une exception. Tout ce qui suit correspond à la version 0.2.0 des deux paquets.

Si vous n'avez jamais créé de sandbox, le guide de connexion en 5 minutes vous donne d'abord un jeton. Ce qu'est une sandbox et ce qu'elle contient est expliqué dans Sandboxes.

Installer et configurer

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

Le même programme dans les deux langages : créer une sandbox, exécuter du code, la supprimer.

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

Créer et retrouver des sandboxes

Sandbox.create(...) démarre une sandbox, en général en une seconde environ. Python prend des arguments nommés, TypeScript un objet d'options.

Sandbox.connect(id) se rattache à une sandbox existante, souvent une persistante créée la veille. Sandbox.list() renvoie toutes les sandboxes du compte, actives et en pause.

Propriétés : id (sb_ + 24 caractères hexadécimaux), mode, tariff, state (running, starting, paused, pausing, resuming, deleting, deleted), env_keys / envKeys (les noms seulement, les valeurs ne reviennent jamais) et info (l'objet brut). refresh() les recharge.

kill() supprime la sandbox et arrête la facturation. L'appeler sur une sandbox déjà supprimée n'est pas une erreur.

Exécuter du code

run(code, language="python", timeout=30) envoie le code sur stdin à Python 3.12, Node.js 22 ou bash ("python", "node", "bash"). exec(command, cwd=None, stdin=None, timeout=30) exécute une commande shell : une chaîne passe par bash -lc, une liste est exécutée comme argv sans shell.

Les deux renvoient un ExecResult :

Un appel synchrone dure 55 secondes au plus. Les deux méthodes acceptent aussi env pour cet appel seulement ; il remplace les valeurs définies à la création.

Tâches longues : l'arrière-plan

Passez background=True (TypeScript : { background: true }) et vous obtenez tout de suite une Task. Elle n'a pas de limite de 55 secondes et peut tourner jusqu'à la fin de vie de la sandbox. Jusqu'à 8 tâches par 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) });

Si wait atteint son propre délai, il lève SandboxTimeoutError, mais la tâche continue. Une tâche en cours empêche aussi qu'une sandbox éphémère soit supprimée pour inactivité.

Fichiers et consommation

upload(path, content, mode=None) écrit un fichier à un chemin absolu et renvoie sa taille. download(path) renvoie des octets, download_text(path) / downloadText(path) une chaîne. Un transfert est limité à 5 Mo.

usage() renvoie les secondes de fonctionnement, les secondes CPU consommées, les octets sortants, le prix horaire, billed_usd et estimated_total_usd. tariffs() est une simple fonction sans clé qui renvoie les prix et limites actuels. Les règles de facturation sont dans Limites et facturation des sandboxes.

Erreurs

Chaque erreur d'API est une sous-classe de EqvpsError avec status (HTTP), code (chaîne stable) et body. retry_after / retryAfter est renseigné quand le serveur l'envoie.

Deux limites provoquent la plupart des 429 : un compte exécute 2 commandes en même temps et garde jusqu'à 20 sandboxes. Le SDK relance ces requêtes quand le serveur indique combien attendre ; après trois essais, vous recevez l'exception.

Quand se passer du SDK

Tout langage doté d'un client HTTP peut appeler l'API directement ; les points d'accès sont décrits dans le fichier OpenAPI à https://eqvps.com/openapi.json. Les agents dans Claude, Cursor ou d'autres clients MCP n'ont besoin d'aucun code : le serveur MCP propose les mêmes outils de sandbox. Et pour simplement voir comment ça marche, la page des sandboxes liste les tarifs et l'essai à $1 pour les nouveaux comptes.