Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runtools.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Code Assistant Agent

Create a sandbox, define an agent, deploy, and run it.
sandboxes/dev-env.ts
import { defineSandbox } from '@runtools/sdk';

export default defineSandbox({
  slug: 'dev-env',
  name: 'Development Environment',
  template: 'desktop-ubuntu',
  resources: { vcpus: 1, memory: '1G', disk: '10G' },
  idleTimeout: 1800,
});
agents/code-assistant.ts
import { defineAgent } from '@runtools/sdk';

export default defineAgent({
  slug: 'code-assistant',
  name: 'Code Assistant',
  model: 'claude-sonnet-4',
  sandbox: 'dev-env',
  tools: ['exec_command', 'write_stdin', 'apply_patch', 'view_image', 'web_search', 'get_dev_url'],
  systemPrompt: 'You are a careful software engineering assistant. Run tests before final answers.',
});

runtools deploy
runtools agent run code-assistant "Create a REST API with Express and TypeScript"

​
GitHub PR Review Bot

Install the GitHub tool, connect GitHub, and add the tool slug to your agent. 
runtools tool install github
runtools oauth connect github
agents/pr-reviewer.ts
import { defineAgent } from '@runtools/sdk';

export default defineAgent({
  slug: 'pr-reviewer',
  name: 'PR Reviewer',
  model: 'claude-sonnet-4',
  sandbox: 'dev-env',
  tools: ['exec_command', 'write_stdin', 'apply_patch', 'web_search', 'github'],
  systemPrompt: `Review pull requests for correctness, security, and missing tests.
Return concise findings with file and line references when possible.`,
});

​
Email Assistant

OAuth-backed tools can resolve connected accounts during hosted tool execution. 
runtools tool install gmail
runtools oauth connect google
agents/email-assistant.ts
import { defineAgent } from '@runtools/sdk';

export default defineAgent({
  slug: 'email-assistant',
  name: 'Email Assistant',
  model: 'claude-sonnet-4',
  sandbox: 'dev-env',
  tools: ['web_search', 'gmail'],
  systemPrompt: 'Summarize important mail, draft replies, and extract action items.',
});

​
Custom Tool + Agent

tools/customer-db.ts
import { defineTool } from '@runtools/sdk';

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

export default defineAgent({
  slug: 'support-agent',
  name: 'Support Agent',
  model: 'claude-sonnet-4',
  sandbox: 'dev-env',
  tools: ['web_search', 'customer-db'],
  systemPrompt: 'Use the customer-db tool to answer support questions accurately.',
});
Store the credential and deploy: 
runtools secret set CUSTOMER_DB_API_KEY "crm_xxx" --category tool --org-wide
runtools deploy

​
Programmatic Sandbox Management

import { RunTools } from '@runtools/sdk';

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

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

sandbox.on('status', (state) => {
  console.log(state.status, state.sshReady);
});

await sandbox.waitForReady();

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

await sandbox.pause();
await sandbox.resume();
await sandbox.waitForReady();
await sandbox.destroy();

​
Workflow Automation

await rt.workflows.save({
  slug: 'daily-summary',
  name: 'Daily Summary',
  graph: {
    nodes: [
      {
        id: 'summary',
        type: 'agent',
        config: {
          agent: 'email-assistant',
          prompt: 'Summarize high-priority updates.',
        },
      },
    ],
    edges: [],
  },
});

await rt.workflows.createTrigger('daily-summary', {
  type: 'cron',
  cronExpression: '0 9 * * 1-5',
  timezone: 'America/Los_Angeles',
});

​
Best Practices

New projects created by runtools init use exec_command, write_stdin, apply_patch, view_image, web_search, and get_dev_url.
Prefer Connected Apps for OAuth-backed marketplace tools.
Use runtools secret or rt.secrets, then reference secrets during tool execution.
Keep long-lived environments only when you need their state.