@enclave-run/sdk

JavaScript/TypeScript SDK for Enclave — secure, isolated cloud sandboxes for AI agents and AI apps.

A sandbox is a persistent Linux VM your code can treat as a remote execution target: run shell commands, read and write files, start long-running processes, forward ports, or build templates. Sandboxes start in ~150 ms and hibernate to disk on timeout.

Install

npm install @enclave-run/sdk

Set your API key:

export ENCLAVE_API_KEY=enclave_...

Get one from app.enclave.run.

Quick start

import { Sandbox } from "@enclave-run/sdk";

const sandbox = await Sandbox.create();

const result = await sandbox.commands.run("echo hello");
console.log(result.stdout); // "hello\n"

await sandbox.files.write("/tmp/note.txt", "persisted");
const contents = await sandbox.files.read("/tmp/note.txt");

await sandbox.kill();

Core surface

| Area | API | | ---------- | ----------------------------------------------------------------------------------------- | | Lifecycle | Sandbox.create, Sandbox.inRegion, sandbox.connect, sandbox.pause, sandbox.kill | | Filesystem | sandbox.files.{read, write, list, exists, remove, makeDir, watch} | | Commands | sandbox.commands.{run, start, list, kill, sendStdin} | | PTY | sandbox.pty.{create, sendInput, resize} | | Snapshots | Sandbox.createSnapshot, Sandbox.list | | Templates | Template().fromImage(...).copy(...), Template.build, Template.exists |

Runtimes

Node.js 20+, Bun, and Deno are supported. The SDK has no Node-specific runtime dependencies in its hot path; platform-specific features (like reading files from disk during a template build) use node:fs behind a dynamic import.

Sandbox region and ownership

The SDK uses the launched default region (yyz) unless you choose another supported region. It sends create directly to that regional API and keeps the authoritative API base on the sandbox handle, so pause, resume, timeout, snapshot, and kill never take a hidden global round trip.

const sandbox = await Sandbox.create("base", { region: "yyz" });
console.log(sandbox.sandboxRegion); // "yyz"

For several operations in one region, create an immutable regional scope once:

const yyz = Sandbox.inRegion("yyz");

const sandbox = await yyz.create("base");
const sameSandbox = await yyz.connect(sandbox.sandboxId);
await yyz.pause(sandbox.sandboxId);

Persist sandbox.ref when a later process needs to reconnect without relying on a configured default:

await save(sandbox.ref); // { sandboxId: "sbx-...", region: "yyz" }
const sameSandbox = await Sandbox.connect(await load());

You can override the client default once with ENCLAVE_REGION=yyz. Static lifecycle helpers can take region; an instance returned by create or connect already carries its owner. A saved reference is authoritative; a conflicting regional scope or explicit option fails locally. SDK releases from before the regional default continue through the bounded global compatibility endpoint.

Every logical create has an idempotency key (generated by the SDK unless you provide one). A timeout or lost response raises OutcomeUnknownError with the same-region recovery URL. Only an explicit pre-admission capacity rejection can be considered for another region; a transport timeout must never be retried elsewhere.

Recover without rebuilding or resending the original create request:

try {
  return await Sandbox.create("base", { idempotencyKey: "job-123" })
} catch (error) {
  if (error instanceof OutcomeUnknownError) {
    return Sandbox.recoverCreate(error.recovery)
  }
  throw error
}

The chosen region is also part of the sandbox host:

sbx-{id}-{port}.{region}.onenclave.com

Env vars

| Variable | Purpose | Default | | ---------------------- | -------------------------------------- | --------------- | | ENCLAVE_API_KEY | API authentication | — | | ENCLAVE_DOMAIN | API/sandbox apex | onenclave.com | | ENCLAVE_API_URL | Override API URL | — | | ENCLAVE_REGION | Regional API used for create/lifecycle | yyz | | ENCLAVE_ACCESS_TOKEN | Alternative auth (user tokens) | — | | ENCLAVE_DEBUG | Debug logging | false |

Docs

Full reference at enclave.run/docs. Source: github.com/enclave-run/docs.