Skip to content
sistemo.io beta
GitHub Docs Quickstart

Sandbox API (JavaScript / TypeScript)

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

Sandbox.create(options?)

Provisions a real microVM and resolves once it has booted.

const sb = await Sandbox.create({
  apiKey:        undefined,   // defaults to SISTEMO_API_KEY
  baseUrl:       undefined,   // defaults to SISTEMO_BASE_URL or https://api.sistemo.io
  timeoutMs:     120000,      // per-request timeout (create blocks until boot)
  name:          "",
  vcpus:         1,
  memoryMb:      1024,
  rootfsSizeGb:  10,
  stack:         "base",      // base | python | node | debian13 | ubuntu24.04
  metadata:      {},
});

Properties: sb.id (machine UUID), sb.state.

sb.run(script, timeoutSec = 30)

const r = await sb.run("ls -la /", 60);

Resolves to an ExecResult:

Field Type Meaning
exitCode number Process exit code (-1 if unknown)
stdout string Standard output
stderr string Standard error

timeoutSec defaults to 30 (server clamps to 120).

sb.close(preserveStorage = false)

await sb.close();                 // destroy disk too
await sb.close(true);             // keep the volume

Low-level Client (advanced)

import { Client } from "@sistemo/sdk";

const c = new Client();                       // reads env, or pass { apiKey, baseUrl }
const machines = await c.request("GET", "/v1/machines");

request<T>(method, path, body?) returns the parsed JSON. See the API reference for paths and shapes.

Types

The package ships .d.ts types — Sandbox, SandboxOptions, ExecResult, Client, ClientOptions, and the error classes are all typed.