SDK Overview - Runtools.ai

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

npm install @runtools-ai/sdk

Client

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
`rt.agent`	Define, run (one-shot or threaded), inspect runs, attachments, visibility	Agents
`rt.tools`	Marketplace, install, credentials, execute, custom tools	Tools
`rt.connect`	Hosted connect sessions and customer-owned integrations for products built on Runtools	Hosted Connect
`rt.workspaces`	Persistent storage + `rt.workspaces.files` for file operations	Workspaces
`rt.threads`	Cloud thread history, events, rollouts, compaction, live streaming	Threads
`rt.secrets`	User-private and org-shared encrypted secrets	Secrets
`rt.auth`	OAuth connections, API keys, BYOA provider configs	Connected Apps
`rt.billing`	Credits, usage, plan, pricing, and top-ups	Billing
`rt.models`	List selectable Platform and BYOK models	Models
`rt.devices`	RunMesh devices — link, list, config, audit, revoke	RunMesh
`rt.installableAgents`	Install and configure agents like Hermes into a sandbox	Tool Hub
`rt.activity`	Unified customer activity feed	Activity
`rt.sshKeys`	Register and manage SSH keys	Organizations
`rt.me`	Read and update the authenticated user profile	—
`rt.workflows`	Workflow runs, versions, and triggers	Schedules

Example

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:

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:

import { defineAgent, defineTool, defineSandbox, defineConfig } from '@runtools-ai/sdk';

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

Next Steps

Installation

Install and configure the client.

Sandboxes

Spin up and drive sandboxes with rt.sandbox.

Agents

Define and run agents with defineAgent() and rt.agent.

Tools

Build and call tools with defineTool() and rt.tools.

Hosted Connect

Let customers connect their own integrations to your Runtools-built products.

Workspaces

Persistent storage and files with rt.workspaces.

Threads

Conversation history and live streams with rt.threads.

​Client

​Managers

​Example

​Error Handling

​Definition Helpers

​Next Steps