SDK de Python para sandboxes en 5 minutos: de pip install eqvps a la primera ejecución

Esta guía te lleva de cero a una sandbox funcionando en Python. Arrancarás una microVM Firecracker aislada, ejecutarás código en ella, instalarás un paquete, meterás y sacarás un archivo y lanzarás algo largo en segundo plano. Cada paso son unas pocas líneas para pegar.

Necesitas Python 3.8 o posterior y una cuenta de EQVPS. El SDK no tiene dependencias.

1. Consigue un token

Las sandboxes se pagan con el saldo de la cuenta, así que el SDK necesita un token de cuenta. Conectar tu cuenta muestra las tres formas de conseguirlo: el panel, la API o el servidor MCP. Después ponlo en el entorno:

export EQVPS_API_KEY="your-token"

¿Aún no tienes saldo? No pasa nada. La primera vez que una cuenta nueva crea una sandbox sin saldo suficiente, recibe 1 $ de crédito para sandboxes, válido durante 14 días.

2. Instala el SDK

pip install eqvps

3. Arranca una sandbox y ejecuta código

Guarda esto como hello.py y ejecútalo:

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)

Verás el id de la sandbox (sb_ y 24 caracteres más) y luego 0 3.12.x. La sandbox arrancó en un segundo, ejecutó el código y se borró al terminar el bloque with.

Conviene saber sobre el resultado:

• r.ok es true cuando el código de salida es 0 y el comando no agotó su tiempo;
• un código de salida distinto de cero no es una excepción, así que comprueba r.ok tú mismo;
• stdout y stderr tienen un tope de 1 MiB cada uno, y r.truncated te dice si la salida se cortó.

4. Instala un paquete y ejecuta comandos de shell

Dentro de la sandbox eres root en un pequeño sistema Linux con Python, Node.js, git y curl. exec ejecuta cualquier comando de 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

El tiempo límite por defecto es de 30 segundos y una llamada síncrona dura como máximo 55. Las instalaciones grandes van en una tarea en segundo plano (paso 6).

5. Mete y saca archivos

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

Las rutas deben ser absolutas. Cada transferencia está limitada a 5 MB; download devuelve bytes y download_text una cadena.

6. Lanza un trabajo largo en segundo plano

Pasa background=True y obtendrás una tarea en lugar de esperar. No tiene el límite de 55 segundos:

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() consulta cada 2 segundos e imprime la salida nueva a medida que llega. También puedes llamar tú a task.logs(), o a task.kill() para detenerla. Mientras una tarea corre, la sandbox no se borra por inactividad.

Lo que costó

Cada bloque with de arriba vivió unos segundos y se facturó con el mínimo de 60 segundos. En small son 0,00055 $ por bloque, así que los cinco ejemplos juntos cuestan alrededor de un tercio de centavo. Los precios de todas las tarifas, el modo persistente y los topes de gasto están en límites y facturación de sandboxes.

Cuando algo falla

Los errores de la API son excepciones que puedes capturar:

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)

El SDK ya reintenta las respuestas 429 y 503 hasta tres veces cuando el servidor indica cuánto esperar. Las 11 clases de error están en la referencia del SDK.

Siguientes pasos

• Los mismos pasos en JavaScript: SDK de TypeScript para sandboxes en 5 minutos.
• Deja que un modelo de IA escriba el código y lo ejecute aquí: tu primera tarea de agente en una sandbox.
• Tarifas, prueba y qué hay dentro de una sandbox: la página de sandboxes.