Welke runtimes ondersteunt @eqvps/sdk?

Node.js 18 en nieuwer, Deno en Bun. Het heeft geen afhankelijkheden en gebruikt de ingebouwde fetch, dus het draait ook in een browser, maar zet je accounttoken niet in frontendcode.

Kan de sandbox Python draaien als mijn app in TypeScript is?

Ja. De taal van je app en de taal van de sandboxcode staan los van elkaar. run accepteert language python, node of bash, en exec voert elk shellcommando uit.

Hoe zorg ik dat de sandbox wordt verwijderd?

Gebruik Sandbox.with(options, fn); dat verwijdert de sandbox als fn klaar is of een fout gooit. Met TypeScript 5.2 of nieuwer kun je ook await using sb = await Sandbox.create() schrijven.

Wat geeft run terug als de code faalt?

Een ExecResult met een exit_code die niet nul is en de fout in stderr. Er wordt niets gegooid. Exceptions zijn er alleen voor API-fouten zoals een ongeldig token of een leeg saldo.

JavaScript-sandbox-SDK in 5 minuten: 6 stappen

Installeer @eqvps/sdk, start een Firecracker-sandbox vanuit Node.js, Deno of Bun, voer er Python-, Node- en shellcode in uit, verplaats bestanden en volg een lange taak live. Zes stappen met elke regel code.

Deze handleiding laat een sandbox draaien vanuit JavaScript of TypeScript. Je start een geïsoleerde Firecracker-microVM, voert code uit in drie talen, verplaatst bestanden en volgt de uitvoer van een lange taak. Elke stap is een kort fragment.

Je hebt Node.js 18+ (of Deno, of Bun) nodig en een EQVPS-account.

1. Haal een token

De SDK authenticeert met een gewoon accounttoken. Je account koppelen laat zien hoe je er een krijgt via het dashboard, de API of de MCP-server.

export EQVPS_API_KEY="your-token"

Een nieuw account zonder saldo krijgt $1 sandboxtegoed de eerste keer dat het een sandbox aanmaakt. Dat dekt deze handleiding vele malen.

2. Installeer de SDK

npm i @eqvps/sdk

De voorbeelden gebruiken ES-modules en top-level await. Sla ze op als .mjs-bestanden, of als .ts en draai ze met npx tsx.

3. Start een sandbox en voer code uit

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

De uitvoer is de sandbox-id (sb_ plus 24 tekens), dan 0 3.12.x. Sandbox.with verwijdert de sandbox als de callback klaar is, ook als die een fout gooit.

De standaardtaal is Python. De andere twee zijn één optie verder:

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

Een falend script gooit niets. Controleer r.ok, dat true is als exit_code 0 is en het commando niet in een timeout liep.

4. Shellcommando's en pakketten

exec neemt een shellstring of een argv-array. De sandbox heeft internettoegang, dus installaties met npm en pip werken:

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

Een synchrone aanroep duurt hooguit 55 seconden. Alles wat langer duurt, gaat in een achtergrondtaak (stap 6).

5. Bestanden

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 neemt een string of een Uint8Array. download geeft een Uint8Array terug, downloadText een string. Eén overdracht is beperkt tot 5 MB.

6. Lange taken met live uitvoer

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

De taak keert meteen terug en heeft geen grens van 55 seconden. wait vraagt standaard elke 2 seconden de status op (pollIntervalMs verandert dat). task.kill() stopt hem; sb.task(id) koppelt opnieuw vanuit een ander proces.

Fouten

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

De SDK probeert 429 en 503 zelf tot drie keer opnieuw als de server Retry-After stuurt. De meest voorkomende 429 ontstaat als je meer dan twee commando's tegelijk draait op één account. Elke klasse staat in de SDK-referentie.

Kosten van deze handleiding

Elk voorbeeld leefde een paar seconden en werd afgerekend tegen het minimum van 60 seconden: $0.00055 op small, $0.0011 op standard. De taak uit stap 6 draaide ongeveer 100 seconden op standard, zo'n $0.002. Alles samen blijft ruim onder een cent. De volledige prijslijst staat in sandbox-limieten en facturering.

Volgende stappen

Hetzelfde in Python: Python-SDK voor sandboxes in 5 minuten.
Koppel een model en laat het zijn eigen code draaien: je eerste agenttaak in een sandbox.
Tarieven en de proef van $1: de sandboxpagina.

TypeScript-SDK voor sandboxes in 5 minuten: van npm i @eqvps/sdk naar je eerste run