> ## 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.

# Use Cases

> Practical RunTools patterns you can build today

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.

```typescript sandboxes/dev-env.ts theme={null}
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,
});
```

```typescript agents/code-assistant.ts theme={null}
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.',
});
```

```bash theme={null}
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.

```bash theme={null}
runtools tool install github
runtools oauth connect github
```

```typescript agents/pr-reviewer.ts theme={null}
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.

```bash theme={null}
runtools tool install gmail
runtools oauth connect google
```

```typescript agents/email-assistant.ts theme={null}
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

```typescript tools/customer-db.ts theme={null}
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();
      },
    },
  },
});
```

```typescript agents/support-agent.ts theme={null}
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:

```bash theme={null}
runtools deploy
runtools tool credentials customer-db --json '{"CUSTOMER_API_KEY":"crm_xxx"}'
```

## Programmatic Sandbox Management

```typescript theme={null}
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

<AccordionGroup>
  <Accordion title="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`.
  </Accordion>

  <Accordion title="Link sandbox-backed agents explicitly">
    `in_sandbox` agents require `sandbox`.
  </Accordion>

  <Accordion title="Use OAuth before manual provider tokens">
    Prefer Connected Apps for OAuth-backed marketplace tools.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Pause or destroy sandboxes when done">
    Keep long-lived environments only when you need their state.
  </Accordion>
</AccordionGroup>