Sandboxes SDK

import { RunTools } from '@runtools/sdk';

const rt = new RunTools({ apiKey: process.env.RUNTOOLS_API_KEY });

// Create with default template (base-ubuntu)
const sandbox = await rt.sandbox.create();

// Create with options
const sandbox = await rt.sandbox.create({
  template: 'desktop-ubuntu',
  name: 'my-dev-env',
  sshKeys: ['ssh-ed25519 AAAA... user@laptop'],
  idleTimeoutSeconds: 1800,
  vcpus: 4,
  memoryMb: 4096,
  tags: { project: 'my-app' },
  env: { NODE_ENV: 'development' },
});

// List all sandboxes
const sandboxes = await rt.sandbox.list();

// Filter by status
const running = await rt.sandbox.list({ status: 'running' });

// Each item: { id, name?, status, template?, tags?, createdAt }

// Destroy by ID (manager method)
await rt.sandbox.destroy('sandbox-abc123');

const sandbox = await rt.sandbox.create({ template: 'base-ubuntu' });

// Wait until SSH (and VNC for desktop) is ready
await sandbox.waitForReady();       // Default 60s timeout
await sandbox.waitForReady(120000); // Custom timeout (ms)

const result = await sandbox.exec('ls -la');
console.log(result.stdout);    // Directory listing
console.log(result.stderr);    // Error output
console.log(result.exitCode);  // 0 = success

// With options
const result = await sandbox.exec('npm install', {
  timeout: 120000,  // 2 minutes
  cwd: '/workspace',
  env: { CI: 'true' },
});

await sandbox.pause();   // Snapshot VM state to disk
await sandbox.resume();  // Restore from snapshot (~500ms)

await sandbox.destroy(); // Closes subscriptions + deletes sandbox

await sandbox.close(); // Closes Convex subscriptions only (sandbox keeps running)

// Status changes (running, paused, stopped, etc.)
sandbox.on('status', (state: SandboxState) => {
  console.log('Status:', state.status);
  console.log('SSH Ready:', state.sshReady);
  console.log('VNC Ready:', state.vncReady);
  console.log('Template:', state.template);
});

// Live metrics (~1 update/second)
sandbox.on('metrics', (m: SandboxMetrics) => {
  console.log('CPU:', m.cpuPercent, '%');
  console.log('Memory:', m.memUsedPercent, '%');
  console.log('Net RX:', m.netRxBytesPerSec, 'bytes/s');
  console.log('Disk Read:', m.diskReadBytesPerSec, 'bytes/s');
});

// Fires once when SSH becomes ready
sandbox.on('ready', () => {
  console.log('Sandbox is ready!');
});

// Error events
sandbox.on('error', (err) => {
  console.error('Error:', err);
});

// Subscription closed
sandbox.on('close', () => {
  console.log('Subscriptions closed');
});

sandbox.id;        // Sandbox ID
sandbox.status;    // Current status string
sandbox.sshReady;  // boolean
sandbox.vncReady;  // boolean
sandbox.state;     // Full SandboxState object (or null)
sandbox.metrics;   // Full SandboxMetrics object (or null)

import type {
  Sandbox,
  SandboxManager,
  SandboxState,
  SandboxMetrics,
  SandboxCreateOptions,
  SandboxEventType,
  SandboxEvents,
} from '@runtools/sdk';