Openbot

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

What It Does

• Runs a local agent server.
• Stores channels, threads, agents, plugins, config, and variables under ~/.openbot.
• Ships with a built-in system agent named Lolly.
• Loads custom agents from ~/.openbot/agents/<agent-id>/AGENT.md.
• Loads shared plugins from ~/.openbot/plugins.
• Streams events to clients with Server-Sent Events.

Quick Start

Requires Node.js >=20.12.0.

npm i -g openbot
openbot start

The server listens on http://localhost:4132 by default. Set a different port with:

openbot start --port 3000

For local development:

npm install
npm run dev

API

OpenBot intentionally keeps the public API small:

• GET /api/events opens an SSE stream for a channel or thread.
• POST /api/publish publishes an event into the harness.
• GET /api/state runs an event and returns the resulting events without opening a stream.

Example:

curl -X POST http://localhost:4132/api/publish \
  -H "content-type: application/json" \
  -d '{"type":"user:input","data":{"content":"hello"}}'

Useful context can be passed as headers, query params, or body fields:

• channelId
• threadId
• agentId
• runId

Configuration

OpenBot reads config from ~/.openbot/config.json.

{
  "port": 4132,
  "baseDir": "~/.openbot",
  "model": "openai/gpt-4o-mini",
  "mcpServers": []
}

Variables are read from ~/.openbot/variables.json and applied to the server process environment on startup.

Agents

The built-in system agent is always available. Add a custom agent by creating ~/.openbot/agents/<agent-id>/AGENT.md:

---
name: Researcher
description: Helps collect and summarize information.
runtime:
  name: ai-sdk
  config:
    model: openai/gpt-4o-mini
plugins:
  - name: storage
---

You are a careful research assistant.
Summarize findings clearly and cite sources when available.

Agents are discovered from disk when the server starts.

Plugins

Built-in plugins include:

• storage
• delegation
• mcp
• ui
• ai-sdk

Shared plugins can be placed in ~/.openbot/plugins and referenced by agents.

Project Layout

• src/app: CLI, server, event types, and app config.
• src/harness: agent harness, orchestration, process, and MCP runtime helpers.
• src/plugins: built-in plugin implementations.
• src/services: local storage service.
• src/registry: plugin registry.
• docs: architecture, agents, and plugin notes.

Learn More

• Architecture
• Agents
• Plugins

Need help or want to share feedback? Join the community on Discord: https://discord.gg/XYYXvN2ebB