Tool Forge - Build AI Apps from Backend Logic

This guide walks you through setting up a Tool Forge project manually, giving you full control over the project structure and configuration.

For most users, we recommend using the Quick Start guide with bunx --bun create-toolforge@latest to scaffold a new project automatically.

Prerequisites

Bun runtime installed (v1.0.0 or higher)
A Tool Forge account with an API key (see Managing API Keys)

Project Setup

Create project directory

Create a new directory for your project and initialize it:

mkdir my-toolforge-project
cd my-toolforge-project
bun init -y

Install dependencies

Install the Tool Forge SDK and required dependencies:

bun add @toolforge-js/sdk dotenv zod

Install development dependencies:

bun add -d @types/bun @types/node typescript

Package	Description
`@toolforge-js/sdk`	Tool Forge SDK for building tools
`dotenv`	Load environment variables from `.env` file
`zod`	TypeScript-first schema validation
`typescript`	TypeScript compiler
`@types/bun`	Type definitions for Bun runtime
`@types/node`	Type definitions for Node.js APIs

Configure package.json

Update your package.json with the following scripts and configuration:

{
  "name": "my-toolforge-project",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "toolforge dev",
    "start": "toolforge start",
    "build": "toolforge build",
    "typecheck": "tsc"
  },
  "dependencies": {
    "@toolforge-js/sdk": "latest",
    "dotenv": "^16.5.0",
    "zod": "^3.24.0"
  },
  "devDependencies": {
    "@types/bun": "^1.3.0",
    "@types/node": "^24.0.0",
    "typescript": "^5.9.0"
  }
}

Script	Description
`bun dev`	Start the development server with hot reload
`bun start`	Run tools in production mode
`bun build`	Build tools for production deployment

Create TypeScript configuration

Create a tsconfig.json file in your project root:

{
  "$schema": "https://json.schemastore.org/tsconfig",
  "compilerOptions": {
    "skipLibCheck": true,
    "incremental": true,
    "strict": true,
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["DOM", "DOM.Iterable", "ES2022", "ESNext"],
    "noEmit": true,
    "verbatimModuleSyntax": true
  },
  "exclude": ["node_modules"]
}

Create environment file

Create a .env file to store your API key:

TOOL_FORGE_API_KEY=pk_test_your_api_key_here

Never commit your .env file to version control. Add it to your .gitignore.

Create Tool Forge configuration

Create a toolforge.config.ts file in your project root:

import 'dotenv/config'
import { defineConfig } from '@toolforge-js/sdk/config'
import * as z from 'zod'

const { TOOL_FORGE_API_KEY } = z
  .object({
    TOOL_FORGE_API_KEY: z
      .string()
      .refine((val) => val.startsWith('sk_live') || val.startsWith('pk_test'), {
        message: 'API key must start with sk_live or pk_test',
      }),
  })
  .parse(process.env)

export default defineConfig({
  apiKey: TOOL_FORGE_API_KEY,
})

The configuration validates your API key format using Zod and exports it for the SDK to use.

Create your first tool

Create a tools directory and add your first tool:

mkdir tools

Create tools/hello-world.ts:

import { defineTool } from '@toolforge-js/sdk/components'
import * as z from 'zod'

export default defineTool({
  name: 'Hello World',
  description: 'A simple tool that greets the user',
  handler: async ({ io }) => {
    const name = await io.textInput({
      label: 'Enter your name',
      validationSchema: z.string().min(1, 'Name is required'),
    })

    return `Hello, ${name} from Tool Forge!`
  },
})

Create .gitignore

Create a .gitignore file to exclude unnecessary files from version control:

# Dependencies
node_modules/

# Environment variables
.env
.env.local
.env.*.local

# Tool Forge
.tf-logs/

# TypeScript
*.tsbuildinfo

# Turbo
.turbo/

# IDE
.idea/
.vscode/
*.swp
*.swo

# OS
.DS_Store
Thumbs.db

Final Project Structure

Your project should now look like this:

.env

.gitignore

package.json

toolforge.config.ts

tsconfig.json

hello-world.ts

Run Your Project

Install dependencies and start the development server:

bun install
bun dev

Your tools are now connected to Tool Forge! Open your Tool Forge dashboard to interact with them.

Adding More Tools

To add more tools, create additional files in the tools directory. Each file should export a default tool definition using defineTool().

You can also organize tools into subdirectories: