Architecture Overview RunTools is built on four core primitives:
Primitive What it is Sandbox An isolated Firecracker microVM — your compute environment Agent AI logic — model, system prompt, tools, running inside a sandbox Tool A server-side integration — GitHub, Gmail, Slack, or your own custom tools Workflow An orchestration of multiple agents (coming soon)
These compose together: Agents need tools and a sandbox. Workflows orchestrate agents.
Project Structure A RunTools project follows this structure:
my-project/ ├── runtools.config.ts # Project configuration ├── agents/ │ └── code-assistant.ts # Agent definition (defineAgent) ├── tools/ │ └── my-tool.ts # Custom tool definition (defineTool) ├── sandboxes/ │ └── dev-env.ts # Sandbox definition (defineSandbox) ├── package.json └── tsconfig.json
runtools.config.tsagents/defineAgent() from the SDKtools/defineTool() — deployed to your org via runtools deploysandboxes/defineSandbox() — deployed via runtools deploy
Deploy everything with one command:
Sandboxes A Sandbox is an isolated Firecracker microVM with its own filesystem, network, and processes.
Key Properties Property Description Isolated Each sandbox runs in its own microVM with hardware-level isolation (KVM) Pausable Snapshot entire VM state to disk, resume in under a second Accessible Public dev URLs via {port}-{sandboxId}.sandboxes.runtools.ai SSH Access ssh sandbox-id@ssh.runtools.ai — key or password authDesktop Full XFCE4 desktop with VNC via desktop-ubuntu template
Lifecycle State Description creatingVM is booting (~5 seconds for cold start) runningReady for commands, SSH, and VNC pausedState saved to disk, zero compute cost stoppedTerminated and cleaned up
Transitions: create → running → pause → paused → resume → running → destroy → stopped
Templates Template Description base-ubuntuCLI environment with Bun, Node.js, common tools desktop-ubuntuFull XFCE4 desktop + KasmVNC + Firefox ESR + Plank dock
Custom templates (Dockerfile-based) are planned but not yet available. Currently, use base-ubuntu for CLI environments and desktop-ubuntu for desktop/VNC use cases.
Agents An Agent is an AI entity that runs inside a sandbox. It has a model, instructions, tools, and a sandbox to operate in.
Defining Agents import { defineAgent } from '@runtools/sdk' ; export default defineAgent ({ slug: 'code-assistant' , name: 'Code Assistant' , model: 'claude-sonnet-4' , systemPrompt: `You are an expert software engineer. You help users build applications by writing clean, well-documented code.` , tools: [ 'bash' , 'read_file' , 'edit_file' , 'grep' , 'web_search' ] , }) ;
Agents can also be created and managed from the dashboard via the Agent Builder UI.
Every agent gets these built-in tools — they cannot be removed:
Tool Description bashExecute shell commands in the sandbox read_fileRead file contents with optional line range edit_fileEdit files with string replacement write_fileWrite new files delete_fileDelete files list_directoryList directory contents file_searchFind files by name pattern grepSearch file contents using ripgrep web_searchSearch the web via Exa get_dev_urlGet public URL for a dev server port
Install additional tools from the marketplace:
Tool OAuth Provider Description githubGitHub Repos, issues, PRs, code search gmailGoogle Send, read, search emails google-calendarGoogle Events, scheduling, free/busy google-sheetsGoogle Read, write, create spreadsheets slackSlack Messages, channels, users discordDiscord Messages, channels, servers outlookMicrosoft Email and calendar via Office 365 x-twitterX Tweets, search, timeline linkedinLinkedIn Posts, profile, network telegramTelegram Messages, photos, updates
All marketplace tools support OAuth auto-resolution — connect your account once and credentials are resolved automatically. You can also build and publish your own.
The Agent Loop When you run an agent, the runtime executes a streaming loop:
Prompt — User message + system prompt sent to the modelThink — Model analyzes context, decides next actionTool Call — If needed, executes a tool and adds result to contextRepeat — Continues until model returns a final text response (max 25 iterations, configurable up to 100)
Events streamed during execution: text-delta, tool-call, tool-result, thinking, done
Model Support RunTools is model-agnostic. Supported providers and models:
Provider Models Anthropic Claude Opus 4.6, Opus 4.5, Sonnet 4.5, Sonnet 4, Haiku OpenAI GPT-5.2, GPT-5.2 Pro, GPT-5, GPT-5 Mini, GPT-4.1, O4 Mini Google Gemini 3 Pro, Gemini 3 Flash, Gemini 2 Flash xAI Grok 4, Grok 3 Mistral Mistral Large DeepSeek DeepSeek, DeepSeek Reasoner Groq Llama 4, Llama 3.3 70B
Tools are server-side integrations that agents can call. They run in the tools service (tools.runtools.ai), not inside sandboxes. Credentials are resolved automatically via OAuth or manual configuration.Two Types Type Description Marketplace Tools 10 official tools (GitHub, Gmail, Slack, Discord, and more) — install from the marketplace Custom Tools Your own tools — write with defineTool(), deploy with runtools deploy
import { defineTool } from '@runtools/sdk' ; export default defineTool ({ name: 'my-database' , description: 'Query my application database' , credentials: { required: [ 'databaseUrl' ], schema: { databaseUrl: { type: 'string' , description: 'PostgreSQL connection string' }, }, } , actions: { query: { description: 'Execute a SQL query' , parameters: { type: 'object' , properties: { sql: { type: 'string' , description: 'SQL query' } }, required: [ 'sql' ], }, execute : async ( params , credentials ) => { // Your implementation return { rows: [] }; }, }, } , }) ;
Organizations and Projects
Organizations — top-level grouping. All resources (sandboxes, agents, tools, secrets, API keys, SSH keys) are org-scoped.Projects — UI grouping within an org. Projects organize resources visually but don’t affect permissions. Every org has a default project.
Secrets & OAuth Centralized credentials management:
Secrets — API keys and provider credentials, encrypted at rest with AES-256-GCMConnected Apps — OAuth connections for automatic credential resolution (see OAuth )SSH Keys — for sandbox accessManage via dashboard (Credentials page), CLI (runtools secret set/list/delete), or API
Scoped by category: provider keys, tool keys, custom secrets
Next Steps
Sandboxes Deep dive into sandboxes
Agents Build your first agent
Tools Explore the Tool Hub
CLI Reference Manage everything from the command line
