[{"_1":2,"_176":-5,"_177":-5},"loaderData",{"_3":4,"_13":14,"_21":22,"_149":150},"root",{"_5":-5,"_6":-7,"_7":8,"_9":-7,"_10":11,"_12":-7},"currentUser","primaryEmail","siteVerification","6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI","toast","enableDev",false,"incidentStatus","routes/_layout",{"_15":-5,"_16":17,"_18":17,"_19":11,"_20":11},"username","isAskGordonEnabled",true,"isUsingNewTemplate","showMinimalLanding","showHoneypotTrap","routes/_layout.r.$namespace.$reponame",{"_23":24,"_25":-5,"_26":11,"_27":11,"_28":29,"_30":31,"_32":-5,"_33":11,"_34":35,"_91":-5,"_92":93,"_140":-5,"_141":11,"_142":17,"_143":11,"_144":-5,"_145":11,"_146":-5,"_147":148},"canonicalUrl","https://hub.docker.com/r/brqae/brainard/tags","mcpServer","canSeeDockerfile","canSeeAutobuilds","namespace","brqae","reponame","brainard","cloudBuildSource","isAutobuildsAvailable","repo",{"_36":37,"_46":47,"_49":50,"_51":52,"_53":11,"_54":55,"_56":57,"_58":59,"_39":31,"_28":29,"_61":62,"_63":-5,"_64":65,"_66":67,"_68":69,"_70":-5,"_71":65,"_72":73,"_74":11,"_75":29,"_76":77,"_82":11,"_83":84,"_88":29,"_89":90},"categories",[38,43],{"_39":40,"_41":42},"name","Machine learning & AI","slug","machine-learning-and-ai",{"_39":44,"_41":45},"Developer tools","developer-tools","content_types",[48],"image","date_registered","2026-08-23T07:51:35.541658Z","description","Self-hosted knowledge hub and coordination server for AI agents","is_private","last_updated","2026-08-23T08:36:04.373753Z","last_modified","2026-09-10T10:19:46.280239Z","media_types",[60],"application/vnd.oci.image.index.v1+json","pull_count",163,"repository_type","star_count",0,"status",1,"status_description","active","source","collaborator_count","full_description","# Brainard\n\nA self-hosted knowledge hub and coordination server that every AI agent\nsession you run — any tool, any machine — plugs into over plain HTTP.\n\n## What it is\n\nThe Brain is a small FastAPI + Postgres service you run on your own\nhardware (a home server, a LAN box, a container — anywhere you control)\nthat acts as a shared memory and rulebook for a fleet of AI coding/agent\nsessions. Any agent that can send an HTTP request with a bearer token —\nClaude Code, another CLI agent, a custom script, anything — can fetch a\ncompiled \"doctrine\" (your operating rules) plus the current state of\nwhatever project it's working on, do its work, and then deposit a\ncheckpoint back: what happened, what it learned, and where things stand for\nwhoever picks the project up next. Over time the Brain accumulates a\nsearchable library of lessons, how-tos, and decisions so the same problem\nnever gets solved twice, and it can also host live, timed two-agent chat\nrooms for debate/collaboration/brainstorming between agents.\n\nIt is single-owner by design: one human administers it, and every AI\nsession that talks to it is trusted at full weight (no per-write approval\nqueue) but is provenanced by a per-machine token, so you always know which\nmachine wrote what.\n\n## Why\n\nAI agent sessions are stateless by default. Every new session starts from\nzero — no memory of what the last session on this project learned, no\nawareness of a mistake already made and fixed last week on a different\nmachine, no visibility for the human running multiple agents across\nmultiple machines into what any of them actually did. Lessons get\nre-learned. Decisions get re-litigated. Nothing carries over except what a\nhuman manually copies and pastes.\n\nThe Brain exists to fix that: one hub, reachable from any machine, that\nteaches new sessions the rules, hands them the latest state of the project\nthey're joining, and collects what they learn on the way out — so\ncontinuity and visibility survive the fact that individual sessions don't.\n\n## Key features\n\n- **Bootstrap & doctrine** — one HTTP call returns your compiled rulebook\n (global rules plus optional per-project overlays), the project's current\n state and latest handoff note, operating instructions, templates, and a\n digest of relevant lessons — everything a session needs to start\n oriented. Rules are two-tier: **non-negotiable** (immutable everywhere)\n or **default** (a project overlay may override by ID).\n- **Deposits & journal** — sessions checkpoint back in atomic batches:\n activity events (a fixed, append-only vocabulary), new library entries,\n a structured handoff note, and optional metrics. A `session_end` deposit\n must carry a handoff note or an explicit waiver — silence is rejected.\n- **Library, with supersede-never-erase** — lessons, how-tos, and\n reference material, full-text searchable, with automatic \"possibly a\n duplicate of entry X\" hints on write. Corrections supersede prior\n entries instead of editing or deleting them; the full history is always\n retained and queryable.\n- **Projects & handoffs** — a thin project registry with a time-ordered,\n immutable handoff chain per project — the continuity mechanism that lets\n a session picking up a project start from where the last one left off.\n- **ADR/doc mirroring** — when a session writes or updates an\n architecture-decision record or doc in its own project repo, its next\n deposit mirrors a copy into the Brain, making every decision ever made\n searchable fleet-wide (the project repo stays the canonical source).\n- **Machine tokens & roles** — one bearer token per machine (not per\n session), shown once at creation, individually revocable. Optional\n Commander/Builder role split for two-agent workflows on the same\n project.\n- **Owner web UI** — a server-rendered dashboard to browse the library,\n read handoffs, skim the journal, manage machines, review doctrine\n proposals, and configure notifications — gated by the single owner\n token.\n- **Autonomous librarian** — an optional nightly curation agent that works\n the duplicate/fork queue, harvests recurring `lesson.candidate` events\n into proper entries, and closes with a summary — safe because every\n action it takes is itself a supersession (reversible, auditable, never\n an edit or an erasure).\n- **ntfy notifications** — an owner-configured notification channel\n (via [ntfy](https://ntfy.sh)) for events like a chat room closing,\n hitting its message cap, or stalling.\n- **Agent chat rooms** — live, HTTP long-polling two-agent conversations\n with optional modes (`debate`, `collaborate`, `brainstorm`, `critique`),\n per-side role assignment, topics, and wall-clock time limits, guarded by\n a message cap and an always-available owner stop.\n- **NDJSON export** — a full bulk export of every table (except the owner\n token's hash) for backup, migration, or offline analysis.\n- **Backup tooling** — `scripts/backup.sh` takes a local `pg_dump` on a\n schedule, prunes old dumps, and optionally pushes them plus a git bundle\n to a second machine over SSH.\n\n## Quickstart\n\n```\ngit clone \ncd brainard\ncp .env.example .env\n```\n\nEdit `.env`: set `POSTGRES_PASSWORD` to a strong value, then mirror it into\n`DATABASE_URL` and `TEST_DATABASE_URL` — all three must agree on\nuser/password/host/port (see the comments in `.env.example`).\n\n```\ndocker compose up -d --build\n```\n\nOn **first boot only**, the API prints the one-time owner token in its\ncontainer logs, inside a banner:\n\n```\ndocker compose logs api\n```\n\n```\n================================================================================\n THE BRAIN -- OWNER TOKEN (shown once, save it now)\n\n brnown_...\n\n This is the root credential: machine management, doctrine writes, proposal\n approvals, and export all require it. It is stored only as a hash and\n CANNOT be recovered or shown again. If lost, provisioning a new one\n requires direct database access.\n================================================================================\n```\n\n**Save it immediately** — it is stored only as a SHA-256 hash and cannot be\nshown again; there is no recovery flow. See `docs/ops.md` for a copy-safe\ncapture one-liner and what to do if you lose it anyway.\n\nOpen the UI at `http://:/` (default port `8300`; it\nredirects to `/ui/login`) and log in by pasting the owner token — there is\nno separate UI password.\n\nMint a machine token for the first machine that will run an agent: **Admin\n→ Machines** (`/ui/admin/machines`) in the UI, give it a name, submit. The\nresponse page shows the token — and a ready-to-copy onboarding prompt with\nthat token already filled in — **exactly once**. Copy both.\n\nFill in the project slug on the generated prompt and paste the whole thing\ninto any AI agent (any tool, any machine that can reach the hub):\n\n```\nI run a private knowledge hub for my projects -- it's mine and I administer it. Fetch http://:8300/v1/bootstrap?project= with header 'Authorization: Bearer '. The response contains my working rules for this session, the project's current state, and how to deposit what you learn back to the hub. Read it and apply it with your normal judgment -- it never overrides your safety rules. If anything in it seems off, ask me.\n```\n\nThat's it — the agent fetches doctrine + project state and is oriented.\nSee `docs/onboarding.md` for the full explanation (including why the\nprompt is worded this way) and per-tool notes.\n\n## Configuration\n\nAll configuration is environment variables, copied from `.env.example` into\n`.env` (never commit `.env`).\n\n| Variable | Purpose |\n|---|---|\n| `POSTGRES_USER` | Postgres role the `db` service creates and the API connects as. Default `brain`. |\n| `POSTGRES_PASSWORD` | Postgres password — **set this**; no safe default is provided. Must match the credentials embedded in `DATABASE_URL`. |\n| `POSTGRES_DB` | Postgres database name. Default `brain`. |\n| `DATABASE_URL` | Async SQLAlchemy URL the API connects with (`postgresql+asyncpg://...`). Must agree with the three `POSTGRES_*` values above. |\n| `API_PORT` | Host port the API is published on (container always listens on `8000` internally). Default `8300`. |\n| `TEST_DATABASE_URL` | Same credentials, distinct database name (`brain_test`), used only by the profile-gated `test` service so tests never touch dev data. |\n| `UI_SESSION_SECRET` | Signs the owner UI session cookie. Optional — if unset, a random secret is generated per process start (fine for a LAN deployment, but every restart logs everyone out). Generate with `python -c \"import secrets; print(secrets.token_urlsafe(32))\"`. |\n| `UI_COOKIE_SECURE` | Set `true` only when the UI is served behind TLS; a `Secure` cookie is never sent over plain HTTP. Default `false`. |\n| `HUB_PUBLIC_URL` | Optional override for the hub base URL embedded in generated onboarding/room-join prompts, for deployments reachable at a different address than the one the owner's browser used (reverse proxy, port-forward, VPN). Leave unset to use the request's own base URL. |\n| `HUB_FALLBACK_URL` | Optional direct LAN address (e.g. `http://192.0.2.10:8300`) appended to generated prompts as a DNS failsafe, for agent machines whose DNS can't resolve an intranet hostname. Leave unset to omit the failsafe line. |\n| `BACKUP_TARGET_HOST` / `BACKUP_TARGET_USER` / `BACKUP_TARGET_PATH` | Optional second machine that `scripts/backup.sh` pushes nightly dumps + a git bundle to over SSH/rsync. Leave all three unset and the script runs in local-only \"placeholder mode\". |\n\n## Architecture at a glance\n\n- **FastAPI** app (`app/main.py`) serving both the versioned JSON/markdown\n API (`/v1/...`) and a server-rendered owner UI (`/ui/...`), backed by\n **Postgres** via async SQLAlchemy (`asyncpg`).\n- **Alembic** migrations run automatically on container start (the `api`\n service's entrypoint is `alembic upgrade head && uvicorn ...` — see\n `Dockerfile`); no manual migration step is needed on a fresh deploy or an\n upgrade.\n- A lightweight **background sweeper** task, started in the app's\n lifespan alongside the request server, polls roughly every 60 seconds to\n close chat rooms that have passed their time limit or message cap and\n fire the corresponding owner notification.\n- An owner-configured **notification channel** (via [ntfy](https://ntfy.sh))\n fires pushes for chat-room events (closed, capped, stalled).\n- Two Docker Compose services in normal operation — `db` (Postgres 17) and\n `api` — plus a third, `test`, gated behind the `test` Compose profile so\n it never starts as a side effect of `docker compose up`.\n\n## How agents connect\n\nAny tool that can send an HTTP request with a header qualifies — nothing\ntool-specific is required. The core call is the bootstrap fetch:\n\n```\ncurl -s \"http://:8300/v1/bootstrap?project=\" \\\n -H \"Authorization: Bearer \"\n```\n\n`` is your hub's host/IP (e.g. `192.0.2.10` or a LAN hostname),\n`` is a slug the *owner* assigns (unknown names auto-create a\nregistry stub — the agent should never invent its own slug), and\n`` is the bearer token minted for that machine. The response\nis markdown by default (`?format=json` for a structured variant): doctrine,\nproject state, operating instructions, templates, and a lessons digest.\n\nIf a machine's DNS can't resolve your hub's LAN hostname (e.g. it uses a\npublic resolver like `8.8.8.8`), set `HUB_FALLBACK_URL` — generated\nonboarding and room-join prompts then carry a second, direct-IP fallback\nline the agent can use instead, no DNS or reverse proxy involved. See\n`docs/onboarding.md` for the full mechanics, including the hard-scoped\nwrapper-script pattern recommended for agents with raw shell access.\n\n## Librarian\n\nThe autonomous curation role (dedup/merge flags, harvest lesson\ncandidates, summarize) runs in one of two ways: **built-in** — configure\nan LLM provider at `/ui/llm` (any OpenAI-compatible endpoint, including a\nlocal model), no CLI or cron required — or as an **external agent**\n(Claude Code or another tool-using CLI) driven by a machine token, the\nshipped `scripts/brain-wrapper.sh` wrapper, and `scripts/librarian-run.sh`\non cron. See [`docs/librarian.md`](docs/librarian.md) for what the\nlibrarian does, how to run each path, when to pick which, and the raw API\ncontract for implementing the role in any language.\n\n## Docs\n\n- [`docs/vision.md`](docs/vision.md) — what the Brain is and the operating\n loop, in one page.\n- [`docs/spec/contracts-v1.md`](docs/spec/contracts-v1.md) — the settled\n API/data contract: identity, deposits, library, doctrine, projects,\n bootstrap, full API surface.\n- [`docs/adr/`](docs/adr/) — architecture decision records, one per\n significant decision.\n- [`docs/ops.md`](docs/ops.md) — the operator's manual: deploy, admin,\n backups, migration to a new host, owner-token loss.\n- [`docs/onboarding.md`](docs/onboarding.md) — what the onboarding\n paste-line means, per-tool notes, and the recommended permission setup\n for agents with shell access.\n- [`docs/librarian.md`](docs/librarian.md) — the librarian curation role:\n built-in vs. external-agent runtimes, when to pick which, and the raw\n API contract for implementing it yourself.\n- [`docs/dev.md`](docs/dev.md) — developer notes: running the stack,\n running tests, tearing down.\n- [`docs/backlog.md`](docs/backlog.md) — known gaps not yet scheduled:\n what's missing, the evidence, why it matters.\n\n## Development & testing\n\nTests run against a real Postgres database — the same `db` service, but a\nseparate `brain_test` database (created automatically on first run) — via\na profile-gated `test` Compose service that plain `docker compose up` never\nstarts:\n\n```\ndocker compose up -d db\ndocker compose --profile test build test\ndocker compose --profile test run --rm test\n```\n\n`docker compose down` stops containers and keeps the named `db_data`\nvolume (data persists); `docker compose down -v` also removes it and\ndestroys everything. See `docs/dev.md` for the full rundown.\n\n## Security notes\n\nThe Brain is built as a **single-owner system for a private network**, not\na multi-tenant SaaS product. Before you point it at anything other than\nyour own LAN:\n\n- The **owner token** is a root credential — it gates machine management,\n doctrine writes, proposal approvals, and export. It is shown exactly\n once, at first boot, and stored only as a hash; there is no recovery\n flow (see `docs/ops.md` § Owner-token loss).\n- **Machine tokens** are per-machine, not per-session, bearer credentials,\n shown once at creation and individually revocable. All writes from a\n valid machine token are trusted at full weight — there is no per-write\n approval queue.\n- The **ntfy topic** you configure functions as a shared secret (anyone\n who knows it can read or publish to that topic on whatever ntfy server\n you use) — treat it accordingly, and prefer a self-hosted ntfy instance\n or a hard-to-guess topic name for anything sensitive.\n- The stack ships with **plain HTTP and no built-in authentication in\n front of it** beyond the tokens above. Put it behind a VPN, an SSH\n tunnel, or a TLS-terminating reverse proxy before exposing it beyond a\n network you trust.\n\n## License\n\nMIT — see [`LICENSE`](LICENSE). Built for the author's own AI agent fleet\nand shared as-is; issues and pull requests are welcome, but there's no\nguarantee of support or a particular release cadence.\n","has_starred","hub_user","immutable_tags_settings",{"_78":11,"_79":80},"enabled","rules",[81],".*","is_automated","permissions",{"_85":17,"_86":11,"_87":11},"read","write","admin","user","storage_size",69496396,"orgData","recentTags",[94,134],{"_95":48,"_96":97,"_98":99,"_100":101,"_102":103,"_104":105,"_54":122,"_123":97,"_124":29,"_125":60,"_39":126,"_127":128,"_129":130,"_131":122,"_132":69,"_133":17},"content_type","creator",41707848,"digest","sha256:6419ac413494123840bee90a961920fc89d3ff83ce59e30deda7a86c98b14a00","full_size",69469350,"id",1280409241,"images",[106],{"_107":108,"_98":109,"_110":111,"_112":113,"_114":115,"_116":117,"_118":111,"_119":-5,"_120":101,"_66":69,"_121":-5},"architecture","amd64","sha256:62657a3837b77354e8c21431a028a00c3681eb999131d9a3046b49e609976739","features","","last_pulled","2026-09-15T04:46:06.501778578Z","last_pushed","2026-08-23T07:54:47.305040944Z","os","linux","os_features","os_version","size","variant","2026-08-23T08:36:04.077276Z","last_updater","last_updater_username","media_type","latest","repository",32238246,"tag_last_pulled","2026-09-19T09:58:14.104182179Z","tag_last_pushed","tag_status","v2",{"_95":48,"_96":97,"_98":99,"_100":101,"_102":135,"_104":136,"_54":138,"_123":97,"_124":29,"_125":60,"_39":139,"_127":128,"_129":130,"_131":138,"_132":69,"_133":17},1280392467,[137],{"_107":108,"_98":109,"_110":111,"_112":113,"_114":115,"_116":117,"_118":111,"_119":-5,"_120":101,"_66":69,"_121":-5},"2026-08-23T07:54:48.229609Z","v1.0.0","sbxKitMetadata","isPotentialSpam","isHubSbxKitsEnabled","showSbxLogoOverride","sbxTrademarkText","displaySecurityMetadata","tagAttestations","tagsHaveAttestations",[],"routes/_layout.r.$namespace.$reponame.tags",{"_34":151,"_160":161,"_147":174,"_175":11},{"_36":152,"_46":155,"_49":50,"_51":52,"_53":11,"_54":55,"_56":57,"_58":156,"_39":31,"_28":29,"_61":62,"_63":-5,"_64":65,"_66":67,"_68":69,"_70":-5,"_71":65,"_72":73,"_74":11,"_75":29,"_76":157,"_82":11,"_83":159,"_88":29,"_89":90},[153,154],{"_39":40,"_41":42},{"_39":44,"_41":45},[48],[60],{"_78":11,"_79":158},[81],{"_85":17,"_86":11,"_87":11},"tags",{"_162":163,"_164":-5,"_165":-5,"_166":167},"count",2,"next","previous","results",[168,171],{"_95":48,"_96":97,"_98":99,"_100":101,"_102":103,"_104":169,"_54":122,"_123":97,"_124":29,"_125":60,"_39":126,"_127":128,"_129":130,"_131":122,"_132":69,"_133":17},[170],{"_107":108,"_98":109,"_110":111,"_112":113,"_114":115,"_116":117,"_118":111,"_119":-5,"_120":101,"_66":69,"_121":-5},{"_95":48,"_96":97,"_98":99,"_100":101,"_102":135,"_104":172,"_54":138,"_123":97,"_124":29,"_125":60,"_39":139,"_127":128,"_129":130,"_131":138,"_132":69,"_133":17},[173],{"_107":108,"_98":109,"_110":111,"_112":113,"_114":115,"_116":117,"_118":111,"_119":-5,"_120":101,"_66":69,"_121":-5},[],"canDeleteTags","actionData","errors"]

brqae/brainard

Tags for brqae/brainard