@ravon/sandbox-sdk

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

Installation

``bash
bun add @ravon/sandbox-sdk


or


npm install @ravon/sandbox-sdk
`

Quick Start

`typescript
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

$3

`typescript
// 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 });
`

$3

`typescript
// 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;
}
}
`

$3

`typescript
// 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");
`

$3

`typescript
// 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);
`

$3

`typescript
// 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);
`

$3

`typescript
// 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);
`

$3

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

$3

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

$3

`typescript
// 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

`typescript
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:

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

Configuration

`typescript
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:

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

Running Tests

`bash
bun test
``

License

MIT