GitHub - meetopenbot/openbot: Meet OpenBot. OS for Agents

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 OpenBot (orchestrator, includes the LLM runtime).
Ships with a built-in state agent for deterministic, non-LLM handling (e.g. /api/state defaults).
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:

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 (defaults to the built-in system agent with the OpenBot / LLM runtime).
GET /api/state runs an event and returns the resulting events without opening a stream (defaults to the built-in state agent: storage-oriented plugins, no LLM).

You can override the agent with agentId (header, query, or body where applicable).

Example:

curl -X POST http://localhost:4132/api/publish \
  -H "content-type: application/json" \
  -d '{"type":"agent:invoke","data":{"role":"user","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"
}

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.
plugins:
  - id: openbot
    config:
      model: openai/gpt-4o-mini
  - id: 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-tools
delegation
openbot

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: orchestration and process helpers.
src/plugins: built-in plugin implementations.
src/services: local storage service.
src/registry: plugin registry.
docs: architecture, agents, and plugin notes.

Learn More

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

推荐订阅源

Show HN