@space-vm/sdk

TypeScript SDK for the Space sandbox API — run code in isolated cloud VMs.

Installation

npm install @space-vm/sdk
# or
bun add @space-vm/sdk
# or
pnpm add @space-vm/sdk

Zero runtime dependencies. Requires Node.js >= 18 or any modern browser/runtime with fetch.

Quick Start

import { Sandbox } from "@space-vm/sdk"

// Sandbox is ready to use when create() returns.
const sandbox = await Sandbox.create({ name: "my-sandbox" })

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

await sandbox.files.write("/app/data.txt", "content")
const text = await sandbox.files.readText("/app/data.txt")

await sandbox.kill()

Authentication

Set the SPACE_API_KEY environment variable:

export SPACE_API_KEY=sp_live_...

Or pass it explicitly:

const sandbox = await Sandbox.create({
  name: "my-sandbox",
  apiKey: "sp_live_...",
  baseUrl: "https://api.spce.me", // optional
})

Listing sandboxes

import { Sandbox } from "@space-vm/sdk"

const sandboxes = await Sandbox.list()
for (const s of sandboxes) {
  console.log(`${s.id} — ${s.name} (${s.status})`)
}

Streaming command output

const result = await sandbox.commands.run("npm install", {
  onStdout: (data) => process.stdout.write(data),
  onStderr: (data) => process.stderr.write(data),
  timeoutMs: 120_000,
})

Cancellation

Every network operation accepts an AbortSignal:

const controller = new AbortController()
setTimeout(() => controller.abort(), 5000)

await sandbox.commands.run("sleep 100", { signal: controller.signal })

Error handling

import {
  SandboxError,
  AuthenticationError, // 401
  ValidationError, // 400
  NotFoundError, // 404
  ConflictError, // 409 — invalid state for operation
  TimeoutError, // request timed out
  ServerError, // 500
} from "@space-vm/sdk"

try {
  await sandbox.pause()
} catch (err) {
  if (err instanceof ConflictError) {
    // Sandbox is not in a pausable state
  }
}

Full documentation

docs.spce.me

Development

# From repo root:
cd packages/sdk
bun run build
bun run typecheck

License

Apache License 2.0.