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.

​
Overview

@runtools/sdk is the TypeScript client and project-definition package for Runtools. It exports the RunTools client plus helpers such as defineAgent(), defineTool(), defineSandbox(), and defineConfig().
The SDK is not published to npm yet. In early access, use the local repo or a local workspace dependency.

​
Client

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

const rt = new RunTools({
  apiKey: process.env.RUNTOOLS_API_KEY,
});
The constructor also accepts accessToken, apiUrl, authUrl, toolsUrl, and convexUrl. Environment variables with the same purpose are supported:
VariableDefault
RUNTOOLS_API_KEYRequired unless apiKey or accessToken is passed
RUNTOOLS_API_URLhttps://api.runtools.ai
RUNTOOLS_AUTH_URLhttps://auth.runtools.ai
RUNTOOLS_TOOLS_URLhttps://tools.runtools.ai
RUNTOOLS_CONVEX_URLPlatform default

​
Managers

ManagerDescription
rt.sandboxCreate, list, get, destroy, exec, pause, resume, and subscribe to sandbox state
rt.agentList, run, thread, visibility, and attachment helpers
rt.toolsMarketplace search/list, install, credentials, custom tools, and tool execution
rt.secretsUser-private and org-shared secrets
rt.workflowsWorkflow save/update/run/version/trigger APIs
rt.threadsCloud thread history, events, rollouts, archive, rename, compact, and streaming subscriptions
rt.sshKeysSSH key management
rt.devicesRunMesh device and audit APIs
rt.authOAuth connections, API keys, BYOA provider configs

​
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/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/sdk';
runtools deploy reads runtools.config.ts, sandboxes/*.ts, tools/*.ts, and agents/*.ts.

​
Next Steps

Installation

Set up the package locally.

Sandboxes

Use rt.sandbox.

Agents

Use defineAgent() and rt.agent.

Tools

Use defineTool() and rt.tools.