SDK Python para sandboxes em 5 minutos: do pip install eqvps à primeira execução

Este guia leva você do zero a uma sandbox funcionando em Python. Você vai iniciar uma microVM Firecracker isolada, executar código nela, instalar um pacote, colocar e tirar um arquivo e rodar algo longo em segundo plano. Cada passo são poucas linhas para colar.

Você precisa do Python 3.8 ou mais recente e de uma conta EQVPS. O SDK não tem dependências.

1. Obtenha um token

As sandboxes são pagas com o saldo da conta, então o SDK precisa de um token da conta. Conectar sua conta mostra as três formas de obtê-lo: o painel, a API ou o servidor MCP. Depois coloque-o no ambiente:

export EQVPS_API_KEY="your-token"

Ainda sem saldo? Tudo bem. Na primeira vez que uma conta nova cria uma sandbox sem saldo suficiente, ela recebe US$ 1 de crédito para sandboxes, válido por 14 dias.

2. Instale o SDK

pip install eqvps

3. Inicie uma sandbox e execute código

Salve isto como hello.py e rode:

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)

Você verá o id da sandbox (sb_ e mais 24 caracteres) e depois 0 3.12.x. A sandbox subiu em cerca de um segundo, executou o código e foi apagada quando o bloco with terminou.

Vale saber sobre o resultado:

• r.ok é true quando o código de saída é 0 e o comando não estourou o tempo;
• um código de saída diferente de zero não é exceção, então confira r.ok você mesmo;
• stdout e stderr são limitados a 1 MiB cada, e r.truncated avisa se a saída foi cortada.

4. Instale um pacote e rode comandos de shell

Dentro da sandbox você é root num pequeno sistema Linux com Python, Node.js, git e curl. exec roda qualquer 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

O timeout padrão é de 30 segundos, e uma chamada síncrona dura no máximo 55. Instalações grandes ficam numa tarefa em segundo plano (passo 6).

5. Coloque e tire arquivos

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

Os caminhos precisam ser absolutos. Cada transferência é limitada a 5 MB; download devolve bytes, download_text uma string.

6. Rode um trabalho longo em segundo plano

Passe background=True e você recebe uma tarefa em vez de esperar. Ela não tem o limite 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 a cada 2 segundos e imprime a saída nova assim que chega. Você também pode chamar task.logs() por conta própria, ou task.kill() para pará-la. Enquanto uma tarefa roda, a sandbox não é apagada por inatividade.

Quanto custou

Cada bloco with acima viveu poucos segundos e foi cobrado pelo mínimo de 60 segundos. Na small, isso dá US$ 0,00055 por bloco, então os cinco exemplos juntos custam cerca de um terço de centavo. Os preços de todas as tarifas, o modo persistente e os limites de gasto estão em limites e cobrança de sandboxes.

Quando algo dá errado

Erros da API são exceções que você pode 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)

O SDK já repete respostas 429 e 503 até três vezes quando o servidor informa quanto esperar. As 11 classes de erro estão na referência do SDK.

Próximos passos

• Os mesmos passos em JavaScript: SDK TypeScript para sandboxes em 5 minutos.
• Deixe um modelo de IA escrever o código e rodar aqui: sua primeira tarefa de agente numa sandbox.
• Tarifas, teste e o que há dentro de uma sandbox: a página de sandboxes.