Multi-agent bots
from a single package.
Bot in a Box is an open-source TypeScript framework for building multi-agent bots. Define agents, wire up channels, and let the framework handle orchestration, scheduling, budget controls, and security.
What it does
Multi-Agent Orchestration
Define agents with different models, roles, and execution adapters. Task queue with priority scheduling (1–10), retry policies with exponential backoff, and followup chains with depth guards.
LLM Provider Abstraction
Swap between Anthropic, OpenAI, and Ollama with a unified interface. Model aliases (fast, smart, balanced), purpose-based routing, and fallback chains. Switch providers without changing application code.
Channel Adapters
Connect agents to Slack, Discord, and webhooks. Each agent can listen on multiple channels. Incoming messages are routed, parsed, and dispatched automatically. Voice message transcription via whisper.cpp.
Workflow Engine
Multi-step DAG workflows with dependency resolution and parallel execution. Context interpolation between steps, per-step failure policies (abort, skip, retry), and cycle detection.
Budget Controls
Per-agent and global cost tracking with configurable limits. Warning thresholds at any percentage, hard stops when limits are reached. Every token is counted and priced by model.
Security
Input sanitization, field length enforcement, audit logging, and HMAC webhook verification. Protected tables for users and secrets. Path traversal prevention and ReDoS-safe parsing.
Quick start
Set up in minutes
Install the package, create a database, register an agent, and start processing tasks. The framework handles the orchestration loop, cost tracking, and message routing.
1. Install
One package, all batteries included. Providers are peer dependencies — install only what you use.
2. Configure
Define agents, channels, and providers in YAML or TypeScript. Environment variables interpolated automatically.
3. Run
The framework boots your agents, connects channels, starts the scheduler, and processes the task queue.
import {
HookBus,
DataStore,
defineCoreTables,
AgentRegistry,
TaskQueue,
RunManager,
ProviderRegistry,
ModelRouter,
ApiExecutionAdapter,
} from 'botinabox';
import createAnthropicProvider
from 'botinabox/anthropic';
// 1. Boot
const hooks = new HookBus();
const db = new DataStore({
dbPath: './data/bot.db',
wal: true,
hooks,
});
defineCoreTables(db);
await db.init();
// 2. Providers
const providers = new ProviderRegistry();
providers.register(
createAnthropicProvider({
apiKey: process.env.ANTHROPIC_API_KEY!,
})
);
const router = new ModelRouter(providers, {
default: 'claude-sonnet-4-6',
});
// 3. Orchestrate
const agents = new AgentRegistry(db, hooks);
const tasks = new TaskQueue(db, hooks);
const runs = new RunManager(db, hooks);
const agentId = await agents.register({
slug: 'assistant',
name: 'Assistant',
adapter: 'api',
});
await tasks.create({
title: 'Summarize the Q4 report',
assignee_id: agentId,
priority: 3,
});Modular imports
Install only what you need
The core package has zero heavy dependencies. LLM providers, channel adapters, and connectors are separate subpath exports with their own peer dependencies.
botinabox
Core framework — hooks, data, orchestration, security
botinabox/anthropic
Anthropic Claude provider
botinabox/openai
OpenAI GPT provider
botinabox/ollama
Ollama local model provider
botinabox/slack
Slack channel adapter + voice
botinabox/discord
Discord channel adapter
botinabox/webhook
Webhook adapter + HMAC server
botinabox/google
Gmail & Calendar connectors
Your agents. Your channels. Your workflows.
Bot in a Box runs wherever Node.js runs. No cloud lock-in, no vendor dependencies, no subscription fees. Just an npm package and a SQLite database.