> ## 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.

# Project Workflow

> Develop deployable Runtools projects locally

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

```bash theme={null}
runtools init my-project
cd my-project
npm install
```

This creates:

```text theme={null}
runtools.config.ts
agents/example-agent.ts
tools/example-tool.ts
sandboxes/dev-env.ts
```

## Validate Before Deploy

```bash theme={null}
runtools deploy --dry-run
```

Deploy only one resource type while iterating:

```bash theme={null}
runtools deploy --sandboxes-only
runtools deploy --tools-only
runtools deploy --agents-only
```

## Project Config

```typescript runtools.config.ts theme={null}
import { defineConfig } from '@runtools-ai/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

```typescript sandboxes/dev-env.ts theme={null}
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

```typescript agents/example-agent.ts theme={null}
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

```typescript tools/example-tool.ts theme={null}
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}` }),
    },
  },
});
```