Brain v2 – A minimal and extensible agent server for building agent applications

---

▄████▄ | __ \ __ \ _ |_ | | | ▄██▄██▄██▄ | __ < < || || | ▀▀ ▀▀ |/||||___|__||

A minimal and extensible agent server for building agent applications

Quickstart · Docs · API reference · Examples · Roadmap

Brain is a single application you deploy as a service to run the agents behind your products. It's an open-source alternative to Claude Managed Agents and the OpenAI Agents SDK, running on your own infrastructure with the models you choose.

Brain gives you session-oriented primitives for building agents. Your application starts sessions, streams what the agent does, and connects tools from application code and services. Brain runs the agent loop and records each session's history, so you can replay a session or recover it after a failure.

import { Brain } from "@aexhq/brain";

const brain = new Brain("http://127.0.0.1:8080", process.env.BRAIN_API_KEY!); const session = await brain.create({ harness: "pi", config: { model: "openai/gpt-4.1-mini", tools: ["echo"] } }); const input = await brain.send(session.id, { type: "user.message", text: "Use echo to say hello." });

for await (const event of brain.observe(session.id)) { const data = event.data as { text?: string; message?: string; status?: string }; if (event.type === "assistant.message") console.log(data.text); if (event.input_id !== input.id) continue; if (event.type === "session.error") throw new Error(data.message); if (event.type === "session.status" && data.status === "idle") break; }

The echo tool comes from the example tool server, a small service you run next to Brain.

Choose where tools run. Compose functions into your application, attach client functions, or connect services in any language.

Decide what the agent can do. The model sees exactly the tools you enable for each session.

Reconnect at any time. Sessions keep running when clients disconnect and survive server restarts, so any client can reconnect and continue from the last event it read.

Move sessions between servers. Checkpoints let another server recover a session after a failure or take it over in a planned handoff.

Isolate every customer. Keep each customer's sessions and tools separate, and give each client only the access it needs.

Run it yourself. Brain is open source and self-hosted, with structured logs and OpenTelemetry traces and metrics.

Get started

You need Go 1.26+, Node.js 24+, and an API key from a model provider such as OpenAI.

Start Brain. Clone the repository, build the Pi harness, and start the server:

git clone https://github.com/aexhq/brain.git cd brain npm --prefix runners/pi ci --ignore-scripts npm --prefix runners/pi run build export BRAIN_API_KEY="replace-with-a-random-token-of-at-least-24-bytes" export OPENAI_API_KEY="your-provider-key" go run ./cmd/brain -config examples/local.json

To run the published container image instead, follow Run Brain in a container.

Install an SDK. Add the SDK to your application with npm install @aexhq/brain or pip install aex-brain. Client applications need neither a checkout nor Go.

Run the example session. In a second terminal in the checkout, install the SDK for the example and start a session:

export BRAIN_API_KEY="replace-with-a-random-token-of-at-least-24-bytes" npm install --no-save --package-lock=false @aexhq/brain@2.1.0 node examples/session.mjs "Explain what makes a good agent tool."

The Quickstart walks through the same steps in PowerShell, Python, and cURL.

I want to… Read

Run my first session Quickstart

Understand how Brain runs a session Architecture

Stream events, interrupt turns, and resume sessions Session lifecycle

Write a tool service Distributed tools

Connect a remote MCP server MCP tools

Issue tokens and isolate customers Authentication

Back up sessions and move them between servers Persistence & recovery

Deploy and monitor Brain Operations & observability

Call Brain from my backend TypeScript SDK or Python SDK

Look up routes and config fields HTTP API and Host configuration

See what's coming next Roadmap

Build with a coding agent

Give your coding agent Brain's docs as plain text: llms-full.txt has every page in one file, and llms.txt lists the pages.

Install the dependencies and run every local check before you open a pull request. The checks need Go 1.26+, Node.js 24+, and Python 3.11+.

node scripts/setup.mjs node scripts/check.mjs

Development & verification covers what the checks run, how CI publishes releases, and how to preview the docs.

Docs · Roadmap · Architecture · License · Issues