Sandboxes

A sandbox is a real Linux machine in the cloud — your own microVM with root, up in seconds and yours to do anything with: run commands, SSH in, serve a dev URL behind a protected link, mount persistent storage, even a full browser desktop. Create one from the API, CLI, SDK, or dashboard; pause it when idle and it’s waiting right where you left off, no rebuild.

Create a sandbox

runtools sandbox create --name my-env --template base-ubuntu

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

await sandbox.waitForReady();

curl -X POST https://api.runtools.ai/v1/sandboxes \
  -H "X-API-Key: rt_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-env","template":"base-ubuntu"}'

Creation returns as soon as the control plane has accepted the sandbox and started either a warm-pool claim or a cold boot. Use runtools sandbox get, runtools sandbox watch, or await sandbox.waitForReady() when you need to wait for SSH readiness.

Templates

Template	Use
`base-ubuntu`	Headless command-line development, package installs, test runs, build tasks
`desktop-ubuntu`	Browser desktop sessions and GUI-oriented automation

Command Execution

Command execution wakes a paused sandbox when possible before dispatching the command.

runtools sandbox exec my-env "npm test"

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

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

curl -X POST https://api.runtools.ai/v1/sandboxes/sandbox-abc123/exec \
  -H "X-API-Key: rt_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"command":"npm test","cwd":"/workspace","timeout":120000}'

SSH

runtools ssh-key add my-laptop --file ~/.ssh/id_ed25519.pub

Then connect:

runtools sandbox ssh my-env

Password access is available for quick experiments:

runtools sandbox create --name password-demo --password "temporary-password"

Protected Dev URLs

Ask Runtools for a protected URL for any port:

runtools sandbox url my-env --port 3000 --open

The REST endpoint is:

curl "https://api.runtools.ai/v1/sandboxes/sandbox-abc123/url?port=3000" \
  -H "X-API-Key: rt_live_xxx"

Dev URL requests also wake a paused sandbox when possible. Desktop URLs normalize to the browser desktop route for desktop templates.

Workspace Mounts

Mount org workspaces under /workspace or a safe subpath:

runtools sandbox create \
  --name repo-env \
  --template base-ubuntu \
  --mount 9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e:/workspace

SDK:

await rt.sandbox.create({
  name: 'repo-env',
  template: 'base-ubuntu',
  mounts: [{ workspaceId: '9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e', path: '/workspace' }],
});

Only org workspaces can be mounted into sandboxes; Personal workspaces stay reserved for thread storage and personal cloud files. Mount targets must be /workspace or a safe subpath under /workspace. For agents linked to this sandbox, the mounted workspace is their persistent filesystem memory. Anything the agent writes under /workspace remains in the workspace for future runs and for new sandboxes that mount the same workspace. See Workspaces for workspace creation, file APIs, and the agent memory model.

Pause, Resume, Destroy

runtools sandbox pause my-env
runtools sandbox resume my-env
runtools sandbox destroy my-env --force

SDK:

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

Pause/resume preserves lifecycle state for an existing sandbox. Named checkpoint, restore, and clone APIs are not part of the current public surface.

Monitoring

The SDK subscribes to live state and metrics when you register listeners:

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

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

The CLI has a live view:

runtools sandbox watch my-env

Logs are available separately:

runtools sandbox logs my-env --tail 100

Common Fields

Field	Description
`id`	Sandbox ID, such as `sandbox-abc123`
`name`	Optional friendly name. Most CLI commands accept ID or name
`template`	Template slug
`status`	`pending`, `creating`, `running`, `pausing`, `paused`, `resuming`, `destroying`, `destroyed`, `stopped`, `failed`, `error`, `suspected_missing`, `orphaned`
`tags`	String tags for filtering and deploy tracking
`projectId`	Optional dashboard project grouping
`mounts`	Workspace mounts attached to the sandbox
`sshReady` / `vncReady`	Readiness flags for remote access

Sandbox lists are paginated. By default, list views show active lifecycle states rather than destroyed or orphaned history.

Best Practices

Use names for day-to-day CLI work

IDs are precise, but friendly names make repeated commands easier.

Mount persistent workspaces for important files

Sandbox-local files are removed when a sandbox is destroyed. Workspace mounts are the durable boundary.

Pause long-lived environments

Pause when you want to keep state for later. Destroy when the environment is no longer needed.

Getting Started

Platform

Core Features

Advanced

Create a sandbox

Templates

Command Execution

SSH

Protected Dev URLs

Workspace Mounts

Pause, Resume, Destroy

Monitoring

Common Fields

Best Practices

​Create a sandbox

​Templates

​Command Execution

​SSH

​Protected Dev URLs

​Workspace Mounts

​Pause, Resume, Destroy

​Monitoring

​Common Fields

​Best Practices

Create a sandbox

Templates

Command Execution

SSH

Protected Dev URLs

Workspace Mounts

Pause, Resume, Destroy

Monitoring

Common Fields

Best Practices