Skip to main content

​
Overview

Templates define the base environment for sandboxes:
  • Operating system (Ubuntu, Debian, Alpine)
  • Runtimes (Node.js, Python, Go, Rust)
  • Pre-installed packages
  • Environment variables

​
System Templates

We provide pre-built templates for common use cases:
TemplateOSRuntimesPackagesSize
nodejs-20Ubuntu 22.04Node 20, Bunnpm, pnpm, tsx450MB
python-mlUbuntu 22.04Python 3.12PyTorch, NumPy, Pandas2.1GB
full-stackUbuntu 22.04Node 20, Python 3.12PostgreSQL, Redis1.2GB
go-1.22Ubuntu 22.04Go 1.22Common Go tools380MB
rust-1.75Alpine 3.19Rust 1.75Cargo520MB

​
Desktop Templates

For Computer Use (GUI interaction), use a desktop-enabled template:
TemplateDescriptionSize
ubuntu-desktopUbuntu 24.04 + XFCE, Chrome, Firefox2.8GB
desktop-devDesktop + VS Code, Node.js, Python3.5GB
desktop-browserMinimal desktop with Chrome only1.9GB

​
Template Builder UI

Create templates visually in the dashboard:
  • Select base OS — Ubuntu, Debian, or Alpine
  • Add runtimes — Node.js, Python, Go, Rust with version selection
  • Install packages — Search and add apt, npm, pip packages
  • Preview Dockerfile — See the generated Dockerfile before building
  • Validate — Check for conflicts and estimate image size

Template Builder

Open the template builder in your dashboard

​
Configuration File

Define custom templates in your templates/ directory with a Dockerfile:
templates/my-fullstack/Dockerfile
FROM ubuntu:24.04

# Install runtimes
RUN apt-get update && apt-get install -y \
    nodejs npm python3.12 python3-pip \
    postgresql-client redis-tools \
    && rm -rf /var/lib/apt/lists/*

# Install packages
RUN npm install -g typescript tsx
RUN pip install numpy pandas

ENV NODE_ENV=development
WORKDIR /workspace
Reference it in your agent:
agents/my-agent.ts
import { defineAgent } from '@runtools/sdk';

export default defineAgent({
  slug: 'my-agent',
  template: './templates/my-fullstack',  // Uses custom template
  // ...
});

​
Desktop Template

For Computer Use, use a desktop-enabled base image:
templates/my-desktop/Dockerfile
FROM runtools/desktop:ubuntu-24.04

# Desktop base includes X11, window manager, VNC
RUN apt-get update && apt-get install -y \
    chromium-browser firefox \
    && rm -rf /var/lib/apt/lists/*

# Add your runtimes
RUN apt-get update && apt-get install -y nodejs npm
Desktop templates are larger and take longer to boot. Only enable if you need GUI interaction.

​
Deploying

Build and deploy with a single command: 
runtools deploy
This validates your config, builds the template, and makes it available for sandboxes.

​
Using SDK to Create Templates

You can also create templates programmatically via the SDK: 
const template = await rt.templates.create({
  slug: 'my-custom',
  os: 'ubuntu-24.04',
  runtimes: [
    { name: 'node', version: '22' },
    { name: 'python', version: '3.12' },
  ],
  apt: ['curl', 'wget', 'git'],
  npm: ['typescript', 'tsx'],
  pip: ['torch', 'numpy', 'pandas'],
});
Then deploy: 
runtools deploy

​
Auto-Deploy from Git

Connect your repo to auto-deploy on push: 
runtools link --repo github.com/myorg/myrepo
Or configure in the dashboard under Settings → Git Integration. Pushes to your default branch trigger automatic deploys.

​
CLI Commands

# Deploy (build + publish)
runtools deploy

# Preview what will be built
runtools deploy --dry-run

# List your templates
runtools template list

# Check deploy status
runtools status

# View build logs
runtools logs --follow

​
Template Marketplace

Share templates publicly: 
// Publish to marketplace
await template.publish({
  description: 'Full stack environment with Node, Python, and databases',
  tags: ['nodejs', 'python', 'postgresql'],
});

// Browse marketplace
const templates = await rt.templates.marketplace();

​
Using Templates

Once a template is ready, use it for sandboxes: 
// Create sandbox from template
const sandbox = await rt.sandboxes.create({
  template: 'my-fullstack',
});

// Or assign to agent deployment
const deployment = await rt.deployments.create({
  runtimeSlug: 'code-assistant',
  templateSlug: 'my-fullstack',
  apiSlug: 'my-bot',
});

​
Best Practices

Smaller templates = faster startup. Only include what you need.
Pin package versions for reproducibility. node@20 not node@latest.
Use rt.templates.validate() to catch issues before waiting for a build.
Our system templates are optimized. Only create custom if needed.