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

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

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-agent.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-agent.ts

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

Next step

Your First Agent — Build a real agent with tools and composition in 5 minutes.