Skip to main content
The Nullspace TypeScript SDK (@nullspace/sdk) gives you on-demand Linux sandboxes from Node or the browser. Its public surface mirrors the Python SDK camelCased — same resource names, same namespacing, same error semantics — so one mental model teaches both languages.

​
Install

npm install @nullspace/sdk@<version>
Requires Node 18+. WebSocket-backed surfaces (PTY, exec streaming, lifecycle events) need a global WebSocket, which Node 22+ and all browsers provide.

​
Configure

Authentication resolves from explicit options first, then the environment:
  • NULLSPACE_API_KEY — required API key.
  • NULLSPACE_API_URL (alias NULLSPACE_BASE_URL) — base URL.
import { NullspaceClient } from "@nullspace/sdk";

const client = new NullspaceClient({ apiKey: "ns_live_..." });

​
Quickstart

Create → exec → file → destroy, in under 10 lines: 
import { Sandbox } from "@nullspace/sdk";

await using sandbox = await Sandbox.create();

const result = await sandbox.commands.run("echo 'Hello!'", { shell: true });
console.log(result.stdout);

await sandbox.files.write("/hello.txt", "world");
console.log(await sandbox.files.read("/hello.txt"));
// `await using` destroys the sandbox when the scope exits.

​
Resources

A Sandbox exposes namespaced resources, mirroring Python:
  • sandbox.commands — run (with onStdout / onStderr streaming), list, kill, sendStdin, getLogs.
  • sandbox.files — read, write, list, exists, info, makeDir, remove, rename, upload / download with progress callbacks.
  • sandbox.pty — open() returns a handle (send input, resize, async-iterate output, wait(), kill()).
  • sandbox.code — run() streams Jupyter-style execution events over SSE.
  • sandbox.lifecycle — list() history and subscribe() live events.
Lifecycle and advanced primitives live on the sandbox or client: 
const child = await sandbox.fork();            // copy-on-write fork
const snap = await sandbox.createSnapshot();   // durable snapshot
const resumed = await client.snapshots.resume(snap.id);
const preview = await sandbox.createSignedPreviewUrl(8080);

const vol = await client.volumes.create("data");
await sandbox.attachVolume(vol.id, "/data");

const template = await client.templates
  .builder()
  .fromUbuntuImage("22.04")
  .aptInstall(["curl"])
  .build({ name: "my-template" });

​
Errors

Every failure is a typed subclass of SandboxError with a stable code, matching the Python hierarchy: NotFoundError, AuthError, ConflictError, QuotaExceededError, RateLimitError, TimeoutError, BuildError, FileUploadError, and more. 
import { NotFoundError } from "@nullspace/sdk";

try {
  await client.sandboxes.get("sb_missing");
} catch (err) {
  if (err instanceof NotFoundError) {
    // ...
  }
}

​
Browser support

The REST and SSE core works in browsers; WebSocket (PTY, exec streaming, lifecycle) and filesystem-path helpers are Node-first. WebSocket routes authenticate with the nullspace-api-key subprotocol so browsers work without setting headers. See the package README for the full support matrix.

​
Not included

The MCP server and CLI remain Python-owned (nullspace-sdk[cli,mcp]). Some advanced REST domains the Python SDK exposes are not yet wrapped in the TypeScript surface; the per-operation coverage manifest lives in specs/client-surfaces/typescript-sdk.yaml.