TypeScript-SDK til sandkasser på 5 minutter: fra npm i @eqvps/sdk til første kørsel

Denne guide får en sandkasse i gang fra JavaScript eller TypeScript. Du starter en isoleret Firecracker-microVM, kører kode i tre sprog, flytter filer og følger output fra et langt job. Hvert trin er et kort kodestykke.

Du skal bruge Node.js 18+ (eller Deno, eller Bun) og en EQVPS-konto.

1. Skaf en token

SDK'et godkender sig med en almindelig kontotoken. Forbind din konto viser, hvordan du får en fra kontrolpanelet, API'et eller MCP-serveren.

export EQVPS_API_KEY="your-token"

En ny konto uden saldo får 1 $ i sandkassekredit, første gang den opretter en sandkasse. Det dækker denne guide mange gange.

2. Installér SDK'et

npm i @eqvps/sdk

Eksemplerne bruger ES-moduler og await på topniveau. Gem dem som .mjs-filer, eller som .ts og kør dem med npx tsx.

3. Start en sandkasse og kør kode

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

Output er sandkassens id (sb_ og 24 tegn mere), derefter 0 3.12.x. Sandbox.with sletter sandkassen, når callbacken er færdig, også hvis den kaster en fejl.

Standardsproget er Python. De to andre er én indstilling væk:

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

Et script, der fejler, kaster intet. Tjek r.ok, som er true, når exit_code er 0, og kommandoen ikke ramte sin timeout.

4. Shellkommandoer og pakker

exec tager en shellstreng eller et argv-array. Sandkassen har internetadgang, så installationer med npm og pip virker:

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

Et synkront kald må højst tage 55 sekunder. Alt længere skal i en baggrundsopgave (trin 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 tager en streng eller en Uint8Array. download returnerer en Uint8Array, downloadText en streng. En overførsel er begrænset til 5 MB.

6. Lange job med live output

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

Opgaven vender straks tilbage og har ingen grænse på 55 sekunder. wait spørger som standard hvert 2. sekund (pollIntervalMs ændrer det). task.kill() stopper den; sb.task(id) kobler sig på igen fra en anden proces.

Fejl

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'et prøver selv 429 og 503 igen, op til tre gange, når serveren sender Retry-After. Den mest almindelige 429 opstår, når mere end to kommandoer kører samtidig på én konto. Alle klasser står i SDK-referencen.

Hvad guiden koster

Hvert eksempel levede et par sekunder og blev afregnet med minimum på 60 sekunder: 0,00055 $ på small, 0,0011 $ på standard. Jobbet i trin 6 kørte cirka 100 sekunder på standard, omkring 0,002 $. Det hele tilsammen er langt under en cent. Den fulde prisliste står i grænser og afregning for sandboxes.

Næste skridt

• Det samme i Python: Python-SDK til sandkasser på 5 minutter.
• Forbind en model, og lad den køre sin egen kode: din første agentopgave i en sandkasse.
• Tariffer og prøven til 1 $: sandkassesiden.