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

# SDK Overview

> Use the Runtools TypeScript SDK

`@runtools-ai/sdk` is two things in one package: a typed **client** for driving the platform (`RunTools`), and a set of **definition helpers** — `defineTool()`, `defineAgent()`, `defineSandbox()`, `defineConfig()` — for authoring things you deploy. Most projects use both.

```bash theme={null}
npm install @runtools-ai/sdk
```

## Client

```typescript theme={null}
import { RunTools } from '@runtools-ai/sdk';

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

The constructor also accepts `accessToken`, `apiUrl`, `authUrl`, `toolsUrl`, and `billingUrl`. Environment variables with the same purpose are supported:

| Variable               | Default                                             |
| ---------------------- | --------------------------------------------------- |
| `RUNTOOLS_API_KEY`     | Required unless `apiKey` or `accessToken` is passed |
| `RUNTOOLS_API_URL`     | `https://api.runtools.ai`                           |
| `RUNTOOLS_AUTH_URL`    | `https://auth.runtools.ai`                          |
| `RUNTOOLS_TOOLS_URL`   | `https://tools.runtools.ai`                         |
| `RUNTOOLS_BILLING_URL` | `https://billing.runtools.ai`                       |

## Managers

The client exposes one manager per resource. Each gets calls right with the caller's auth and the correct service URL.

| Manager                | What it does                                                                           | Guide                                 |
| ---------------------- | -------------------------------------------------------------------------------------- | ------------------------------------- |
| `rt.sandbox`           | Create, exec, pause/resume, destroy, dev URLs, SSH, logs, live status                  | [Sandboxes](/sdk/sandboxes)           |
| `rt.agent`             | Define, run (one-shot or threaded), inspect runs, attachments, visibility              | [Agents](/sdk/agents)                 |
| `rt.tools`             | Marketplace, install, credentials, execute, custom tools                               | [Tools](/sdk/tools)                   |
| `rt.connect`           | Hosted connect sessions and customer-owned integrations for products built on Runtools | [Hosted Connect](/sdk/hosted-connect) |
| `rt.workspaces`        | Persistent storage + `rt.workspaces.files` for file operations                         | [Workspaces](/sdk/workspaces)         |
| `rt.threads`           | Cloud thread history, events, rollouts, compaction, live streaming                     | [Threads](/sdk/threads)               |
| `rt.secrets`           | User-private and org-shared encrypted secrets                                          | [Secrets](/advanced/secrets)          |
| `rt.auth`              | OAuth connections, API keys, BYOA provider configs                                     | [Connected Apps](/advanced/oauth)     |
| `rt.billing`           | Credits, usage, plan, pricing, and top-ups                                             | [Billing](/api-reference/billing)     |
| `rt.models`            | List selectable Platform and BYOK models                                               | [Models](/api-reference/models)       |
| `rt.devices`           | RunMesh devices — link, list, config, audit, revoke                                    | [RunMesh](/api-reference/runmesh)     |
| `rt.installableAgents` | Install and configure agents like Hermes into a sandbox                                | [Tool Hub](/features/tool-hub)        |
| `rt.activity`          | Unified customer activity feed                                                         | [Activity](/api-reference/activity)   |
| `rt.sshKeys`           | Register and manage SSH keys                                                           | [Organizations](/organizations)       |
| `rt.me`                | Read and update the authenticated user profile                                         | —                                     |
| `rt.workflows`         | Workflow runs, versions, and triggers                                                  | [Schedules](/advanced/schedules)      |

## Example

```typescript theme={null}
const sandbox = await rt.sandbox.create({
  name: 'sdk-demo',
  template: 'base-ubuntu',
});

await sandbox.waitForReady();

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

await sandbox.destroy();
```

## Error Handling

HTTP failures throw `RunToolsApiError`:

```typescript theme={null}
import { RunToolsApiError } from '@runtools-ai/sdk';

try {
  await rt.sandbox.destroy('missing-sandbox');
} catch (error) {
  if (error instanceof RunToolsApiError) {
    console.error(error.status, error.code, error.message, error.requestId);
  }
}
```

## Definition Helpers

Use helpers inside deployable projects:

```typescript theme={null}
import { defineAgent, defineTool, defineSandbox, defineConfig } from '@runtools-ai/sdk';
```

`runtools deploy` reads `runtools.config.ts`, `sandboxes/*.ts`, `tools/*.ts`, and `agents/*.ts`.

## Next Steps

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/sdk/installation">
    Install and configure the client.
  </Card>

  <Card title="Sandboxes" icon="server" href="/sdk/sandboxes">
    Spin up and drive sandboxes with `rt.sandbox`.
  </Card>

  <Card title="Agents" icon="robot" href="/sdk/agents">
    Define and run agents with `defineAgent()` and `rt.agent`.
  </Card>

  <Card title="Tools" icon="wrench" href="/sdk/tools">
    Build and call tools with `defineTool()` and `rt.tools`.
  </Card>

  <Card title="Hosted Connect" icon="plug" href="/sdk/hosted-connect">
    Let customers connect their own integrations to your Runtools-built products.
  </Card>

  <Card title="Workspaces" icon="folder-tree" href="/sdk/workspaces">
    Persistent storage and files with `rt.workspaces`.
  </Card>

  <Card title="Threads" icon="book-open" href="/sdk/threads">
    Conversation history and live streams with `rt.threads`.
  </Card>
</CardGroup>