TypeScript-SDK för sandlådor på 5 minuter: från npm i @eqvps/sdk till första körningen

Den här guiden får igång en sandlåda från JavaScript eller TypeScript. Du startar en isolerad Firecracker-microVM, kör kod på tre språk, flyttar filer och följer utdata från ett långt jobb. Varje steg är ett kort kodavsnitt.

Du behöver Node.js 18+ (eller Deno, eller Bun) och ett EQVPS-konto.

1. Skaffa en token

SDK:t autentiserar med en vanlig kontotoken. Koppla ditt konto visar hur du får en från kontrollpanelen, API:t eller MCP-servern.

export EQVPS_API_KEY="your-token"

Ett nytt konto utan saldo får 1 $ sandlådekredit första gången det skapar en sandlåda. Det räcker till den här guiden många gånger om.

2. Installera SDK:t

npm i @eqvps/sdk

Exemplen använder ES-moduler och await på toppnivå. Spara dem som .mjs-filer, eller som .ts och kör dem med npx tsx.

3. Starta en sandlåda och kör kod

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);
});

Utdata är sandlådans id (sb_ och 24 tecken till), sedan 0 3.12.x. Sandbox.with raderar sandlådan när callbacken är klar, även om den kastar ett fel.

Standardspråket är Python. De andra två är ett alternativ bort:

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);
});

Ett skript som misslyckas kastar inget. Kontrollera r.ok, som är true när exit_code är 0 och kommandot inte slog i tidsgränsen.

4. Skalkommandon och paket

exec tar en skalsträng eller en argv-array. Sandlådan har internetåtkomst, så installationer med npm och pip fungerar:

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);
});

Ett synkront anrop får ta högst 55 sekunder. Allt längre går till en bakgrundsuppgift (steg 6).

5. Filer

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 tar en sträng eller en Uint8Array. download returnerar en Uint8Array, downloadText en sträng. En överföring är begränsad till 5 MB.

6. Långa jobb med utdata i realtid

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
});

Uppgiften returnerar direkt och har ingen gräns på 55 sekunder. wait frågar som standard var 2:a sekund (pollIntervalMs ändrar det). task.kill() stoppar den; sb.task(id) kopplar upp sig igen från en annan process.

Fel

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;
}

SDK:t gör själv om 429 och 503, upp till tre gånger, när servern skickar Retry-After. Den vanligaste 429 uppstår när mer än två kommandon körs samtidigt på ett konto. Varje klass finns i SDK-referensen.

Vad guiden kostar

Varje exempel levde några sekunder och debiterades minimitiden på 60 sekunder: 0,00055 $ på small, 0,0011 $ på standard. Jobbet i steg 6 körde ungefär 100 sekunder på standard, runt 0,002 $. Allt tillsammans hamnar långt under en cent. Hela prislistan finns i sandlådors gränser och debitering.

Nästa steg

• Samma sak i Python: Python-SDK för sandlådor på 5 minuter.
• Koppla in en modell och låt den köra sin egen kod: din första agentuppgift i en sandlåda.
• Tariffer och provperioden på 1 $: sandlådesidan.