Use Cases

Five things people actually build on Runtools, end to end — copy one, swap the names, deploy. Each is a real config: a sandbox, an agent, sometimes a tool, and the commands to ship it.

Code assistant agent

Create a sandbox, define an agent, deploy, and run it.

sandboxes/dev-env.ts

import { defineSandbox } from '@runtools-ai/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-ai/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-ai/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-ai/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-ai/sdk';

export default defineTool({
  name: 'customer-db',
  description: 'Query the customer database',
  credentials: {
    required: ['CUSTOMER_API_KEY'],
    schema: {
      CUSTOMER_API_KEY: { 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.CUSTOMER_API_KEY}`,
          },
        });
        return response.json();
      },
    },
  },
});

agents/support-agent.ts

import { defineAgent } from '@runtools-ai/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.',
});

Deploy the tool and agent, then store the tool credential:

runtools deploy
runtools tool credentials customer-db --json '{"CUSTOMER_API_KEY":"crm_xxx"}'

Programmatic Sandbox Management

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

const rt = new RunTools({ CUSTOMER_API_KEY: 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();

Best Practices

Use current core tool names

New projects created by runtools init use exec_command, write_stdin, apply_patch, view_image, web_search, and get_dev_url.

Link sandbox-backed agents explicitly

in_sandbox agents require sandbox.

Use OAuth before manual provider tokens

Prefer Connected Apps for OAuth-backed marketplace tools.

Store reusable credentials as secrets

Use runtools tool credentials for installed API-key tools. Use runtools secret or rt.secrets for named secrets that your own code or direct tool calls reference.

Pause or destroy sandboxes when done

Keep long-lived environments only when you need their state.

Getting Started

Platform

Core Features

Advanced

Code assistant agent

GitHub PR Review Bot

Email Assistant

Custom Tool + Agent

Programmatic Sandbox Management

Best Practices

​Code assistant agent

​GitHub PR Review Bot

​Email Assistant

​Custom Tool + Agent

​Programmatic Sandbox Management

​Best Practices

Code assistant agent

GitHub PR Review Bot

Email Assistant

Custom Tool + Agent

Programmatic Sandbox Management

Best Practices