OpenSandbox SDK

Sandbox VMs with instant time-travel snapshots

Installation

npm install opensandbox

Or link locally during development:

# In the opensandbox repo
npm link

# In your project
npm link opensandbox

Quickstart

import { Client } from "opensandbox"

// Initialize with your API key
const client = new Client("ws_your_api_key")

// Create a sandbox VM
const result = await client.create("my-sandbox")
if (!result.success) throw new Error(result.error)

const { sandbox } = result

// Run commands (auto-snapshots after each)
const cmd = await sandbox.run("echo 'hello world'")
if (cmd.success) {
    console.log(cmd.stdout)     // "hello world\n"
    console.log(cmd.snapshot)   // "cmd_1702147200000"
}

// Time travel to any snapshot
const snaps = await sandbox.snapshots()
if (snaps.success) {
    await sandbox.restore(snaps.snapshots[0].snapshot_name)
}

// Cleanup
await sandbox.destroy()

Client

The main entry point. Manages sandbox VMs.

new Client(api_key, base_url?)

constructor(api_key: string, base_url?: string)

Create a new client.

api_key string Your API key

base_url string API URL (default: http://localhost:4000)

client.create(name)

async create(name: string): Promise<CreateResult>

Create a new sandbox VM.

name string Unique name for the sandbox

Returns: { success: true, sandbox } or { success: false, error }

client.list()

async list(): Promise<ListResult>

List all sandbox VMs.

Returns: { success: true, vms } or { success: false, error }

client.sandbox(name)

sandbox(name: string): Sandbox

Get a reference to an existing sandbox by name.

name string Name of existing sandbox

Sandbox

Represents a single VM instance. Run commands, manage snapshots, and time-travel.

sandbox.run(command, timeout?)

async run(command: string, timeout?: number): Promise<CommandResult>

Execute a shell command. A snapshot is automatically taken after each successful command.

command string Shell command to execute

timeout number Timeout in seconds (default: 30)

Returns: { success, stdout, stderr, exitCode, snapshot } or { success: false, error }

sandbox.snapshots()

async snapshots(): Promise<SnapshotsResult>

List all snapshots for this sandbox, ordered by creation time.

Returns: { success: true, snapshots } or { success: false, error }

sandbox.restore(snapshot_name)

async restore(snapshot_name: string): Promise<SimpleResult>

Restore workspace to a previous snapshot. All snapshots after this point are deleted.

snapshot_name string Name of snapshot to restore

sandbox.info()

async info(): Promise<VMInfoResult>

Get detailed information about the VM.

sandbox.wipe()

async wipe(): Promise<SimpleResult>

Clear all files in the workspace without creating a snapshot.

sandbox.destroy()

async destroy(): Promise<SimpleResult>

Delete the VM and all its snapshots permanently.

Types

All methods return discriminated unions for type-safe error handling.

CommandResult

Field	Type	Description
success	boolean	Whether command succeeded
stdout	string	Standard output (on success)
stderr	string	Standard error (on success)
exitCode	number	Exit code (on success)
snapshot	string	Snapshot name (on success)
error	string	Error message (on failure)

Snapshot

Field	Type	Description
id	number	Snapshot ID
vm_name	string	Parent VM name
snapshot_name	string	Unique snapshot identifier
command	string \| null	Command that created this snapshot
created_at	string	ISO timestamp

VMInfo

Field	Type	Description
id	number	VM ID
name	string	VM name
status	string	Current status (e.g. "running")
agent_port	number	Agent communication port
ssh_port	number	SSH port
agentHealthy	boolean	Whether agent is responding
created_at	string	ISO timestamp