Tool Forge Runner

What is a Runner?

A Runner is an instance of the Tool Forge SDK running on your machine or server that connects your tools to the Tool Forge platform. When you execute toolforge dev or toolforge deploy, your machine becomes a runner—it discovers your tools, registers them with Tool Forge, and executes them when users interact with the dashboard.

Think of a runner as a bridge between your backend code and the Tool Forge dashboard:

How Runners Work

1. Discovery

When a runner starts, it scans your tools/ directory to discover all available tools and agents:

tools/
├── hello-world.ts      → Registered as "Hello World" tool
├── orders/
│   ├── create-order.ts → Registered as "Create Order" tool
│   └── refund-order.ts → Registered as "Refund Order" tool
└── support/
    └── ticket-agent.ts → Registered as "Ticket Agent" agent

2. Connection

The runner establishes a persistent WebSocket connection to the Tool Forge SDK server:

1. Authenticates using your environment's API key
2. Registers itself with a unique runner ID
3. Sends a list of all discovered tools and agents
4. Starts listening for commands from the platform

3. Execution

When a user starts a tool from the dashboard:

1. Tool Forge sends a START_TOOL message to an available runner
2. The runner spawns a new tool session to handle the execution
3. The tool's handler function runs, interacting with the user via io.* methods
4. Results are sent back to the dashboard in real-time
5. When complete, the runner sends a TOOL_COMPLETE or TOOL_ERROR message

4. Hot Reload (Development Only)

In development mode, the runner watches your tools/ directory for changes:

• File added: New tool is registered
• File changed: Tool is reloaded with new code
• File deleted: Tool is unregistered

This enables rapid iteration without manually restarting the server.

Runner Modes

Runners operate in one of two modes, corresponding to environment types:

Development Mode

Started with toolforge dev (or bun dev):

bun dev

Production Mode

Started with toolforge start (or bun start):

bun start

Why Environment Separation Matters

The separation between development and production runners is enforced by design for these critical reasons:

Runner Conflicts

Each environment can have multiple runners connected simultaneously. When you run toolforge dev:

• Your local runner registers your tools with the environment
• If connected to production, your in-development code becomes available to all users
• Multiple runners with different tool versions cause unpredictable behavior

Session Interruption

When a runner's tool list changes (via hot reload), active sessions may be affected:

• In development: This is expected—you're iterating
• In production: This could interrupt a user mid-operation, causing data loss or failed transactions

Code Stability

Development code is inherently unstable:

• Incomplete features
• Debugging statements
• Experimental changes
• Potential bugs

Production environments should only run tested, stable code.

The Safe Pattern

Development Environment          Production Environment
        │                                │
        ▼                                ▼
┌───────────────┐               ┌───────────────┐
│ toolforge dev │               │toolforge start│
│  (Your laptop)│               │ (Server/Cloud)│
└───────────────┘               └───────────────┘
        │                                │
        ▼                                ▼
   Hot reload                      Stable tools
   Debug logs                    Minimal logging
   pk_test_ key                   sk_live_ key

Multiple Runners

You can connect multiple runners to the same environment for:

Load Balancing

In production, multiple runners can handle tool executions in parallel:

Production Environment
        │
        ├── Runner 1 (Server A) ─── Handling 5 sessions
        ├── Runner 2 (Server B) ─── Handling 3 sessions
        └── Runner 3 (Server C) ─── Handling 7 sessions

Tool Forge automatically routes new sessions to available runners.

High Availability

If one runner goes offline, others continue serving requests:

• No single point of failure
• Seamless failover
• Zero downtime deployments (rolling updates)

Team Development

In development, each team member runs their own runner:

Development Environment
        │
        ├── Runner (Alice's laptop) ─── Testing new feature
        ├── Runner (Bob's laptop) ─── Fixing bug
        └── Runner (CI Server) ─── Running automated tests

Monitoring Runners

The Tool Forge dashboard shows runner status for each environment:

Use this information to:

• Verify deployments are successful
• Monitor resource usage
• Debug connectivity issues
• Plan capacity

Lifecycle

Starting a Runner

# Development
bun dev

# Production
bun start

The runner:

1. Loads configuration from toolforge.config.ts
2. Discovers tools in the tools/ directory
3. Connects to Tool Forge via WebSocket
4. Registers all tools with the environment
5. Begins accepting tool execution requests

Stopping a Runner

Press Ctrl+C or send a termination signal. The runner:

1. Stops accepting new sessions
2. Waits for active sessions to complete (graceful shutdown)
3. Closes the WebSocket connection
4. Unregisters from the environment

Next Steps

• Tools - Learn about building tools in Tool Forge
• Agents - Create multi-step workflows with context and branching
• Environment - Learn about development vs production environments
• Workspace - Understand the organizational structure
• Quick Start - Start your first runner