Installation

Get baleybots running in under 3 minutes.

Prerequisites

• Node.js 18+ (or Bun)
• An API key from OpenAI or Anthropic

1. Configure the package registry

Baleybots is currently published to GitHub Packages. This requires a one-time auth setup.

Create or edit ~/.npmrc and add:

@baleybots:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

Replace YOUR_GITHUB_TOKEN with a GitHub personal access token that has read:packages scope.

Moving to public npm

We're working on publishing to the public npm registry. Once that's done, this step goes away entirely.

2. Install

Install core, an AI SDK provider package, and Zod:

npm install @baleybots/core @ai-sdk/openai zod

Using Anthropic instead?

Swap @ai-sdk/openai for @ai-sdk/anthropic:

npm install @baleybots/core @ai-sdk/anthropic zod

Baleybots routes all LLM calls through AI SDK v7 (ai ^7.0.0). You need at least one @ai-sdk/* provider package for the models you plan to use.

3. Set your API key

export OPENAI_API_KEY="sk-..."
# or
export ANTHROPIC_API_KEY="sk-ant-..."

4. Verify it works

Create a file called test-processor.ts and paste:

import { Baleybot } from '@baleybots/core';

const bot = Baleybot.create({
  name: 'test',
  goal: 'Say hello and confirm you are working',
});

const result = await bot.process('Hi! Are you working?');
console.log(result);

Run it:

npx tsx test-processor.ts

You should see a friendly response. If you do, you're ready.

Next step

Quickstart — Build a processor with structured output, tools, and composition in 5 minutes.