Skip to main content

​
Overview

RunTools is used to build AI-powered applications across many domains. Here are common patterns showing what you can build today.

​
Code Assistant Agent

Build an agent that can write, debug, and refactor code inside a sandbox.
agents/code-assistant.ts
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.
Always explain your reasoning before making changes.`,
  tools: ['bash', 'read_file', 'edit_file', 'grep', 'web_search'],
});
Deploy and run: 
runtools deploy
runtools agent run code-assistant --prompt "Create a REST API with Express and TypeScript"
The agent has full access to the sandbox filesystem, can install packages, run tests, and start dev servers.

​
GitHub PR Review Bot

An agent that reviews pull requests using the GitHub marketplace tool.
agents/pr-reviewer.ts
import { defineAgent } from '@runtools/sdk';

export default defineAgent({
  slug: 'pr-reviewer',
  name: 'PR Reviewer',
  model: 'claude-sonnet-4',
  systemPrompt: `You are an expert code reviewer. When given a PR:
1. Use the github tool to list changed files
2. Read each file and analyze for bugs, security issues, and style
3. Provide constructive, specific feedback`,
  tools: ['bash', 'read_file', 'grep', 'web_search', 'github'],
});
The github tool is installed from the marketplace and configured with your GitHub PAT via the Credentials page.

​
AI Email Assistant

Process emails using the Gmail marketplace tool.
agents/email-assistant.ts
import { defineAgent } from '@runtools/sdk';

export default defineAgent({
  slug: 'email-assistant',
  name: 'Email Assistant',
  model: 'claude-sonnet-4',
  systemPrompt: `You help manage emails:
- Summarize important emails
- Draft professional responses
- Categorize and prioritize
- Extract action items`,
  tools: ['gmail', 'web_search'],
});

​
Custom Tool + Agent

Build a custom tool that queries your database, then use it in an agent.
tools/customer-db.ts
import { defineTool } from '@runtools/sdk';

export default defineTool({
  name: 'customer-db',
  description: 'Query the customer database',
  credentials: {
    required: ['databaseUrl'],
    schema: {
      databaseUrl: { type: 'string', description: 'PostgreSQL connection string' },
    },
  },
  actions: {
    lookup: {
      description: 'Look up a customer by email',
      parameters: {
        type: 'object',
        properties: {
          email: { type: 'string', description: 'Customer email' },
        },
        required: ['email'],
      },
      execute: async (params, credentials) => {
        const res = await fetch(`${credentials.databaseUrl}/customers?email=${params.email}`);
        return await res.json();
      },
    },
  },
});
agents/support-agent.ts
import { defineAgent } from '@runtools/sdk';

export default defineAgent({
  slug: 'support-agent',
  name: 'Support Agent',
  model: 'claude-sonnet-4',
  systemPrompt: `You are a customer support agent. Use the customer-db tool
to look up customer information and provide helpful responses.`,
  tools: ['bash', 'read_file', 'customer-db', 'web_search'],
});
Deploy both: 
runtools deploy  # Deploys tools/ and agents/

​
Desktop Environment for Computer Use

Create a desktop sandbox with full GUI for browser automation or computer-use agents. 
# Create a desktop sandbox with VNC
runtools sandbox create --name browser-env --template desktop-ubuntu

# Open the desktop in your browser
# https://6901-sandbox-xxx.sandboxes.runtools.ai

# Or SSH into it
runtools sandbox ssh browser-env
The desktop sandbox includes XFCE4, Firefox ESR, and tools like xdotool, scrot, and imagemagick for computer-use agents.

​
SDK: Programmatic Sandbox Management

Use the SDK to manage sandboxes from your application code. 
import { RunTools } from '@runtools/sdk';

const rt = new RunTools({ apiKey: process.env.RUNTOOLS_API_KEY });

// Create a sandbox
const sandbox = await rt.sandbox.create({
  template: 'base-ubuntu',
  name: 'my-dev-env',
});

// Wait for it to boot
await sandbox.waitForReady();

// Real-time status via Convex WebSocket
sandbox.on('status', (state) => {
  console.log(`Status: ${state.status}, SSH: ${state.sshReady}`);
});

sandbox.on('metrics', (m) => {
  console.log(`CPU: ${m.cpuPercent}%, MEM: ${m.memPercent}%`);
});

// Execute commands
const result = await sandbox.exec('node --version');
console.log(result.stdout);

// Pause when done
await sandbox.pause();

// Resume later
await sandbox.resume();
await sandbox.waitForReady();

​
Secrets Management

Store API keys and credentials securely for your tools and agents. 
# Store provider API keys
runtools secret set ANTHROPIC_API_KEY sk-ant-xxx --category provider
runtools secret set OPENAI_API_KEY sk-xxx --category provider

# Store tool credentials
runtools secret set GITHUB_TOKEN ghp_xxx --category tool
runtools secret set SLACK_BOT_TOKEN xoxb-xxx --category tool

# List secrets (values never shown)
runtools secret list
Or manage via the dashboard under Credentials.

​
Best Practices

Use base-ubuntu for CLI/headless tasks, desktop-ubuntu when you need a browser or GUI.
Paused sandboxes have zero compute cost. Resume takes under a second. Auto-pause kicks in after 10 minutes of inactivity.
Use runtools secret set or the Credentials page to store API keys. Never hardcode credentials in agent definitions.
Every agent gets bash, read_file, edit_file, etc. These are powerful — agents can install packages, run tests, and modify code.
If the marketplace doesn’t have what you need, write a custom tool with defineTool() and deploy it to your org.