@ravon/sandbox-sdk

TypeScript SDK for Ravon Sandbox Platform - MicroVM-based isolated code execution.

Installation

bun add @ravon/sandbox-sdk
# or
npm install @ravon/sandbox-sdk

Quick Start

import { SandboxClient } from "@ravon/sandbox-sdk";

const client = new SandboxClient({
  baseUrl: "http://localhost:8080",
  apiKey: "your-api-key",
});

// Create a sandbox
const sandbox = await client.createSandbox({
  template: "python",
  vcpu_count: 1,
  memory_mb: 256,
});

// Execute code
const result = await client.execute(sandbox.id, {
  language: "python",
  code: 'print("Hello from the sandbox!")',
});

console.log(result.stdout); // "Hello from the sandbox!"

// Clean up
await client.deleteSandbox(sandbox.id);

Features

Sandbox Management

// Create with custom configuration
const sandbox = await client.createSandbox({
  template: "python", // or "node", "base"
  vcpu_count: 2,
  memory_mb: 512,
  timeout_seconds: 3600,
  env_vars: { DEBUG: "true" },
  network: {
    outbound: {
      allow_internet: true,
      allowed_domains: ["*.github.com", "api.example.com"],
    },
    inbound: {
      ssh_enabled: true,
      http_enabled: true,
    },
  },
  workspace_id: "existing-workspace-id", // restore from S3
});

// List all sandboxes
const sandboxes = await client.listSandboxes();

// Get sandbox details
const details = await client.getSandbox(sandbox.id);

// Delete sandbox
await client.deleteSandbox(sandbox.id, { delete_workspace: false });

Code Execution

// Synchronous execution
const result = await client.execute(sandbox.id, {
  language: "python", // python, javascript, bash, etc.
  code: 'print("Hello!")',
  files: { "data.json": '{"key": "value"}' },
  stdin: "input data",
  timeout_ms: 30000,
  packages: ["requests", "pandas"], // auto-installed
});

console.log(result.stdout);
console.log(result.stderr);
console.log(result.exit_code);
console.log(result.duration_ms);

// Streaming execution (SSE)
for await (const event of client.executeStream(sandbox.id, {
  language: "python",
  code: 'for i in range(5): print(i)',
})) {
  switch (event.type) {
    case "started":
      console.log("Execution started");
      break;
    case "stdout":
      process.stdout.write(event.data!);
      break;
    case "stderr":
      process.stderr.write(event.data!);
      break;
    case "done":
      console.log(`Finished with exit code ${event.exit_code}`);
      break;
    case "error":
      console.error(event.error);
      break;
  }
}

File Operations

// List files
const files = await client.listFiles(sandbox.id, "/workspace");

// Read file
const content = await client.readFile(sandbox.id, "/workspace/app.py");

// Write file
await client.writeFile(sandbox.id, {
  path: "/workspace/script.py",
  content: 'print("Hello")',
});

// Create directory
await client.mkdir(sandbox.id, "/workspace/src");

// Delete file
await client.deleteFile(sandbox.id, "/workspace/old-file.txt");

// Upload binary file
const file = new Blob(["binary content"]);
await client.uploadFile(sandbox.id, "/workspace", file, "data.bin");

// Download file
const buffer = await client.downloadFile(sandbox.id, "/workspace/output.zip");

Port Exposure (Preview URLs)

// Expose a port
const port = await client.exposePort(sandbox.id, {
  port: 8080,
  name: "web-server",
});
console.log(port.url); // https://8080.{sandbox-id}.ravon.cloud

// List exposed ports
const ports = await client.listPorts(sandbox.id);

// Remove exposed port
await client.unexposePort(sandbox.id, 8080);

Background Tasks

// Start a background task
const task = await client.createTask(sandbox.id, {
  language: "python",
  code: "import time; time.sleep(60); print('Done!')",
  timeout_ms: 120000,
});

// List tasks
const tasks = await client.listTasks(sandbox.id);

// Get task status
const status = await client.getTask(sandbox.id, task.task_id);

// Wait for task completion
const completed = await client.waitForTask(sandbox.id, task.task_id, {
  pollInterval: 1000,
  timeout: 300000,
});

// Cancel a running task
await client.cancelTask(sandbox.id, task.task_id);

Workspace Persistence

// Get workspace info
const workspace = await client.getWorkspace(sandbox.id);
console.log(workspace.local_size_bytes);
console.log(workspace.synced_to_cloud);

// Manually flush workspace to S3
await client.flushWorkspace(sandbox.id);

HTTP Proxy

// Proxy requests to sandbox
const response = await client.proxy(sandbox.id, "/api/data", {
  method: "POST",
  body: JSON.stringify({ key: "value" }),
});

WebSocket Terminal

// Get WebSocket URL for terminal access
const wsUrl = client.getTerminalWebSocketUrl(sandbox.id);
// Use with xterm.js or similar terminal emulator

Stats & Health

// Check server health
const healthy = await client.health();

// Get server statistics
const stats = await client.stats();
console.log(stats.active_sandboxes);
console.log(stats.cpu_usage_percent);
console.log(stats.resource_limits);

// Get available templates
const templates = await client.templates();

Error Handling

import { SandboxClient, SandboxClientError } from "@ravon/sandbox-sdk";

try {
  await client.getSandbox("invalid-id");
} catch (error) {
  if (error instanceof SandboxClientError) {
    console.error(`Error ${error.statusCode}: ${error.message}`);
    console.error("Response:", error.response);
  }
}

Types

All types are exported from the package:

import type {
  Sandbox,
  SandboxState,
  CreateSandboxOptions,
  ExecuteOptions,
  ExecuteResult,
  SSEEvent,
  FileInfo,
  Task,
  TaskStatus,
  Stats,
  // ... and more
} from "@ravon/sandbox-sdk";

Configuration

const client = new SandboxClient({
  baseUrl: "https://api.ravon.cloud", // API server URL
  apiKey: "sk-xxx", // Your API key
  timeout: 30000, // Default request timeout in ms
});

Environment Variables

For testing, you can configure:

SANDBOX_API_URL=http://localhost:8080
SANDBOX_API_KEY=your-api-key

Running Tests

bun test

License

MIT