TypeScript SDK за пясъчници за 5 минути: от npm i @eqvps/sdk до първото пускане

Това ръководство пуска пясъчник от JavaScript или TypeScript. Ще стартирате изолирана microVM на Firecracker, ще изпълните код на три езика, ще прехвърлите файлове и ще следите изхода на дълга задача. Всяка стъпка е кратък фрагмент.

Нужни са ви Node.js 18+ (или Deno, или Bun) и акаунт в EQVPS.

1. Вземете токен

SDK се удостоверява с обикновен токен на акаунта. Страницата свързване на акаунта показва как да го вземете от таблото, API или MCP сървъра.

export EQVPS_API_KEY="your-token"

Нов акаунт без наличност получава 1 $ кредит за пясъчници, когато за първи път създаде пясъчник. Това стига за ръководството многократно.

2. Инсталирайте SDK

npm i @eqvps/sdk

Примерите използват ES модули и await на най-горно ниво. Запазете ги като файлове .mjs или като .ts и ги пускайте с npx tsx.

3. Пуснете пясъчник и изпълнете код

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

Изходът е id на пясъчника (sb_ и още 24 знака), след това 0 3.12.x. Sandbox.with изтрива пясъчника, когато callback-ът приключи, дори ако хвърли грешка.

Езикът по подразбиране е Python. Другите два са на една опция разстояние:

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

Скрипт, който се проваля, не хвърля нищо. Проверявайте r.ok, което е true, когато exit_code е 0 и командата не е стигнала таймаута си.

4. Shell команди и пакети

exec приема shell низ или масив argv. Пясъчникът има достъп до интернет, така че инсталирането с npm и pip работи:

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

Синхронно извикване трае най-много 55 секунди. Всичко по-дълго отива във фонова задача (стъпка 6).

5. Файлове

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 приема низ или Uint8Array. download връща Uint8Array, downloadText — низ. Едно прехвърляне е ограничено до 5 MB.

6. Дълги задачи с изход на живо

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

Задачата се връща веднага и няма ограничение от 55 секунди. wait по подразбиране проверява на всеки 2 секунди (pollIntervalMs го променя). task.kill() я спира; sb.task(id) се свързва отново от друг процес.

Грешки

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 сам повтаря 429 и 503 до три пъти, когато сървърът изпрати Retry-After. Най-честото 429 идва от пускане на повече от две команди едновременно в един акаунт. Всички класове са в справочника за SDK.

Цената на ръководството

Всеки пример живя няколко секунди и беше таксуван с минимума от 60 секунди: 0,00055 $ на small, 0,0011 $ на standard. Задачата от стъпка 6 работи около 100 секунди на standard, около 0,002 $. Всичко заедно е далеч под един цент. Пълният ценоразпис е в лимити и таксуване на пясъчниците.

Следващи стъпки

• Същото на Python: Python SDK за пясъчници за 5 минути.
• Свържете модел и го оставете да пуска собствения си код: първата ви агентска задача в пясъчник.
• Тарифи и пробата за 1 $: страницата на пясъчниците.