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

Local development is a TypeScript project workflow: define sandboxes, tools, and agents locally, then deploy them with the CLI. There is no public runtools dev command in the current CLI.

​
Create a Project

runtools init my-project
cd my-project
npm install
This creates: 
runtools.config.ts
agents/example-agent.ts
tools/example-tool.ts
sandboxes/dev-env.ts

​
Validate Before Deploy

runtools deploy --dry-run
Deploy only one resource type while iterating: 
runtools deploy --sandboxes-only
runtools deploy --tools-only
runtools deploy --agents-only

​
Project Config

runtools.config.ts
import { defineConfig } from '@runtools/sdk';

export default defineConfig({
  project: {
    name: 'my-project',
  },
  defaultTemplate: 'desktop-ubuntu',
  toolsDir: './tools',
  agentsDir: './agents',
  sandboxesDir: './sandboxes',
});

​
Development Loop

  1. Edit tools/*.ts, sandboxes/*.ts, or agents/*.ts.
  2. Run runtools deploy --dry-run.
  3. Deploy the changed resource type.
  4. Test with runtools tool exec, runtools sandbox exec, or runtools agent run.

​
Sandbox Definitions

sandboxes/dev-env.ts
import { defineSandbox } from '@runtools/sdk';

export default defineSandbox({
  slug: 'dev-env',
  name: 'Development Environment',
  template: 'base-ubuntu',
  resources: { vcpus: 1, memory: '1G', disk: '10G' },
  idleTimeout: 1800,
});

​
Agent Definitions

agents/example-agent.ts
import { defineAgent } from '@runtools/sdk';

export default defineAgent({
  slug: 'example-agent',
  model: 'claude-sonnet-4',
  systemPrompt: 'You are helpful.',
  tools: ['exec_command', 'write_stdin', 'apply_patch', 'web_search'],
  sandbox: 'dev-env',
});

​
Tool Definitions

tools/example-tool.ts
import { defineTool } from '@runtools/sdk';

export default defineTool({
  name: 'example-tool',
  actions: {
    hello: {
      description: 'Say hello',
      parameters: {
        type: 'object',
        properties: { name: { type: 'string', description: 'Name' } },
        required: ['name'],
      },
      execute: async (params) => ({ message: `Hello, ${params.name}` }),
    },
  },
});