Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runtools.ai/llms.txt

Use this file to discover all available pages before exploring further.

Create

const sandbox = await rt.sandbox.create({
  name: 'dev-env',
  template: 'base-ubuntu',
  tags: ['docs'],
  resources: { vcpus: 1, memory: '1GB', disk: '10GB' },
  env: { NODE_ENV: 'development' },
  idleTimeout: 600,
  mounts: [{ workspaceId: '9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e', path: '/workspace' }],
});

await sandbox.waitForReady();

SandboxCreateOptions

FieldTypeDescription
namestringFriendly name
templatestringDefaults to base-ubuntu
tagsstring[]Filter and deploy tracking tags
sshKeysstring[]SSH key IDs to inject
rootPasswordstringOptional password access
resources{ vcpus?, memory?, disk? }Resource request
envRecord<string,string>Environment variables
idleTimeoutnumberIdle timeout in seconds
mounts{ workspaceId, path }[]Workspace mounts under /workspace
Workspace mount paths must be /workspace or a subpath under /workspace. When an agent uses this sandbox, the mounted workspace is persistent filesystem state the agent can carry across runs.

List

const all = await rt.sandbox.list();
const running = await rt.sandbox.list({ status: 'running', limit: 20 });

const page = await rt.sandbox.listPage({
  status: 'running',
  limit: 20,
});
Filters include status, tags, template, exclude_template, limit, cursor, and admin-only all.

Get an Instance

const sandbox = rt.sandbox.get('sandbox-abc123');
get() returns a local Sandbox object. It does not fetch immediately; methods and subscriptions use the API.

Execute

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

console.log(result.exitCode);
console.log(result.stdout);
console.log(result.stderr);

Lifecycle

await sandbox.pause();
await sandbox.resume();
await sandbox.destroy();

await rt.sandbox.destroy('sandbox-abc123');

Wait and Subscribe

await sandbox.waitForReady(120000);

const offStatus = sandbox.on('status', (state) => {
  console.log(state.status, state.sshReady, state.vncReady);
});

const offMetrics = sandbox.on('metrics', (metrics) => {
  console.log(metrics.cpuPercent, metrics.memUsedPercent);
});

offStatus();
offMetrics();
await sandbox.close();

Accessors

PropertyDescription
sandbox.idSandbox ID
sandbox.statusCurrent known status or unknown
sandbox.sshReadyCurrent known SSH readiness
sandbox.vncReadyCurrent known VNC readiness
sandbox.vncUrlNormalized desktop URL when available
sandbox.stateLast full state payload or null
sandbox.metricsLast metrics payload or null

Not In The SDK

Named checkpoint and restore operations are not public SDK methods. Use pause/resume for lifecycle preservation.