Brain

What it is

Brain is a tiny agent runtime that runs sessions: it holds the conversation, decides what happens next, calls the model, hands out tool calls, and journals every step — in about 7,300 lines of Rust. The agent loop, the model, the tools, and the environment they run in all plug in and are yours to replace, and the packages we ship use the same interface you would — nothing built in gets a shortcut.

The name comes from Anthropic's split of the brain from the hands. Brain is the brain: it decides. Environments are the hands — a sandbox, a browser, your backend, someone's laptop — where the work actually happens. The small-and-extensible shape follows Pi.

Features

Tools run wherever you want

Brain never executes tool code. It calls whatever you bind the tool to — a sandbox VM, a browser tab driving the DOM, your own backend, the user's laptop — and one session can span several at once.

Built for low overhead

Session state lives in memory and the journal is written behind the turn: 25 ms round trips, 0.6 ms session creation, ~14 KiB per idle session. The numbers are measured, and CI holds them.

Any model

Anthropic and OpenAI wire formats, gateways, your own keys. The model is pinned when the session starts, so nothing swaps it out mid-conversation.

Any agent loop

Pi, Codex-style, or your own — and sessions can create sessions for subagent work. Brain is not an agent; it is what agents run on, and the loop we ship has no privileges yours doesn't.

The loop is sealed off

An agent loop compiles to WebAssembly and runs in a standalone runtime. No network, no filesystem, no secrets, no clock — Brain performs every effect.

Any language

Agent loops compile to WebAssembly. Tools and environments talk to Brain over plain HTTP. One tool in Rust and another in Node, in the same session.

Everything is an event log

A session is an ordered, replayable log of what happened, and a running turn streams the model's output token by token. Live streaming drops rather than stalling a turn.

Conversations outlive processes

Sessions rebuild from their own journal on restart, an interrupted turn says so with a turn_interrupted event, and a conversation can be handed to a new session as history — on another machine if you like.

Server or library

Run the binary — the journal is the only thing it writes — or embed the brain crate in your own Rust service and supply your own storage and transport.

Benchmark

The benchmark measures the engine, not a model: every subject is driven through its own public API on the same machine, against the same scripted model, so nothing here is model latency. Medians on an AWS c7g.xlarge; the harness lives in the repository, so the numbers can be re-run rather than trusted.

Brain's first-token figure is an upper bound — under an instant scripted model the turn completes before a delta reaches the stream. Cold-start figures other than Brain's come from each project's own published numbers. The full charts, including OpenFang, CrewAI, and AutoGen, are in the repository README.

Architecture

Brain owns the session. Four kinds of component plug into it.

Roadmap

Shipped

Four-part runtime: agent loop, model, tool, environment

Shipped

WebAssembly agent loop pipeline

Shipped

Append-only segment log with best-effort restart recovery

Shipped

HTTP/SSE session API and the TypeScript SDK

Shipped

Remote environment contract with the official adapters

Shipped

End-to-end benchmark harness against other runtimes

In progress

Cross-session isolation test

In progress

A frozen v1 API and tagged releases

Next

File access and workspace sync

Next

crates.io publication

Later

Sessions spread across machines, sharing environments

Later

Checkpoint and restore

Later

Custom images, scoped credentials, network metering

Getting started

Drive a session from TypeScript:

npm install @aexhq/brain @aexhq/brain-pi

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

const brain = new Brain({ baseUrl: "http://127.0.0.1:8080" });

const session = await brain.sessions.create({
  model: {
    provider: "openai",
    name: "gpt-5-mini",
    apiKey: process.env.OPENAI_API_KEY!,
  },
  brain: pi(),
  system: "Answer briefly and directly.",
});

await session.send("Explain what a session runtime does, in one sentence.");
for await (const event of session.events()) console.log(event);

await session.end();
await session.delete();

Or run the server first:

docker run --rm -p 8080:8080 -v brain-data:/var/lib/brain ghcr.io/aexhq/brain:latest

Guides, concepts, and the generated API reference are in the documentation.

License

MIT. The source is at github.com/aexhq/brain.