Python-SDK voor sandboxes in 5 minuten: van pip install eqvps naar je eerste run

Deze handleiding brengt je van niets naar een werkende sandbox in Python. Je start een geïsoleerde Firecracker-microVM, voert er code in uit, installeert een pakket, zet een bestand erin en haalt het er weer uit, en draait iets langs op de achtergrond. Elke stap is een paar regels om te plakken.

Je hebt Python 3.8 of nieuwer nodig en een EQVPS-account. De SDK heeft geen afhankelijkheden.

1. Haal een token

Sandboxes worden betaald uit je accountsaldo, dus de SDK heeft een accounttoken nodig. Je account koppelen toont de drie manieren om er een te krijgen: het dashboard, de API of de MCP-server. Zet hem daarna in de omgeving:

export EQVPS_API_KEY="your-token"

Nog geen saldo? Geen probleem. De eerste keer dat een nieuw account een sandbox aanmaakt zonder voldoende saldo, krijgt het $1 sandboxtegoed, 14 dagen geldig.

2. Installeer de SDK

pip install eqvps

3. Start een sandbox en voer code uit

Sla dit op als hello.py en draai het:

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)

Je ziet de sandbox-id (sb_ plus 24 tekens) en daarna 0 3.12.x. De sandbox startte in ongeveer een seconde, voerde de code uit en werd verwijderd toen het with-blok eindigde.

Goed om te weten over het resultaat:

• r.ok is true als de exitcode 0 is en het commando niet in een timeout liep;
• een exitcode die niet nul is, is geen exception, dus controleer r.ok zelf;
• stdout en stderr zijn elk begrensd op 1 MiB, en r.truncated vertelt of de uitvoer is afgekapt.

4. Installeer een pakket en draai shellcommando's

In de sandbox ben je root op een klein Linux-systeem met Python, Node.js, git en curl. exec voert elk shellcommando uit:

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

De standaardtimeout is 30 seconden en een synchrone aanroep duurt hooguit 55. Grote installaties horen in een achtergrondtaak (stap 6).

5. Bestanden erin en eruit

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

Paden moeten absoluut zijn. Eén overdracht is beperkt tot 5 MB; download geeft bytes terug, download_text een string.

6. Draai een lange taak op de achtergrond

Geef background=True mee en je krijgt een taak in plaats van te wachten. Die heeft geen grens van 55 seconden:

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() vraagt elke 2 seconden de status op en print nieuwe uitvoer zodra die binnenkomt. Je kunt ook zelf task.logs() aanroepen, of task.kill() om te stoppen. Zolang een taak draait, wordt de sandbox niet verwijderd wegens inactiviteit.

Wat dit kostte

Elk with-blok hierboven leefde een paar seconden en werd afgerekend tegen het minimum van 60 seconden. Op small is dat $0.00055 per blok, dus de vijf voorbeelden samen kosten ongeveer een derde cent. Prijzen voor elk tarief, de persistente modus en uitgavenlimieten staan in sandbox-limieten en facturering.

Als er iets misgaat

Fouten van de API zijn exceptions die je kunt afvangen:

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)

De SDK probeert 429- en 503-antwoorden zelf tot drie keer opnieuw als de server zegt hoe lang je moet wachten. Alle 11 foutklassen staan in de SDK-referentie.

Volgende stappen

• Dezelfde stappen in JavaScript: TypeScript-SDK voor sandboxes in 5 minuten.
• Laat een AI-model de code schrijven en hier draaien: je eerste agenttaak in een sandbox.
• Tarieven, de proefperiode en wat er in een sandbox zit: de sandboxpagina.