Skip to main content

​
Requirements

  • Node.js 18+ or Bun 1.0+
  • TypeScript 5.0+ (recommended)
The SDK is not yet published to npm. Install from GitHub: npm install github:runtools-ai/runtools-sdk, or clone and npm link locally.

​
Installation

npm install @runtools/sdk

​
Configuration

​
Environment Variables

Create a .env file:
.env
RUNTOOLS_API_KEY=rt_live_xxxxxxxxxxxxx

​
Initialize the Client

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

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

​
Configuration Options

const rt = new RunTools({
  // Required
  apiKey: 'rt_live_xxx',
  
  // Optional
  baseUrl: 'https://api.runtools.ai',  // Custom API URL
  timeout: 30000,                       // Request timeout (ms)
  retries: 3,                           // Retry failed requests
  debug: false,                         // Enable debug logging
});

​
TypeScript Setup

The SDK includes full TypeScript definitions. No additional setup needed. 
import type { 
  Sandbox, 
  SandboxStatus,
  AgentRun,
  Template 
} from '@runtools/sdk';

​
ESM and CommonJS

The SDK supports both ESM and CommonJS: 
import { RunTools } from '@runtools/sdk';

​
Framework Examples

​
Next.js

lib/runtools.ts
import { RunTools } from '@runtools/sdk';

export const rt = new RunTools({
  apiKey: process.env.RUNTOOLS_API_KEY!,
});
app/api/sandbox/route.ts
import { rt } from '@/lib/runtools';

export async function POST() {
  const sandbox = await rt.sandboxes.create({ 
    template: 'nodejs-20' 
  });
  return Response.json(sandbox);
}

​
Express

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

const app = express();
const rt = new RunTools({ apiKey: process.env.RUNTOOLS_API_KEY! });

app.post('/sandbox', async (req, res) => {
  const sandbox = await rt.sandboxes.create({ template: 'nodejs-20' });
  res.json(sandbox);
});

​
Bun

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

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

Bun.serve({
  async fetch(req) {
    const sandbox = await rt.sandboxes.create({ template: 'nodejs-20' });
    return Response.json(sandbox);
  },
});

​
Verify Installation

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

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

// Test the connection
const sandboxes = await rt.sandboxes.list();
console.log('Connected! Found', sandboxes.length, 'sandboxes');

​
Next Steps

Sandboxes

Create and manage sandboxes

Agents

Build and run AI agents