SDK Python per sandbox in 5 minuti: da pip install eqvps alla prima esecuzione

Questa guida ti porta da zero a una sandbox funzionante in Python. Avvierai una microVM Firecracker isolata, ci eseguirai del codice, installerai un pacchetto, sposterai un file dentro e fuori e lancerai qualcosa di lungo in background. Ogni passo sono poche righe da incollare.

Ti servono Python 3.8 o successivo e un account EQVPS. L'SDK non ha dipendenze.

1. Ottieni un token

Le sandbox si pagano con il saldo dell'account, quindi l'SDK ha bisogno di un token dell'account. Collegare l'account mostra i tre modi per ottenerlo: la dashboard, l'API o il server MCP. Poi mettilo nell'ambiente:

export EQVPS_API_KEY="your-token"

Non hai ancora saldo? Nessun problema. La prima volta che un nuovo account crea una sandbox senza saldo sufficiente, riceve 1 $ di credito per sandbox, valido 14 giorni.

2. Installa l'SDK

pip install eqvps

3. Avvia una sandbox ed esegui codice

Salva questo come hello.py ed eseguilo:

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)

Vedrai l'id della sandbox (sb_ più altri 24 caratteri) e poi 0 3.12.x. La sandbox si è avviata in circa un secondo, ha eseguito il codice ed è stata eliminata alla fine del blocco with.

Cose utili da sapere sul risultato:

• r.ok è true quando il codice di uscita è 0 e il comando non è andato in timeout;
• un codice di uscita diverso da zero non è un'eccezione, quindi controlla r.ok da te;
• stdout e stderr hanno un tetto di 1 MiB ciascuno, e r.truncated ti dice se l'output è stato tagliato.

4. Installa un pacchetto ed esegui comandi shell

Dentro la sandbox sei root su un piccolo sistema Linux con Python, Node.js, git e curl. exec esegue qualsiasi comando 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

Il timeout predefinito è di 30 secondi e una chiamata sincrona dura al massimo 55. Le installazioni grandi vanno in un task in background (passo 6).

5. Sposta file dentro e fuori

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

I percorsi devono essere assoluti. Un trasferimento è limitato a 5 MB; download restituisce byte, download_text una stringa.

6. Lancia un lavoro lungo in background

Passa background=True e ottieni un task invece di aspettare. Non ha il limite di 55 secondi:

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() interroga ogni 2 secondi e stampa il nuovo output appena arriva. Puoi anche chiamare tu task.logs(), o task.kill() per fermarlo. Finché un task è in esecuzione, la sandbox non viene eliminata per inattività.

Quanto è costato

Ogni blocco with qui sopra è vissuto pochi secondi ed è stato fatturato al minimo di 60 secondi. Su small fanno 0,00055 $ a blocco, quindi i cinque esempi insieme costano circa un terzo di centesimo. I prezzi di tutte le tariffe, la modalità persistente e i tetti di spesa sono in limiti e fatturazione delle sandbox.

Quando qualcosa va storto

Gli errori dell'API sono eccezioni che puoi intercettare:

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)

L'SDK ripete già le risposte 429 e 503 fino a tre volte quando il server indica quanto aspettare. Tutte le 11 classi di errore sono nel riferimento dell'SDK.

Prossimi passi

• Gli stessi passi in JavaScript: SDK TypeScript per sandbox in 5 minuti.
• Lascia che un modello di IA scriva il codice e lo esegua qui: il tuo primo task da agente in una sandbox.
• Tariffe, prova e cosa c'è dentro una sandbox: la pagina delle sandbox.