BRIAN

A self-hosted agent runtime. Model, loop, tools, memory, permissions.

pip-installable as brian-core 2.0.0rc37. The command is brian.

macOS / Linux

curl -fsSL https://heybrian.ai/install | bash

cmd

powershell -c "irm https://heybrian.ai/install.ps1 | iex"

PowerShell

irm https://heybrian.ai/install.ps1 | iex

First brian in a terminal asks for a provider, credentials, and model, seeds ~/.brian/SOUL.md if missing, live-pings the provider, then asks what to call you. brian doctor diagnoses the home without starting a session. Pipe install stays non-interactive. Bring your own LLM key. The wheel is code — memory and sessions start empty, in ~/.brian.

What you get

BrianClient talks to the HTTP 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"):
    ...

Twelve providers (Anthropic, OpenAI, Gemini, Bedrock, OpenRouter, DeepSeek, Mistral, xAI, Ollama, LM Studio, plus generic gateways). Seventy tools: shell, files, browser, desktop, web, media, MCP, subagents, durable runs that survive a crash.

From this repo

Git, Python 3.11+, uv. Code lives under src/brian_core.

git clone https://github.com/mrgizmo212/Brian.git
cd Brian
uv sync
uv run brian --help
uv run brian
uv run brian "list python files"

Optional extras: providers, hosted, desktop (screen control).

Modes

uv run brian                         # TUI
uv run brian --repl                  # CLI prompt
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
uv run brian --api
uv run brian --scheduler
uv run brian --heartbeat-only
uv run brian --learning-graph
uv run brian --version
uv run brian doctor

One 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."}]}'

Self-host with Docker: deploy/README.md.

Bring your own machine

Let heybrian chats run bash, file reads/writes/edits, undo, glob and grep on your own laptop or server, inside an OS sandbox limited to the folders you choose. The helper only connects out to heybrian over HTTPS; nothing listens on your machine. Your admin turns it on in Admin → Configuration → machines.enabled.

Command output streams live to the chat while a command runs. When a command stops to ask a question ("Overwrite? (y/n)"), you answer it on the question card in the chat.

Install, pair once, then start the helper:

# macOS
brew install pipx && pipx install 'brian-core[desktop]==2.0.0rc37'
# Linux
sudo apt install -y bubblewrap pipx && pipx install 'brian-core==2.0.0rc37'
# Windows (PowerShell) — also follow srt's one-time restricted-account setup
py -m pip install --user pipx; py -m pipx install 'brian-core==2.0.0rc37'; npm install -g @anthropic-ai/sandbox-runtime

brian pair                                  # shows a code; enter it in heybrian → Settings → BRIAN → Your machines
brian worker --dir ~/code/project           # add more --dir flags for more folders (max 16)
brian machine status                        # pairing, sandbox and git token state
brian machine unpair                        # delete the local credential (also: brian unpair)

Sandbox. Every command runs in srt (Anthropic sandbox-runtime) when it is on PATH, otherwise bwrap on Linux or sandbox-exec on macOS. Windows needs srt. With none of them the helper exits with code 4 and never runs a command unsandboxed. Commands can write only to your folders and a private scratch dir, cannot read the rest of your home folder or the helper's credential folder, cannot open Unix sockets (Linux), and have no network unless you allow it. File reads, writes and edits run in the helper itself, confined to the folders (.., absolute paths and symlinks that leave a folder are refused). Every write keeps an undo snapshot under the helper's folder.

Screen control (--screen, off by default, and only when your admin enabled machines.screenControl.enabled). You grant each app in Settings → Your machines as full, click-only or view-only; apps you have not granted are refused, and password managers are always view-only. Every screen action asks you first unless you turn on "Let BRIAN act without asking". BRIAN refuses to type into password, sign-in and payment windows or password fields, and never types card numbers. Move the pointer to the top-left corner to stop it at once. On macOS grant Screen Recording and Accessibility to your terminal in System Settings → Privacy & Security; on Linux an X11 session with xdotool is needed (Wayland is not supported).

Git identity. Commits made on the machine carry the agent's name as <agent> (BRIAN) and <agent>+brian@users.noreply.heybrian.ai. To let BRIAN push, store a token locally (brian machine git-token set, read from stdin, never from the command line; clear removes it). It is saved as git-token (mode 0600) next to machine.json, handed to git through a per-command credential helper, never sent to heybrian or the model, and masked as *** in every output. Pushing also needs network, e.g. --allow-domain github.com.

Files: ~/.config/brian/machine.json (macOS/Linux) or %APPDATA%\brian\machine.json (Windows), mode 0600; BRIAN_MACHINE_HOME overrides the folder. Exit codes: 0 ok, 2 not paired, 3 removed in heybrian (the credential is deleted), 4 no OS sandbox, 5 turned off by your admin.

Config

Settings live in ~/.brian/.env (or BRIAN_ENV_FILE). Names are in env.example. Required: PROVIDER, MODEL, and that provider's key.

Override the home directory with BRIAN_HOME.

Docs

• docs/CAPABILITIES.md — what it can do (Memory Trio: flush-before-compact, stub summary, skill proposals; Engine parity 2026-09-20: real token counting, file-tool fence, default step cap, one durable path, surfaced transcript failures, CI)
• docs/brian-operator.md — SOUL, skills, MCP, session save, compaction flags
• AGENTS.md — working in this repo (module index, Memory Trio table, Engine parity table)
• docs/core-v2/package-migration.md — package, CLI, and install reference

License

MIT License. Copyright 2026 TTG AI LLC. See LICENSE and NOTICE.