SDK Python pour sandboxes en 5 minutes : de pip install eqvps au premier lancement

Ce guide vous mène de zéro à une sandbox qui fonctionne, en Python. Vous allez démarrer une microVM Firecracker isolée, y exécuter du code, installer un paquet, faire entrer et sortir un fichier et lancer quelque chose de long en arrière-plan. Chaque étape tient en quelques lignes à coller.

Il vous faut Python 3.8 ou plus récent et un compte EQVPS. Le SDK n'a aucune dépendance.

1. Obtenir un token

Les sandboxes sont payées sur le solde du compte, le SDK a donc besoin d'un token de compte. Connecter votre compte montre les trois façons d'en obtenir un : le tableau de bord, l'API ou le serveur MCP. Placez-le ensuite dans l'environnement :

export EQVPS_API_KEY="your-token"

Pas encore de solde ? Aucun souci. La première fois qu'un nouveau compte crée une sandbox sans solde suffisant, il reçoit 1 $ de crédit sandbox, valable 14 jours.

2. Installer le SDK

pip install eqvps

3. Démarrer une sandbox et exécuter du code

Enregistrez ceci sous hello.py et lancez-le :

from eqvps import Sandbox

with Sandbox.create(tariff="small") as sb:
    print(sb.id)
    r = sb.run("import platform; print(platform.python_version())")
    print(r.exit_code, r.stdout)

Vous verrez l'identifiant de la sandbox (sb_ suivi de 24 caractères), puis 0 3.12.x. La sandbox a démarré en une seconde environ, a exécuté le code et a été supprimée à la fin du bloc with.

Bon à savoir sur le résultat :

• r.ok vaut true quand le code de sortie est 0 et que la commande n'a pas expiré ;
• un code de sortie non nul n'est pas une exception, vérifiez donc r.ok vous-même ;
• stdout et stderr sont plafonnés à 1 MiB chacun, et r.truncated indique si la sortie a été coupée.

4. Installer un paquet et lancer des commandes shell

Dans la sandbox, vous êtes root sur un petit système Linux avec Python, Node.js, git et curl. exec exécute n'importe quelle commande shell :

from eqvps import Sandbox

with Sandbox.create(tariff="small") as sb:
    sb.exec("pip install --quiet requests", timeout=55)
    r = sb.run("import requests; print(requests.get('https://example.com').status_code)")
    print(r.stdout)   # 200

Le délai par défaut est de 30 secondes et un appel synchrone dure au maximum 55. Les grosses installations relèvent d'une tâche de fond (étape 6).

5. Faire entrer et sortir des fichiers

from eqvps import Sandbox

with Sandbox.create() as sb:
    sb.upload("/root/data.csv", "a,b\n1,2\n3,4\n")
    sb.run("""
import csv
rows = list(csv.DictReader(open('/root/data.csv')))
open('/root/sum.txt', 'w').write(str(sum(int(r['b']) for r in rows)))
""")
    print(sb.download_text("/root/sum.txt"))   # 6

Les chemins doivent être absolus. Un transfert est limité à 5 MB ; download renvoie des octets, download_text une chaîne.

6. Lancer une longue tâche en arrière-plan

Passez background=True et vous obtenez une tâche au lieu d'attendre. Elle n'a pas de limite de 55 secondes :

from eqvps import Sandbox

with Sandbox.create(tariff="standard") as sb:
    task = sb.exec("for i in 1 2 3 4 5; do echo step $i; sleep 20; done", background=True)
    result = task.wait(on_output=lambda out, err: print(out, end=""))
    print(result.state, result.exit_code)   # done 0

task.wait() interroge toutes les 2 secondes et affiche la nouvelle sortie dès qu'elle arrive. Vous pouvez aussi appeler task.logs() vous-même, ou task.kill() pour l'arrêter. Tant qu'une tâche tourne, la sandbox n'est pas supprimée pour inactivité.

Ce que ça a coûté

Chaque bloc with ci-dessus a vécu quelques secondes et a été facturé au minimum de 60 secondes. Sur small, cela fait 0,00055 $ par bloc : les cinq exemples réunis coûtent environ un tiers de centime. Les prix de tous les tarifs, le mode persistant et les plafonds de dépenses sont dans limites et facturation des sandboxes.

Quand quelque chose échoue

Les erreurs de l'API sont des exceptions que vous pouvez intercepter :

from eqvps import Sandbox, InsufficientBalanceError, RateLimitError

try:
    with Sandbox.create() as sb:
        print(sb.run("print(1)").stdout)
except InsufficientBalanceError:
    print("Top up the balance")
except RateLimitError as e:
    print("Too many at once, retry in", e.retry_after)

Le SDK relance déjà les réponses 429 et 503 jusqu'à trois fois quand le serveur indique combien attendre. Les 11 classes d'erreur sont listées dans la référence du SDK.

Pour aller plus loin

• Les mêmes étapes en JavaScript : SDK TypeScript pour sandboxes en 5 minutes.
• Laisser un modèle d'IA écrire le code et l'exécuter ici : votre première tâche d'agent dans une sandbox.
• Tarifs, essai et contenu d'une sandbox : la page sandboxes.