Python-SDK für Sandboxes in 5 Minuten: von pip install eqvps zum ersten Lauf

Diese Anleitung bringt Sie von null zu einer laufenden Sandbox in Python. Sie starten eine isolierte Firecracker-MicroVM, führen darin Code aus, installieren ein Paket, schieben eine Datei hinein und wieder heraus und lassen etwas Langes im Hintergrund laufen. Jeder Schritt sind ein paar Zeilen zum Einfügen.

Sie brauchen Python 3.8 oder neuer und ein EQVPS-Konto. Das SDK hat keine Abhängigkeiten.

1. Token besorgen

Sandboxes werden vom Kontoguthaben bezahlt, deshalb braucht das SDK einen Konto-Token. Konto verbinden zeigt die drei Wege dorthin: Dashboard, API oder MCP-Server. Legen Sie ihn dann in die Umgebung:

export EQVPS_API_KEY="your-token"

Noch kein Guthaben? Kein Problem. Wenn ein neues Konto zum ersten Mal ohne ausreichendes Guthaben eine Sandbox erstellt, erhält es $1 Sandbox-Guthaben, gültig für 14 Tage.

2. SDK installieren

pip install eqvps

3. Sandbox starten und Code ausführen

Speichern Sie das als hello.py und starten Sie es:

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)

Sie sehen die Sandbox-ID (sb_ und 24 weitere Zeichen) und danach 0 3.12.x. Die Sandbox ist in etwa einer Sekunde gestartet, hat den Code ausgeführt und wurde gelöscht, als der with-Block endete.

Gut zu wissen über das Ergebnis:

• r.ok ist true, wenn der Exit-Code 0 ist und der Befehl nicht ins Timeout lief;
• ein Exit-Code ungleich null ist keine Exception, prüfen Sie r.ok also selbst;
• stdout und stderr sind auf je 1 MiB begrenzt, r.truncated zeigt an, ob die Ausgabe gekürzt wurde.

4. Paket installieren und Shell-Befehle ausführen

In der Sandbox sind Sie root auf einem kleinen Linux-System mit Python, Node.js, git und curl. exec führt jeden Shell-Befehl aus:

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

Das Standard-Timeout beträgt 30 Sekunden, ein synchroner Aufruf darf höchstens 55 dauern. Große Installationen gehören in einen Hintergrund-Task (Schritt 6).

5. Dateien hinein und heraus

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

Pfade müssen absolut sein. Eine Übertragung ist auf 5 MB begrenzt; download liefert Bytes, download_text einen String.

6. Langen Job im Hintergrund laufen lassen

Übergeben Sie background=True, und Sie bekommen einen Task, statt zu warten. Er hat keine 55-Sekunden-Grenze:

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() fragt alle 2 Sekunden ab und gibt neue Ausgabe aus, sobald sie ankommt. Sie können auch selbst task.logs() aufrufen oder den Task mit task.kill() stoppen. Solange ein Task läuft, wird die Sandbox nicht wegen Inaktivität gelöscht.

Was das gekostet hat

Jeder with-Block oben lebte ein paar Sekunden und wurde mit dem Minimum von 60 Sekunden abgerechnet. Auf small sind das $0.00055 pro Block, alle fünf Beispiele zusammen kosten also etwa ein Drittel Cent. Preise aller Tarife, der persistente Modus und Ausgabenlimits stehen unter Sandbox-Limits und Abrechnung.

Wenn etwas schiefgeht

API-Fehler sind Exceptions, die Sie abfangen können:

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)

Das SDK wiederholt 429- und 503-Antworten selbst bis zu dreimal, wenn der Server sagt, wie lange zu warten ist. Alle 11 Fehlerklassen stehen in der SDK-Referenz.

Nächste Schritte

• Dieselben Schritte in JavaScript: TypeScript-SDK für Sandboxes in 5 Minuten.
• Lassen Sie ein KI-Modell den Code schreiben und hier ausführen: Ihre erste Agentenaufgabe in einer Sandbox.
• Tarife, Testguthaben und was in einer Sandbox steckt: die Sandbox-Seite.