SDK TypeScript para sandboxes em 5 minutos: do npm i @eqvps/sdk à primeira execução

Este guia coloca uma sandbox para rodar a partir de JavaScript ou TypeScript. Você vai iniciar uma microVM Firecracker isolada, executar código em três linguagens, mover arquivos e acompanhar a saída de um trabalho longo. Cada passo é um trecho curto.

Você precisa do Node.js 18+ (ou Deno, ou Bun) e de uma conta EQVPS.

1. Obtenha um token

O SDK se autentica com um token de conta comum. Conectar sua conta mostra como obtê-lo pelo painel, pela API ou pelo servidor MCP.

export EQVPS_API_KEY="your-token"

Uma conta nova sem saldo recebe US$ 1 de crédito para sandboxes na primeira vez que cria uma. Isso cobre este guia muitas vezes.

2. Instale o SDK

npm i @eqvps/sdk

Os exemplos usam módulos ES e await no nível superior. Salve-os como arquivos .mjs, ou como .ts e rode com npx tsx.

3. Inicie uma sandbox e execute código

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

await Sandbox.with({ tariff: "small" }, async (sb) => {
  console.log(sb.id);
  const r = await sb.run("import platform; print(platform.python_version())");
  console.log(r.exit_code, r.stdout);
});

A saída é o id da sandbox (sb_ e mais 24 caracteres) e depois 0 3.12.x. Sandbox.with apaga a sandbox quando o callback termina, mesmo se ele lançar exceção.

A linguagem padrão é Python. As outras duas estão a uma opção de distância:

await Sandbox.with({}, async (sb) => {
  const js = await sb.run("console.log(process.version)", { language: "node" });
  const sh = await sb.run("uname -r && nproc", { language: "bash" });
  console.log(js.stdout, sh.stdout);
});

Um script que falha não lança nada. Confira r.ok, que é true quando exit_code é 0 e o comando não estourou o tempo.

4. Comandos de shell e pacotes

exec aceita uma string de shell ou um array argv. A sandbox tem acesso à internet, então instalações com npm e pip funcionam:

await Sandbox.with({ tariff: "small" }, async (sb) => {
  await sb.exec("mkdir -p /root/app && cd /root/app && npm init -y && npm i lodash", { timeout: 55 });
  const r = await sb.exec(["node", "-e", "console.log(require('/root/app/node_modules/lodash').VERSION)"]);
  console.log(r.stdout);
});

Uma chamada síncrona dura no máximo 55 segundos. Qualquer coisa mais longa vai para uma tarefa em segundo plano (passo 6).

5. Arquivos

await Sandbox.with({}, async (sb) => {
  await sb.upload("/root/input.json", JSON.stringify({ values: [3, 5, 8] }));
  await sb.run("import json; d = json.load(open('/root/input.json')); open('/root/out.txt', 'w').write(str(sum(d['values'])))");
  console.log(await sb.downloadText("/root/out.txt"));   // 16
});

upload aceita uma string ou um Uint8Array. download devolve um Uint8Array, downloadText uma string. Cada transferência é limitada a 5 MB.

6. Trabalhos longos com saída ao vivo

await Sandbox.with({ tariff: "standard" }, async (sb) => {
  const task = await sb.exec("for i in 1 2 3 4 5; do echo step $i; sleep 20; done", { background: true });
  const res = await task.wait({ onOutput: (out) => process.stdout.write(out) });
  console.log(res.state, res.exit_code);   // done 0
});

A tarefa retorna na hora e não tem o limite de 55 segundos. wait consulta a cada 2 segundos por padrão (pollIntervalMs muda isso). task.kill() a interrompe; sb.task(id) se reconecta a partir de outro processo.

Erros

import { Sandbox, InsufficientBalanceError, RateLimitError } from "@eqvps/sdk";

try {
  await Sandbox.with({}, async (sb) => console.log((await sb.run("print(1)")).stdout));
} catch (e) {
  if (e instanceof InsufficientBalanceError) console.log("Top up the balance");
  else if (e instanceof RateLimitError) console.log("Busy, retry in", e.retryAfter);
  else throw e;
}

O SDK repete sozinho 429 e 503, até três vezes, quando o servidor envia Retry-After. O 429 mais comum vem de rodar mais de dois comandos ao mesmo tempo numa conta. Todas as classes estão na referência do SDK.

Custo deste guia

Cada exemplo viveu poucos segundos e foi cobrado pelo mínimo de 60 segundos: US$ 0,00055 na small, US$ 0,0011 na standard. O trabalho do passo 6 rodou cerca de 100 segundos na standard, uns US$ 0,002. Tudo junto fica bem abaixo de um centavo. A tabela completa está em limites e cobrança de sandboxes.

Próximos passos

• O mesmo em Python: SDK Python para sandboxes em 5 minutos.
• Conecte um modelo e deixe-o rodar o próprio código: sua primeira tarefa de agente numa sandbox.
• Tarifas e o teste de US$ 1: a página de sandboxes.