Skip to main content

​
Overview

Sandboxes are the foundation of RunTools. Each sandbox is an isolated Firecracker microVM that provides:
  • Full Linux environment with root access
  • Hardware-level isolation via KVM (not containers)
  • Network access with public dev server URLs
  • Pause/Resume with sub-second snapshot restore
  • SSH access via ssh sandbox-id@ssh.runtools.ai
  • Desktop environment (optional) with XFCE4 + VNC

​
Creating a Sandbox

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

​
Templates

TemplateDescriptionSize
base-ubuntuCLI environment — Bun, Node.js, common dev tools~400MB
desktop-ubuntuFull XFCE4 desktop + KasmVNC + Firefox ESR + Plank dock~1GB
Custom templates (Dockerfile-based) are planned but not yet available. If you need a specialized environment, use base-ubuntu and install packages via sandbox.exec() or SSH.

​
Executing Commands

const result = await sandbox.exec('ls -la');
console.log(result.stdout);
console.log(result.exitCode);

​
Dev Server URLs

Every sandbox gets public URLs for any port via Caddy reverse proxy: 
https://{port}-{sandboxId}.sandboxes.runtools.ai
For example, if your sandbox runs a dev server on port 3000: 
https://3000-sandbox-abc123.sandboxes.runtools.ai
Default ports (3000, 3001, 5173, 8000, 8080) are automatically proxied. Host headers are rewritten to localhost for Vite/Next.js compatibility.

​
Pause and Resume

Save money by pausing sandboxes when not in use: 
# Pause — snapshots entire VM state to disk
runtools sandbox pause my-env

# Resume — restores in under 1 second
runtools sandbox resume my-env

​
Auto-Pause (Idle Timeout)

Sandboxes auto-pause after 10 minutes of inactivity (configurable). Activity is detected from:
  • Command execution
  • SSH connections
  • VNC connections
  • Dev server traffic
  • CPU usage above 5%
# Create with custom idle timeout (seconds, 0 = disabled)
runtools sandbox create --template base-ubuntu --idle-timeout 1800

​
SSH Access

Register your SSH key once, then access any sandbox: 
# One-time setup: register your SSH key
runtools ssh-key add my-laptop

# SSH into any sandbox
ssh sandbox-abc123@ssh.runtools.ai

# Or via CLI (auto-selects key)
runtools sandbox ssh my-env
Password auth is also supported: 
runtools sandbox create --password mypass123
ssh sandbox-xxx@ssh.runtools.ai  # prompts for password

​
Desktop / VNC Access

Desktop sandboxes (desktop-ubuntu template) include a full XFCE4 desktop accessible via VNC in your browser: 
https://6901-{sandboxId}.sandboxes.runtools.ai
The desktop includes:
  • XFCE4 with Orchis Dark theme
  • Firefox ESR
  • Plank dock (macOS-style)
  • KasmVNC web client (no VNC client needed)
  • xdotool, scrot, imagemagick for computer-use agents

​
Real-Time Monitoring

The SDK provides real-time status and metrics via Convex WebSocket: 
sandbox.on('status', (state) => {
  console.log(`Status: ${state.status}`);
  console.log(`SSH Ready: ${state.sshReady}`);
  console.log(`VNC Ready: ${state.vncReady}`);
});

sandbox.on('metrics', (m) => {
  console.log(`CPU: ${m.cpuPercent}%`);
  console.log(`MEM: ${m.memPercent}%`);
  console.log(`NET: ${m.netRxBytesPerSec} bytes/s`);
});
Or via CLI: 
runtools sandbox watch my-env

​
Snapshots

Create named snapshots and rollback: 
# Create a snapshot
runtools sandbox snapshot my-env

# Rollback to snapshot
runtools sandbox rollback my-env

​
Lifecycle

StateDescription
creatingVM is booting (~5 seconds cold start)
runningReady for commands, SSH, VNC
pausedState saved to disk, zero compute cost
stoppedTerminated and cleaned up

​
Resource Configuration

ResourceDefaultConfigurable
vCPUs2Yes (--vcpus)
Memory1 GB (CLI), 2 GB (desktop)Yes (--memory)
Disk2 GB sparse overlayFixed per-VM
NetworkFull internet + VPCAutomatic
runtools sandbox create --template base-ubuntu --vcpus 4 --memory 4096

​
Best Practices

The default 10-minute idle timeout auto-pauses inactive sandboxes. Resume takes under 1 second.
Each team member should register their SSH key once. Then they can access any sandbox without passwords.
Need a browser, GUI app, or computer-use agent? Use desktop-ubuntu instead of trying to run GUI apps in base-ubuntu.
Even paused sandboxes consume disk space for their snapshots. Destroy them when you’re done.