Project Workflow - Runtools.ai

A Runtools project is just a TypeScript folder: define your sandboxes, tools, and agents in files, then push them up with runtools deploy. You author and version everything locally — there’s no runtools dev server to babysit, just edit and deploy.

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-ai/sdk';

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

Development Loop

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

Sandbox Definitions

sandboxes/dev-env.ts

import { defineSandbox } from '@runtools-ai/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-ai/sdk';

export default defineAgent({
  slug: 'example-agent',
  model: 'claude-sonnet-4.5',
  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-ai/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}` }),
    },
  },
});

​Create a project

​Validate Before Deploy

​Project Config

​Development Loop

​Sandbox Definitions

​Agent Definitions

​Tool Definitions