@nodeops-createos/sandbox SDK

The TypeScript SDK for createos-sandbox — spawn VM sandboxes, run commands, move files, expose services, and orchestrate fleets, from one hand-written fetch client with zero runtime dependencies.

TypeScript
1import { CreateosSandboxClient } from "@nodeops-createos/sandbox";
2
3const client = new CreateosSandboxClient();
4const sandbox = await client.createSandbox({ shape: "s-4vcpu-4gb", rootfs: "devbox:1" });
5try {
6  const out = await sandbox.runCommand("echo", ["hello from a VM"]);
7  console.log(out.result.stdout);
8} finally {
9  await sandbox.destroy();
10}

A sandbox is a real virtual machine — its own Linux kernel, hardware-level isolation — that boots in seconds. That makes it safe to run untrusted or AI-generated code, stand up a dev server, branch a filesystem, or fan a batch job across a fleet. The SDK runs on Node 20+, Bun, Deno, Cloudflare Workers, Vercel Edge, and the browser.

At a glance

Package: @nodeops-createos/sandbox (npm)
Import: import { createClient } from "@nodeops-createos/sandbox"
Base URL: https://api.sb.createos.sh — override with CREATEOS_SANDBOX_BASE_URL
Auth: API key via the apiKey option or CREATEOS_SANDBOX_API_KEY

What you can build

Run AI-generated code safely — an agent writes code, a VM runs it, you read back the result.
Expose a live service — start a server inside the sandbox and reach it at a per-sandbox preview URL.
Branch and snapshot — pause, fork, and resume a sandbox to explore multiple paths from one state.
Persist and share data — attach S3-backed disks and private networks across sandboxes.

Find your way around

These docs follow the Diátaxis framework — four kinds of documentation for four kinds of need.

If you want to…	Go to
Learn by building something end to end	Tutorial — build an AI app generator
Get going in 30 seconds	Quickstart
Solve a specific problem	How-to guides — files, lifecycle, services, disks, streaming, errors, observability
Look up a method or type	API reference — client, sandbox, sub-APIs, errors, types, helpers
Understand how it works	Explanation — VMs, the handle model, lifecycle, reliability
Copy a working program	Examples — runnable, one per directory

Start here

New to the SDK? Read the Quickstart, then the Tutorial.
New to VM sandboxes? Read What is a VM sandbox?
Building an agent? Jump to the Tutorial and the examples.

For AI agents

This documentation is published for machine consumption too, following the llmstxt.org convention.

Key facts

Zero runtime dependencies, ESM-only. A hand-written fetch client.
Typed errors + automatic retries. Idempotent requests retry on transient failures with backoff and jitter; see reliability.
Sandboxes bill while running. Every example here tears down with try / finally; set an idle auto-pause for safety.
Install: npm install @nodeops-createos/sandbox or bun add @nodeops-createos/sandbox.