OpenBot: a local-first agent server on port 4132

What OpenBot solves, and for whom

Most assistant frameworks assume a hosted backend. OpenBot takes the opposite position: the agent runs on your machine, and its memory is a directory. The README calls it a "local-first harness for running AI agents" and lists what that means in practice. The server listens on port 4132. Channels, threads, agents, plugins and config are stored under ~/.openbot. Events reach clients over Server-Sent Events rather than a polling loop or a socket protocol.

The audience follows from that layout. If you are building a personal assistant that should keep its threads on your own disk, or you want to prototype an agent runtime without standing up a database and a queue, the shape fits. It is a TypeScript project with an npm bin, so the expected user is comfortable with Node and with editing files by hand. The topics on the repository (personal-assistant, data-ownership, your-own-ai-assistant) describe the same intent.

What it is not is a hosted product. There is no account, no sync layer and no managed storage described in the README. The trade is that you own the files and you also own the backups, the process supervision and the API keys.

How the event API and the Melony runtime fit together

The mechanism is an event bus wrapped in HTTP. Three endpoints are documented. GET /api/events is the SSE stream, scoped to a channel or a thread. POST /api/publish takes an event and defaults to the system agent. GET /api/state runs an event and returns the resulting events, defaulting to the state agent. Context travels through channelId, threadId, agentId and runId, which the README lists as both headers and fields.

The two built-in agents split the work by capability. The system agent is the LLM path: it uses the openbot plugin, which the README describes as an "LLM agent runtime with storage tools". The state agent is the deterministic path and explicitly runs without an LLM, which means reads of stored state do not cost a model call and do not depend on a provider being reachable. That split is the most interesting design decision in the repository. It gives you a way to inspect what an agent has stored without asking a model to summarize it.

Plugins are the extension unit, and only three ship in this edition: openbot, storage and ui. Storage handles channel and thread persistence; ui provides interactive widgets. The runtime underneath is Melony, pinned at ^0.3.7 in package.json, and the model layer is the Vercel AI SDK family (@ai-sdk/openai, @ai-sdk/anthropic, @ai-sdk/google, ai ^6.0.42). Custom agents are Markdown files with YAML front matter, parsed with gray-matter, loaded from ~/.openbot/agents/<agent-id>/AGENT.md.

Installing OpenBot and running a first agent call

The README requires Node.js >=20.12.0, and package.json enforces the same floor in its engines field. Install globally and start the server:

npm i -g openbot
openbot start

The server comes up on port 4132. Before starting, export a provider key. The README gives the OpenAI example:

export OPENAI_API_KEY=sk-...
openbot start

With the server running, publish an event. The README's own example posts an agent:invoke event to the publish endpoint with a user role and a content string:

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

Because publish defaults to the system agent, you should see the LLM path handle it. To define your own agent instead, create ~/.openbot/agents/<agent-id>/AGENT.md with front matter naming the plugins and the model:

---
name: Assistant
description: A helpful local assistant.
plugins:
  - id: openbot
    config:
      model: openai/gpt-4o-mini
  - id: storage
---

You are a careful assistant. Be concise and clear.

For working on the project itself rather than consuming it, the README lists npm install followed by npm run dev, which runs tsx watch src/app/cli.ts start.

Where OpenBot gets in your way

The README is short, and several things a production user needs are simply absent from it. There is no documented rollback, no migration path between versions, and no description of what happens to ~/.openbot when the storage plugin changes shape. The README also does not document authentication on the HTTP API. If you bind the server beyond localhost, nothing in the documentation tells you what protects /api/publish, so treat that as an open question to answer by reading src/ rather than assuming a default.

The scope of the licence is the sharper constraint. The README states that MIT applies to this repository through release v0.5.3, that code released under MIT before this archive remains MIT, and that newer work is not published here. Read that carefully before you plan around the project. The repository you are looking at is a snapshot with a licence boundary drawn on it, and the README does not describe how the published line relates to the archive.

Finally, the agent model is single-provider per agent. The front matter in the README example names one model under the openbot plugin config, so routing different tasks to different providers means defining different agents rather than configuring a fallback chain.

OpenBot compared with a client-side copilot framework

People searching for OpenBot often arrive from CopilotKit, and the two solve different halves of the problem. CopilotKit is a client-side layer: it puts assistant UI and in-app actions into a React application, and the application owns the backend. OpenBot is the opposite end. It is the server, the storage and the event bus, and it expects a client to connect to it over SSE on port 4132. If your problem is "my React app needs an assistant sidebar," OpenBot is not the tool. If your problem is "I want an agent whose threads live in files on my disk and whose API I can curl," the client framework is not the tool.

The other comparison the README invites is with the state agent against any LLM-backed assistant. Because the state agent performs deterministic storage reads with no model in the loop, it behaves like a query endpoint rather than a chat endpoint. That is a different reliability profile from anything that routes every read through a model call.

Maintenance, upgrades and the MIT boundary

The repository is not archived, and the last push was on 2026-07-07. The README's licence paragraph is the upgrade constraint that matters most: MIT applies to this repository through release v0.5.3, and newer work is not published here. Whatever ships after that boundary is not covered by the grant you get from this repository, so an upgrade path that leaves v0.5.3 is a licensing question, not just a version bump. That is not legal advice; it is a reading of the sentence the README puts under its own License heading, and it is the first thing to have someone qualified look at if you plan to build a product on top.

On the technical side, package.json pins the runtime to Node >=20.12.0 and depends on Melony ^0.3.7 and the AI SDK packages at their ^3.x and ^6.x ranges. Those caret ranges mean a fresh npm install can pull newer minor versions than the ones the snapshot was built against. If you need reproducibility, install from the pnpm-lock.yaml in the repository rather than resolving fresh ranges.

Editorial conclusion

Adopt OpenBot if you want a small, self-hosted agent server whose channels, threads, agents and config live in plain files under ~/.openbot and whose clients speak a three-endpoint HTTP API. Do not adopt it if you need a published release line, documented rollback, or a stable scope for the MIT grant, because the README limits MIT to this repository through v0.5.3 and states that newer work is not published here. Before writing anything against it, verify three things: that npm i -g openbot resolves to a version matching package.json 0.5.3, that your Node build is at least 20.12.0, and that the AGENT.md front matter you write is parsed by the gray-matter version the project pins.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. meetopenbot/openbot on GitHub
4. Project website
5. README