BRIAN

A self-hosted AI harness: a model plus the loop, tools, memory, and permissions that turn it into an agent you can actually run.

Package: brian-core 2.0.0rc1. Command: brian. agent is a silent alias of the same program. Code lives under src/brian_core.

This checkout is /srv/brian on branch brian. It is not the live operator at /srv/agent (ab212.io) and not HeyBrian. Do not copy those trees’ .env, memory/, or sessions here.

Install

curl -LsSf https://astral.sh/uv/install.sh | sh && uv tool install brian-core && brian

Or run scripts/install.sh. First run asks for a provider and key, writes ~/.brian/.env (mode 0600), then starts the REPL. Type brian from any folder — keys, USER.md, and sessions live in ~/.brian. You still need your own LLM key. The wheel is code only; a stranger’s brain starts blank.

Three doors

BrianClient is an HTTP helper for the API. It is not the Agent SDK.

from brian_core.sdk import run, stream

print(run("list python files"))
for event in stream("list python files"):
    ...

Run from this repo

Needs Git, Python 3.11+, and uv. Product home is still ~/.brian (override with BRIAN_HOME or BRIAN_ENV_FILE). Tests may set MEMORY_DIR.

cd /srv/brian          # or clone the repo and check out this branch
uv sync
uv run brian --help
uv run brian           # first run: provider + key into ~/.brian/.env
uv run brian "list python files"   # one shot

Package layout is src/brian_core. Optional extras: providers, hosted.

Modes

uv run brian                         # interactive REPL
uv run brian "do this"               # one shot
uv run brian --continue              # last session
uv run brian --resume <session-id>
uv run brian --fork-session <id>
uv run brian --tui                   # full-screen terminal UI
uv run brian --api                   # FastAPI server
uv run brian --scheduler             # durable job worker
uv run brian --heartbeat-only        # memory maintenance, then exit
uv run brian --learning-graph
uv run brian --version
uv run agent --help                  # same CLI; do not teach this name

One execution mode per invocation. --api requires API_SERVER_KEY.

HTTP API

uv run brian --api
curl -fsS http://127.0.0.1:8000/health
curl -fsS http://127.0.0.1:8000/v1/chat/completions \
  -H "Authorization: Bearer $API_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"agent","messages":[{"role":"user","content":"Say hello."}]}'

Bearer API_SERVER_KEY on almost every route. Public: /health, /v1/health, throttled POST /api/web/login, Twilio-signed POST /hooks/twilio/sms.

Operator detail (SOUL, skills, MCP, session save): docs/brian-operator.md. What it can do in plain English: docs/CAPABILITIES.md.

Config

All settings are .env under ~/.brian (or BRIAN_ENV_FILE). Names are in env.example. Required: PROVIDER, MODEL, and the key for that provider.

On first interactive start, if ~/.brian/memory/USER.md is empty, the CLI asks a few profile questions after keys work.

What this tree is for

Build the product here. Leave /srv/agent as production. Tests that need config use a local env, never the live one.

Working rules for agents: AGENTS.md.