Skip to main content

​
Overview

Templates define the base environment for sandboxes. Each template is a squashfs image that serves as the read-only lower layer, with a per-VM writable overlay on top.

​
Available Templates

TemplateDescriptionSizeIncludes
base-ubuntuCLI environment~400MBBun, Node.js, common dev tools, SSH server
desktop-ubuntuFull desktop environment~1GBXFCE4, KasmVNC, Firefox ESR, Plank dock, xdotool, scrot, imagemagick

​
Base Ubuntu (base-ubuntu)

The default template for headless/CLI workloads. Includes:
  • Bun runtime
  • Node.js
  • SSH server
  • Common dev tools (git, curl, wget, etc.)
  • RunTools runtime (agent execution engine)

​
Desktop Ubuntu (desktop-ubuntu)

Full GUI environment for browser automation, computer-use agents, and visual tasks:
  • Everything in base-ubuntu, plus:
  • XFCE4 desktop with Orchis Dark theme
  • KasmVNC (web-based VNC, no client needed)
  • Firefox ESR
  • Plank Reloaded dock (macOS-style)
  • xdotool, scrot, imagemagick (for computer-use)
  • Accessible via https://6901-{sandboxId}.sandboxes.runtools.ai

​
Using Templates

# Create with default template (base-ubuntu)
runtools sandbox create --name my-env

# Create with desktop template
runtools sandbox create --name my-desktop --template desktop-ubuntu

​
How Templates Work

Templates use an OverlayFS architecture: 
MERGED VIEW (what the VM sees)
  ├── LOWER (read-only): rootfs.squashfs (shared across ALL VMs)
  └── UPPER (read-write): {vmId}-overlay.ext4 (sparse 2GB, per-VM)
  • The base image (squashfs) is shared across all VMs of the same template type
  • Each VM gets its own sparse overlay that only stores changes
  • This means 10 VMs share one ~400MB base image, each adding only their modifications
  • The overlay starts at ~0 bytes and grows as files are modified

​
Custom Templates

Custom templates (Dockerfile-based) are planned but not yet available. The template build pipeline is not yet connected. For now, use base-ubuntu and install packages at runtime.

​
Workaround: Install at Runtime

Until custom templates are available, install packages after sandbox creation: 
# Create sandbox
runtools sandbox create --name ml-env --template base-ubuntu

# Install what you need
runtools sandbox exec ml-env "apt-get update && apt-get install -y python3-pip"
runtools sandbox exec ml-env "pip3 install torch numpy pandas"
Or in the SDK: 
const sandbox = await rt.sandbox.create({ template: 'base-ubuntu' });
await sandbox.waitForReady();
await sandbox.exec('apt-get update && apt-get install -y python3-pip');
await sandbox.exec('pip3 install torch numpy pandas');

​
Planned: defineSandbox()

The SDK provides a defineSandbox() helper for declarative sandbox definitions:
sandboxes/ml-env.ts
import { defineSandbox } from '@runtools/sdk';

export default defineSandbox({
  slug: 'ml-env',
  name: 'ML Environment',
  template: 'base-ubuntu',
  resources: { vcpus: 4, memoryMb: 4096 },
});
Deploy with runtools deploy --sandboxes-only. This creates the sandbox with the specified configuration but doesn’t install custom packages (that requires custom templates).

​
Best Practices

The base template has everything you need for CLI/headless tasks. It boots faster and uses less resources.
Desktop sandboxes use 2x memory and take slightly longer to boot. Only use for browser automation or visual tasks.
If you install packages at runtime, create a snapshot so you can resume without reinstalling.