Skip to main content

​
Architecture Overview

RunTools is built on three core primitives:
PrimitiveWhat it defines
Agent RuntimeThe logic — system prompt, model, tools, workflow
Sandbox TemplateThe environment — OS, runtimes, packages
DeploymentThe API — combines runtime + template into an endpoint
When you create a deployment, you get:
  • POST /v1/run/{slug} — run the agent
  • WS /v1/run/{slug}/stream — real-time streaming

​
Project Structure

A RunTools project follows this structure: 
my-project/
├── runtools.config.ts       # Project configuration
├── agents/
│   ├── code-assistant.ts    # Agent definition
│   ├── data-analyst.ts      # Another agent
│   └── support-bot/         # Complex agent (multiple files)
│       ├── index.ts
│       ├── tools.ts
│       └── prompts.ts
├── templates/               # Custom templates (optional)
│   └── ml-stack/
│       └── Dockerfile
├── package.json
└── tsconfig.json
  • runtools.config.ts — Project-level settings (default template, dev config)
  • agents/ — Each agent is a TypeScript file using defineAgent()
  • templates/ — Custom Dockerfiles for specialized environments
Code is the source of truth. The dashboard visual builder exports to these files, and changes to files are reflected in the dashboard.

​
Sandboxes

A Sandbox is an isolated execution environment for running code and agents.
Sandboxes start in milliseconds and can be paused/resumed in under 1 second with full state preservation.

​
Key Properties

PropertyDescription
IsolatedEach sandbox runs in its own microVM with full process isolation
Flexible StorageEphemeral by default, add persistent mounts as needed
PausableSnapshot entire VM state to disk, resume instantly
AccessiblePublic URLs for dev servers

​
Lifecycle

StateDescription
creatingVM is booting
runningReady for commands
pausedState saved to disk, no compute cost
stoppedTerminated
Transitions: create() → running, pause() → paused, resume() → running, delete() → stopped

​
Templates

A Template defines the base environment for sandboxes.

​
System Templates

TemplateContents
nodejs-20Node.js 20, npm, pnpm, Bun
python-mlPython 3.12, PyTorch, NumPy, Pandas
full-stackNode.js, Python, PostgreSQL, Redis

​
Custom Templates

Create your own templates with:
  • Template Builder UI — Select OS, runtimes, packages visually
  • Dockerfile — Full control with custom Dockerfile
const template = await rt.templates.create({
  slug: 'my-env',
  os: 'ubuntu-22.04',
  runtimes: [
    { name: 'node', version: '20' },
    { name: 'python', version: '3.12' },
  ],
  npm: ['typescript', 'tsx'],
  pip: ['numpy', 'pandas'],
});

​
Agent Runtimes

An Agent Runtime defines the AI agent’s behavior:
  • System Prompt — Instructions for the agent
  • Model — Which LLM to use (Claude, GPT-4, Gemini, etc.)
  • Tools — What capabilities the agent has
  • Workflow — Optional visual workflow for complex logic

​
Defining Agents

Agents are defined as TypeScript files using defineAgent():
agents/code-assistant.ts
import { defineAgent } from '@runtools/sdk';

export default defineAgent({
  slug: 'code-assistant',
  name: 'Code Assistant',
  model: 'claude-sonnet-4-20250514',
  systemPrompt: `You are an expert software engineer...`,
  tools: ['bash', 'read_file', 'edit_file', 'grep', 'glob', 'web_search'],
  template: 'nodejs-20',
});

​
Core Tools

These tools are included by default when you scaffold a new project with npx create-runtools-app or runtools init. Remove any you don’t need from the tools array.
ToolDescription
bashExecute shell commands. Run anything available in the sandbox.
read_fileRead file contents with optional line range. Returns numbered lines.
edit_fileEdit files with str_replace. Fuzzy matching finds the right location.
grepSearch file contents using ripgrep. Fast regex search across codebase.
globFind files by name pattern. Returns matching file paths.
web_searchSearch the web. Returns summarized results.
The dashboard and SDK mirror each other. Build your agent visually on the dashboard, then export as code — or write code and see it reflected in the dashboard.

​
Marketplace Tools

Install additional tools for external integrations:
ToolDescription
gmailSend and read emails
slackPost messages, read channels
githubManage repos, issues, PRs
stripeProcess payments
twilioSMS and voice calls

Tools Marketplace

Browse the full catalog of available tools

​
Deployments

A Deployment combines an Agent Runtime with a Sandbox Template to create an API endpoint. 
Agent Runtime + Sandbox Template = Deployment = API

​
Deployment Features

  • API Endpoint — POST /v1/run/{api_slug}
  • WebSocket Streaming — Real-time thinking, tool calls, results
  • Webhooks — Get notified on run.completed, run.failed, etc.
  • Controls — Pause, resume, cancel runs mid-execution

​
Model Agnostic

RunTools works with any LLM provider: 
const runtime = await rt.runtimes.create({
  model: 'claude-opus-4-5',     // Anthropic
  // model: 'gpt-5.2',           // OpenAI
  // model: 'gemini-3-pro', // Google
  // model: 'llama-4-scout',  // Meta
});
Or bring your own model: 
const runtime = await rt.runtimes.create({
  model: {
    provider: 'custom',
    endpoint: 'https://my-model.example.com/v1/chat',
    apiKey: process.env.MY_MODEL_KEY,
  },
});

​
The Agent Loop

When you run an agent, it executes a simple loop:
  1. Think — Model analyzes context and decides next action
  2. Act — If tool call needed, execute it and add result to context
  3. Repeat — Continue until model returns final response
Events emitted during execution:
  • thinking — Model’s reasoning
  • tool_call — Tool being invoked
  • tool_result — Tool output
  • complete — Final response

​
Next Steps

Sandboxes

Learn more about sandboxes

Agents

Build your first agent

Tools

Explore the tools marketplace

Templates

Create custom templates