@eqvps/sdk — code sandboxes for AI agents (TypeScript / JavaScript)

Isolated Firecracker microVMs in ~1 second: Linux with Python 3.12 + pip, Node.js 22 + npm, bash, git and curl (3–40 GB disk by tariff), internet egress (pip/npm install and git clone work), no inbound ports. Billed per second from your prepaid EQVPS balance — same balance as VPS, no subscription. Zero dependencies; Node 18+, Deno, Bun.

npm i @eqvps/sdk

Docs: Sandboxes · Connecting your account (token, config, balance) · OpenAPI

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

await Sandbox.with({ tariff: "small" }, async (sb) => {   // EQVPS_API_KEY from the environment
  const r = await sb.run("print(2 + 2)");
  console.log(r.stdout, r.exit_code);                    // "4\n" 0
  await sb.upload("/root/data.csv", "a,b\n1,2\n");
  console.log((await sb.exec("wc -l /root/data.csv")).stdout);
});                                                       // deleted afterwards, also on errors

// TS 5.2+:  await using sb = await Sandbox.create();

API key

Any EQVPS account Bearer token (POST https://api.eqvps.com/api/v1/eqvps/auth/register, the MCP register_account tool, or the dashboard). Pass { apiKey } or set EQVPS_API_KEY.

Modes and prices

ephemeral (default): per second, min 60 s, auto-deleted after idleTimeout (default 300 s), ttl ≤ 24 h. persistent: per started hour, a month costs at most 730 h −25 %, ttl ≤ 30 days; if the balance runs out it is paused (snapshot, not billed) and resumes after a top-up — snapshots are kept 14 days. | tariff | vCPU | RAM | disk | $/hour | persistent month max | |---|---|---|---|---|---| | micro | 0.25 | 512 MB | 3 GB | $0.0165 | $9.03 | | small | 0.5 | 1 GB | 5 GB | $0.033 | $18.07 | | standard | 1 | 2 GB | 10 GB | $0.066 | $36.14 | | plus | 2 | 4 GB | 15 GB | $0.132 | $72.27 | | pro | 4 | 8 GB | 20 GB | $0.264 | $144.54 | | max | 8 | 16 GB | 40 GB | $0.528 | $289.08 |

Rates: vCPU $0.040/h + RAM $0.013/GiB-h. Live: tariffs(). Heavy installs (torch) and builds: plus or bigger. If the host is busy, creating a big tariff raises CapacityError (503, retry_after).

API

• Sandbox.create({ mode, tariff, idleTimeout, ttl, apiKey?, baseUrl? }) · Sandbox.connect(id) · Sandbox.list() · Sandbox.with(opts, fn) · tariffs()
• sb.run(code, { language: "python" | "node" | "bash", timeout }) → ExecResult { exit_code, stdout, stderr, timed_out, truncated, duration_ms, ok }
• sb.exec("cmd" | ["argv"], { cwd, stdin, timeout }) · sb.upload(path, string | Uint8Array) · sb.download(path) · sb.downloadText(path)
• sb.usage() · sb.refresh() · sb.kill()

Limits: command timeout ≤ 55 s per call (background long jobs and poll), files ≤ 5 MB per transfer, output ≤ 1 MiB per stream, 2 concurrent commands per account.

Long jobs — background tasks (no 55 s limit)

const task = await sb.exec("python3 train.py", { background: true });   // returns at once
const res = await task.wait({ onOutput: (out) => process.stdout.write(out), pollIntervalMs: 5000 });
console.log(res.state, res.exit_code);                                 // done 0 (failed | killed | timeout)
const { stdout } = await task.logs();   // only new output since the last call
await task.kill();

Runs until the sandbox's maximum lifetime (or timeout), keeps the sandbox from idle-deletion, billed like any running time.

Environment variables

const sb = await Sandbox.create({ env: { OPENAI_API_KEY: "sk-...", MODE: "prod" } });  // every command in this sandbox
console.log(sb.envKeys);                                // ["OPENAI_API_KEY", "MODE"] — values are never returned
await sb.run("console.log(process.env.MODE)", { language: "node" });
await sb.exec("echo $REGION", { env: { REGION: "eu" } }); // this call only, overrides create()

Values are stored encrypted and never logged. Up to 64 variables, 64 KB in total.

Spending limit

Set a daily/monthly cap for sandboxes in the dashboard (Sandboxes → Spending limit, UTC). When it is reached, Sandbox.create() throws BudgetExceededError (extends RateLimitError), running ephemeral sandboxes are deleted and persistent ones are paused (disk kept) until the limit resets or you raise it. The limit can also be set via the REST API: PUT /sandboxes/budget.

Errors

EqvpsError { status, code, message, retryAfter } and subclasses: AuthenticationError 401, InsufficientBalanceError 402, NotFoundError 404, SandboxPausedError 409, SandboxDeletedError 410, FileTooLargeError 413, ValidationError 422, RateLimitError 429 (BudgetExceededError when the spending limit is reached), CapacityError 503, SandboxTimeoutError. 429/503 with Retry-After are retried automatically (maxRetries: 3). A non-zero exit code is not an exception.

REST API reference: https://eqvps.com/openapi.json (tag sandboxes) · human guide: https://eqvps.com/en/docs/sandboxes

Changelog

• 0.2.0 — environment variables: env in create(), run() and exec() (values stored encrypted, only names come back as envKeys); BudgetExceededError (HTTP 429 budget_exceeded) when your sandbox spending limit is reached.
• 0.1.0 — first release: create / run / exec / files / background tasks / kill.