Skip to content
OpenBot Docs

Introduction

OpenBot is a local-first harness for running AI agents. It is designed around a small event API, local file storage, and a Melony-powered runtime that routes events to agents and plugins.

What is OpenBot?

Section titled “What is OpenBot?”

OpenBot provides a robust environment for AI agents to operate locally on your machine. It handles the complexities of event routing, state management, and plugin integration, allowing you to focus on building intelligent agent behaviors.

Key Features

Section titled “Key Features”
  • Local-First: All data, including channels, threads, agents, and configuration, is stored locally in ~/.openbot.
  • Event-Driven: Built on a small, powerful event API for seamless communication between components.
  • Extensible: Easily add custom agents and plugins to extend functionality.
  • Built-in Agent: Ships with OpenBot, a system agent ready to assist.
  • SSE Streaming: Streams events to clients in real-time using Server-Sent Events (browser clients include OpenBot.one; see OpenBot.one client).

Quick Start

Section titled “Quick Start”

To get started with OpenBot, you can install it via npm:

Terminal window
npm i -g openbot
openbot start

By default, the server listens on http://localhost:4132.

For a graphical client that connects to that runtime, use OpenBot.one — see OpenBot.one client.

Core Concepts

Section titled “Core Concepts”

Channels and threads

Section titled “Channels and threads”

Channels define workspace-style context (spec, state, tooling scope); each conversation happens inside a thread within a channel. OpenBot does not support channel-wide chat — channelId and threadId are both required for messaging flows with GET /api/events and POST /api/publish. See Your First Channel.

Agents

Section titled “Agents”

Agents are the primary actors in OpenBot. They process events and can emit new ones. You can define custom agents using an AGENT.md file. For a walk-through, see Your First Agent.

Plugins

Section titled “Plugins”

Plugins extend the capabilities of agents. They can handle specific event types, interact with storage, or provide tools for agents to use.

Events

Section titled “Events”

Everything in OpenBot happens through events. Whether it’s user input, agent output, or internal system changes, events are the lifeblood of the harness.