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.

​
Overview

Sandboxes are isolated cloud environments you can create from the API, CLI, SDK, or dashboard. They support command execution, SSH, protected dev server URLs, optional desktop access, project grouping, workspace mounts, and pause/resume lifecycle control.

​
Create a Sandbox

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

​
Templates

TemplateUse
base-ubuntuHeadless command-line development, package installs, test runs, build tasks
desktop-ubuntuBrowser desktop sessions and GUI-oriented automation

​
Command Execution

runtools sandbox exec my-env "npm test"

​
SSH

Register an SSH key once: 
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"

​
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' }],
});
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

​
Common Fields

FieldDescription
idSandbox ID, such as sandbox-abc123
nameOptional friendly name. Most CLI commands accept ID or name
templateTemplate slug
statuspending, creating, running, pausing, paused, resuming, destroying, destroyed, failed, error
tagsString tags for filtering and deploy tracking
projectIdOptional dashboard project grouping
mountsWorkspace mounts attached to the sandbox
sshReady / vncReadyReadiness flags for remote access

​
Best Practices

IDs are precise, but friendly names make repeated commands easier.
Sandbox-local files are removed when a sandbox is destroyed. Workspace mounts are the durable boundary.
Pause when you want to keep state for later. Destroy when the environment is no longer needed.