Referência da API de sandboxes: SDK Python e TypeScript

O SDK é uma camada fina sobre a API REST de sandboxes. Ele poupa você de três coisas: montar requisições à mão, repeti-las quando a plataforma está ocupada e esquecer de apagar uma sandbox quando o código lança uma exceção. Tudo aqui corresponde à versão 0.2.0 dos dois pacotes.

Se você nunca criou uma sandbox, o guia de conexão em 5 minutos entrega um token primeiro. O que é uma sandbox e o que tem dentro está em Sandboxes.

Instalar e configurar

pip install eqvps          # Python 3.8+
npm i @eqvps/sdk           # Node.js 18+, Deno, Bun
export EQVPS_API_KEY=...   # your EQVPS account token

O mesmo programa nas duas linguagens: criar uma sandbox, rodar código, apagá-la.

from eqvps import Sandbox

with Sandbox.create(tariff="small") as sb:
    r = sb.run("print(2 + 2)")
    print(r.exit_code, r.stdout)   # 0 4

import { Sandbox } from "@eqvps/sdk";

await Sandbox.with({ tariff: "small" }, async (sb) => {
  const r = await sb.run("print(2 + 2)");
  console.log(r.exit_code, r.stdout); // 0 4
});

Criar e encontrar sandboxes

Sandbox.create(...) inicia uma sandbox, normalmente em cerca de um segundo. Python recebe argumentos nomeados; TypeScript, um objeto de opções.

Sandbox.connect(id) se conecta a uma sandbox existente, em geral uma persistente que você criou ontem. Sandbox.list() devolve todas as sandboxes da conta, ativas e pausadas.

Propriedades: id (sb_ + 24 caracteres hexadecimais), mode, tariff, state (running, starting, paused, pausing, resuming, deleting, deleted), env_keys / envKeys (só os nomes; os valores nunca voltam) e info (o objeto bruto). refresh() recarrega tudo.

kill() apaga a sandbox e para a cobrança. Chamar em uma sandbox que já não existe não é erro.

Rodar código

run(code, language="python", timeout=30) manda o código pelo stdin para Python 3.12, Node.js 22 ou bash ("python", "node", "bash"). exec(command, cwd=None, stdin=None, timeout=30) executa um comando de shell: uma string passa por bash -lc, uma lista é executada como argv sem shell.

Os dois devolvem um ExecResult:

Uma chamada síncrona roda por no máximo 55 segundos. Os dois métodos também aceitam env só para aquela chamada; ele substitui os valores definidos na criação.

Trabalhos longos: tarefas em segundo plano

Passe background=True (TypeScript: { background: true }) e você recebe uma Task na hora. Ela não tem o limite de 55 segundos e pode rodar até o fim da vida da sandbox. Até 8 tarefas por sandbox.

task = sb.exec("cd /root/app && python3 -m pytest -q", background=True)
result = task.wait(on_output=lambda out, err: print(out, end=""))
print(result.state, result.exit_code)   # done 0

const task = await sb.exec("cd /root/app && npm test", { background: true });
const result = await task.wait({ onOutput: (out) => process.stdout.write(out) });

Se o wait estourar o próprio tempo, ele lança SandboxTimeoutError, mas a tarefa continua rodando. Uma tarefa em andamento também impede que uma sandbox efêmera seja apagada por inatividade.

Arquivos e consumo

upload(path, content, mode=None) grava um arquivo em um caminho absoluto e devolve o tamanho. download(path) devolve bytes; download_text(path) / downloadText(path), uma string. Uma transferência é limitada a 5 MB.

usage() devolve os segundos em execução, os segundos de CPU usados, os bytes de saída, o preço por hora, billed_usd e estimated_total_usd. tariffs() é uma função simples que não precisa de chave e devolve preços e limites atuais. As regras de cobrança estão em Limites e cobrança de sandboxes.

Erros

Todo erro da API é uma subclasse de EqvpsError com status (HTTP), code (string estável) e body. retry_after / retryAfter vem preenchido quando o servidor o envia.

Dois limites causam a maioria dos 429: uma conta executa 2 comandos ao mesmo tempo e mantém até 20 sandboxes. O SDK repete essas requisições quando o servidor diz quanto esperar; depois de três tentativas, você recebe a exceção.

Quando dispensar o SDK

Qualquer linguagem com um cliente HTTP pode chamar a API diretamente; os endpoints estão no arquivo OpenAPI em https://eqvps.com/openapi.json. Agentes no Claude, Cursor ou outros clientes MCP não precisam de código nenhum: o servidor MCP tem as mesmas ferramentas de sandbox. E se você só quer ver funcionando, a página de sandboxes mostra os planos e o teste de $1 para contas novas.