Skip to main content

​
Overview

The SDK and CLI support local development with smart backend detection:
  • Run agents locally before deploying
  • Automatic Firecracker or Docker based on your environment
  • Sync files between local and cloud sandboxes
  • Test without cloud costs

​
Smart Backend Detection

When you run runtools dev, the CLI automatically detects the best local backend:
EnvironmentBackendPause/ResumeNotes
Linux + KVMFirecrackerYesFull fidelity
WSL2 + nested virtFirecrackerYesEnable in WSL settings
Mac (any)DockerNoStop/start only
Windows (no WSL2)DockerNoStop/start only
Want pause/resume on Windows?Enable nested virtualization in WSL2:
  1. Open PowerShell as Admin
  2. Run: wsl --update
  3. Add to .wslconfig: nestedVirtualization=true
  4. Restart WSL: wsl --shutdown
Now runtools dev will use Firecracker with full pause/resume support.

​
Force a Specific Backend

# Force cloud sandbox (always full features)
runtools dev --cloud

# Force Docker (useful for testing Docker behavior)
runtools dev --docker

​
Local Agent Development

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

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

// Create agent instance
const agent = new Agent({
  systemPrompt: 'You are a helpful coding assistant...',
  model: 'claude-opus-4-5',
  tools: ['bash', 'read_file', 'edit_file'],
  
  // Use local sandbox
  sandbox: await rt.sandboxes.create({ template: 'nodejs-20' }),
});

// Run locally
const result = await agent.run('Create a hello world app');

// Stream locally
for await (const event of agent.stream('Build a todo app')) {
  console.log(event.type, event.data);
}

​
Configuration File

Create runtools.config.ts in your project root:
runtools.config.ts
import { defineConfig } from '@runtools/cli';

export default defineConfig({
  project: {
    name: 'my-saas-app',
  },
  
  defaultTemplate: 'nodejs-20',
  agentsDir: './agents',
  
  dev: {
    sync: ['./src:/workspace/src'],
    ignore: ['node_modules', '.git', 'dist'],
  },
  
  env: {
    NODE_ENV: 'development',
  },
  
  hooks: {
    beforeSync: 'npm run build',
    afterSync: 'npm run dev',
  },
});

​
File Sync

// Sync local files to sandbox
await sandbox.sync({
  local: './src',
  remote: '/workspace/src',
  ignore: ['node_modules', '.git'],
});

// Watch for changes
await sandbox.sync({
  local: './src',
  remote: '/workspace/src',
  watch: true,
});

// Two-way sync
await sandbox.sync({
  local: './src',
  remote: '/workspace/src',
  bidirectional: true,
});

​
Local Execution

Run code locally with cloud tools: 
import { execute } from '@runtools/sdk';

// Execute locally but use cloud tools
const result = await execute({
  runtime: 'python',
  code: 'print("Hello")',
  local: true,  // Run on local machine
});

​
Dev Server Proxy

Access sandbox dev servers locally: 
// Start sandbox server
await sandbox.exec('npm run dev &');

// Proxy to local port
await sandbox.proxy({
  remotePort: 3000,
  localPort: 3000,
});

// Now access at http://localhost:3000

​
Testing Agents

import { Agent, MockSandbox } from '@runtools/sdk';

// Use mock sandbox for testing
const mockSandbox = new MockSandbox({
  files: {
    '/package.json': '{"name": "test"}',
  },
  execResults: {
    'npm --version': { stdout: '10.0.0', exitCode: 0 },
  },
});

const agent = new Agent({
  systemPrompt: '...',
  model: 'claude-opus-4-5',
  tools: ['bash', 'read_file'],
  sandbox: mockSandbox,
});

// Test agent behavior
const result = await agent.run('Check npm version');
expect(result.output).toContain('10.0.0');

​
Environment Switching

const rt = new RunTools({
  apiKey: process.env.RUNTOOLS_API_KEY,
  environment: process.env.NODE_ENV === 'production' ? 'live' : 'test',
});

// Test environment uses test sandboxes and doesn't bill

​
Debug Mode

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

// Logs all API calls
// DEBUG: POST /v1/sandboxes { template: 'nodejs-20' }
// DEBUG: 201 { id: 'sandbox-abc123', ... }

​
CLI Integration

# Initialize project
runtools init

# Start local dev (auto-detects Firecracker or Docker)
runtools dev

# Force cloud sandbox for full features
runtools dev --cloud

# Sync files
runtools sync --watch

# Push to dashboard for preview
runtools push

# Deploy to production
runtools deploy

# Run agent interactively
runtools agent chat code-assistant