Hive docs
Everything the ns-brain binary does with a hive, on one page. A hive is a
brain shared by a team: coding agents in every project attached to it read what the team
knows at the start of a session and write back what they learn.
The four words
- Organisation. What you create when you register. Everything below belongs to exactly one. Nothing crosses between two.
- Node. A place in the organisation's tree. The root node is the organisation itself; each project gets a node of its own beneath it. A memory lives on one node. A grant on a node covers everything under it.
- Project. A code repository with a
brain.jsonin it. Its name (the directory name unless you give it another) is how the server finds its node. A project gets its node the first time it writes anything, so there is nothing to create by hand. - Credential. What a machine holds to talk to this server. One per machine per organisation, kept outside every project, used by every project on that machine. Signing in is per machine; attaching is per project.
1. Register and set up your first machine
Who: the person starting the organisation. You need: a terminal on macOS or Linux, and a project checked out in a git repository.
- Open /signup. Choose a name for the organisation (lowercase letters, numbers and hyphens), your email and a password of at least 12 characters. Press Create it. You become the owner.
- The next screen shows a credential, once. Copy it now. It starts with
hive_. Lose it and you can still sign in the slow way (step 4 as a colleague would), but it is never shown again. - Install the client. It is one file, put on your PATH:
curl -fsSL https://brain.fightclub.pro/install.sh | sh ns-brain version
ns-brain 26092806 (schema v16)
- Go to the root of the project and sign in with the credential:
cd ~/code/web ns-brain hive login --server https://hive.fightclub.pro --token hive_...
You should see:credential stored for https://hive.fightclub.pro, organisation acme (1) ~/.config/ns-brain/credentials.json, mode 600 Attach 'web' to the hive? The hive is online: once attached, what sessions in this project remember is stored on https://hive.fightclub.pro, in organisation acme (1), not only on this machine. project: ~/code/web - nothing is copied: this project has no brain yet - brain/brain.json is pointed at the server - the brain's hooks and slash commands are written into .claude/, so every session here starts from it and writes to it Attach now? [y/N] - Type
yand press Enter. It prints what it wrote:attaching the project at ~/code/web attached to the brain on https://hive.fightclub.pro, node 1 + brain.json for 'web' + .gitignore entry for brain/brain.db* + SessionStart hook -> BRAIN_HOME="$CLAUDE_PROJECT_DIR/brain" ns-brain wakeup + UserPromptSubmit hook -> BRAIN_HOME="$CLAUDE_PROJECT_DIR/brain" ns-brain hook-recall ...
- Check it:
ns-brain hive status
hive https://hive.fightclub.pro api v1, schema v19 (this client speaks v19) organisation acme (1), person alice@acme.example (1), token 1 ... brains this machine holds credentials for: * https://hive.fightclub.pro org acme (1) - Commit
brain/brain.jsonand.claude/settings.json. They hold no secret, and committing them is what lets a colleague's checkout find the same brain. - Open a new agent session in the project. Its first message now starts from the brief.
If you see something else. Not attached; nothing was sent: you
answered no, or the command ran without a keyboard (inside an agent or a script). Run the
command it prints, or log in again with --attach. is not inside a
project: you ran it outside a git repository; cd into one and run
ns-brain init --hive https://hive.fightclub.pro. that credential was not accepted: the
token was mistyped or revoked; copy it again.
2. Add another project, on a machine already signed in
Who: anyone signed in on this machine. You need: nothing new. The credential belongs to the machine, so there is no second login and no approval.
The project has no brain yet
cd ~/code/api ns-brain init --hive https://hive.fightclub.pro
attached to the brain on https://hive.fightclub.pro, node 1 no local store: this project's memories live there, and a file here would be a second answer + brain.json for 'api' ...
The project gets its own place in the organisation the first time anything is stored. Its
name is the directory name; to call it something else, add --project <name>.
The project already has a local brain
Look before anything moves. The dry run lists what would be copied:
cd ~/code/legacy ns-brain hive join
DRY RUN — join — move 'legacy' into the hive at https://hive.fightclub.pro
1 memories would be sent to node 1 (1 live, 0 retracted, with their chains)
[decision] deploys go through the staging box first
Nothing has moved. Add --apply to do it.
The local database is kept either way: join copies, it does not empty.
Colleagues will be able to read what moves. When you are happy with the list:
ns-brain hive join --apply
dump written first: ~/code/legacy/brain/brain.db-prejoin-20260928-150013.json 1 sent, 0 refused by the server brain.json now points at https://hive.fightclub.pro node 2, so every ordinary command and every hook uses the hive from the next run. The local database is untouched and is what `ns-brain hive leave` puts back.
The project is already on the hive from another machine
If brain/brain.json is committed with the server in it, this machine only needs
to be signed in (procedure 3 or 5). Nothing else to run.
If you see something else. several credentials for this server:
this machine is signed in to more than one organisation; see procedure 4.
this credential can work in the projects it was granted, but ... starting a new project
needs contributor on the organisation: your grant is on particular projects, not the
organisation. Ask an admin to approve a fresh ns-brain hive login from you at the
organisation. this project is already attached: there is nothing to do.
3. Let a colleague in
Two people are involved, and the code has to pass from one to the other by chat, phone or across the desk. That is deliberate: whoever approves a code decides which organisation the person joins, so codes are never listed anywhere.
The colleague
- Install the client (procedure 1, step 3).
- In the root of a project, run:
ns-brain hive login --server https://hive.fightclub.pro
Sign in at: https://hive.fightclub.pro/v1/device?code=DWAF-GAD6 Your code: DWAF-GAD6 Someone with admin approves it there. The code is good for 10 minutes. Waiting....
- Send the code to an admin and your email address with it. Leave the terminal running.
- When they approve it the dots stop,
approved.appears and it asks to attach the project, exactly as in procedure 1 step 4.
The admin
On the dashboard: /login, sign in, find Let somebody in. Enter the code, their email, the node and the role, then Approve. Or from a terminal on your own machine, from any directory:
ns-brain hive approve DWAF-GAD6 --email bob@acme.example --node 1 --role contributor --server https://hive.fightclub.pro
approved DWAF-GAD6 for bob@acme.example as contributor on node 1
Choosing the node. The organisation's own node (the dashboard's default,
shown in ns-brain hive nodes as org) lets them work in every project
and start new ones. A project's node limits them to that project. Choosing the
role: see Roles; contributor is right for most
people.
If something goes wrong. that code expired before it was approved: ten minutes passed; the colleague runs login again for a new code. this needs admin on that node: you cannot let people into a node you do not administer. Approving the same person again replaces their grant, which is also how you change someone's role or node.
4. Several organisations on one machine
Sign in to each one with its own hive login. They sit side by side and never
replace each other:
credential stored for https://hive.fightclub.pro, organisation beta (2) this machine now holds 2 brains; a project names its own with "org" in brain.json's hive block
From then on, say which one when attaching a project. Without it you are asked, never guessed for:
ns-brain init --hive https://hive.fightclub.pro
several credentials for this server: this machine holds 2 for https://hive.fightclub.pro and this project names none. Say which, with --org <name> or "org" in brain.json's hive block: https://hive.fightclub.pro org acme (1) https://hive.fightclub.pro org beta (2)
ns-brain init --hive https://hive.fightclub.pro --org beta ns-brain hive join --org beta --apply
The choice is written into the project's brain.json, so you say it once per
project. ns-brain hive status lists every organisation this machine holds, with a
* against the one the current project uses.
5. Add a second machine of your own
A new laptop or a desktop signs in exactly as a colleague does (procedure 3): run
ns-brain hive login there and approve the code yourself on the dashboard, since you
are an admin. Projects whose brain.json is committed need nothing more; others get
init --hive or hive join as in procedure 2.
CI and headless agents. There is no separate machine token to issue yet.
Sign the CI box in once with ns-brain hive login as the person it should act as,
and it keeps working. A credentials file can also be supplied as a secret and pointed to with
NS_BRAIN_CREDENTIALS. On a machine with nobody at the keyboard, login never attaches
a project without --attach.
6. Using it day to day
Once a project is attached your coding agent does most of this through the hooks: the brief at the start of a session, related memories with each prompt, a reminder to store what it learned at the end. Every one of these also works from a terminal in the project.
ns-brain remember --type decision --title "Payments go through Stripe Checkout, not Elements" \ --body "Checkout keeps us out of PCI scope. Decided with finance, 2026-09-28."
remembered #2 on https://hive.fightclub.pro [reported]
ns-brain recall "stripe payments"
#2 [decision] (score 1.188) Payments go through Stripe Checkout, not Elements — alice@acme.example, 2026-09-28 15:01
Checkout keeps us out of PCI scope. Decided with finance, 2026-09-28.
Recall matches meaning as well as words: recall "staging data disappeared"
finds a memory titled "The staging database is restored from prod every Sunday".
ns-brain get 2 prints one memory in full.
ns-brain prefer "Run the test suite before every commit, and say which tests ran" ns-brain log --kind deploy --summary "v2.3.0 to production, migration 0042 applied" ns-brain task add "renew the Apple push certificate" --when 2026-11-01 --owner user ns-brain note web "The checkout decision is in the api brain; recall stripe"
prefer records how the team wants to be worked with, and every session's brief
opens with it. log is the history of what happened. task is what is
owed and when (task list, task done 1). note leaves a
message for another project; it appears at the top of that project's next brief and in
ns-brain note --inbox there.
ns-brain brief
======================================================================== HIVE BRAIN — SESSION BRIEF ======================================================================== server https://hive.fightclub.pro · org acme memories 3 visible to this credential ## HOW THEY WANT TO WORK #4 [preference] Run the test suite before every commit, and say which tests ran ## RECENT ACTIVITY 2026-09-28 [deploy] v2.3.0 to production, migration 0042 applied
A fact that changed is corrected, not duplicated: ns-brain remember ... --supersedes 2
keeps the history and retires the old one. ns-brain update 2 --body "..." improves
the wording of the same fact.
7. Forgotten dashboard password
From any machine already signed in, run ns-brain hive password, type the new one
twice, then sign in at /login. From that machine, ns-brain hive
dashboard opens the dashboard already signed in, with no password at all. If no machine
of yours is signed in, ask another admin in the organisation.
8. A laptop is lost, or someone leaves
On the dashboard, Credentials lists every credential with when it was last used;
Revoke stops one on its next request. From a terminal, ns-brain hive machines
lists enrolled machines and ns-brain hive logout --server https://hive.fightclub.pro --machine <name>
revokes one while leaving the machine you are on signed in. To remove a person's writing and
attribution entirely, an owner runs ns-brain hive erase --email <them>
(a dry run until --apply).
9. When the trial ends
A new organisation has six months with no card. After that the balance on the dashboard pays for each period. If it runs out, the organisation is suspended: every read and write is refused with this message, and nothing is deleted.
this organisation is suspended for non-payment. Your data is intact and GET /v1/export still works
Agents are told the brain did not answer rather than being handed an empty one. Top up and
it answers again on its own, with nothing to re-run. ns-brain hive leave --apply
still works while suspended, so nobody is ever locked out of their own memories.
10. Upgrading the client
When a newer ns-brain is out, the binary says so once a day on its own, and
session briefs carry it too:
ns-brain 26092806 is out; this is 26092701. Upgrade: curl -fsSL https://brain.fightclub.pro/install.sh | sh
Run that line on each machine. Memories live on the server, so nothing in a project changes.
Then ns-brain version confirms it.
11. Leaving
ns-brain hive leave
DRY RUN — leave — take 'api' back to a local brain 4 memories would be written to ~/code/api/brain/brain.db Nothing has changed. Add --apply to do it.
ns-brain hive leave --apply
4 memories would be written to ~/code/api/brain/brain.db 1 open tasks and 1 log entries came back with them export written: ~/code/api/brain/hive-export-20260928-150127.json 4 of 4 memories are now in the local brain (0 of them retracted, with their chains) brain.json no longer names a server, so the next command uses the local store
Nothing is deleted on the server. Ask an admin to revoke the credential when you are done.
Roles
Each role includes everything above it in this table. A grant applies to its node and to everything beneath it.
| Role | May |
|---|---|
| reader | recall, brief, get |
| contributor | remember, log, tasks, notes, leads, measures. Contributor on the root is what starting a new project needs |
| curator | forget and restore memories |
| admin | approve people onto the node, approve machines, change node settings, open the dashboard (admin on the root) |
| owner | retention, erasure, legal holds, passing on guardrail and axiom authority |
What changes in a project once it is attached
Nothing you type. brain.json gains a block like this:
"hive": {"server": "https://hive.fightclub.pro", "node": 12, "org": "3"}
and every ordinary command (brief, recall,
remember, prefer, log, note,
task, get, update, forget and the rest)
goes to this server. The session hooks call the same commands, so agents need no new
instructions. A project reads its own node plus the organisation's memories above it; it
never reads a sibling project's. remember --everywhere stores at the
organisation so every project reads it.
An attached project never falls back to a local file. If the server cannot be reached for a read, the command says so and names the server.
Every hive command
ns-brain hive help prints the short form of this table.
Signing in and out
| Command | What it does |
|---|---|
| hive login | Prints a code and a link, waits for an admin to approve it,
stores the credential, then offers to attach the project it was run in. Without
--server it uses the project's server, else https://hive.fightclub.pro; it says which.
--token stores a credential directly. --attach answers the attach
question yes in advance. Signing in to a second organisation adds a credential beside the
first; it never replaces one. |
| hive logout | Forgets this machine's credential. With --revoke
it is revoked on the server first, which is what you want if the machine may have leaked.
--machine <name> revokes another enrolled machine from this one and
leaves this one signed in. |
| hive status | Is the server answering, which organisation and person this credential is, what is queued and every brain this machine holds a credential for. |
| hive nodes | The nodes this credential reaches, with this project's node marked. Empty means nobody has granted you anything yet. |
| hive dashboard | Opens a single-use link to this organisation's dashboard,
good for two minutes. --json prints it instead. |
Projects
| Command | What it does |
|---|---|
| hive join | Copy this project's local memories, open tasks and log onto the
server and point brain.json at it. A dry run until --apply. The
node defaults to this project's own, else the organisation's; --node names
one. --again re-sends memories only, for a project already attached (tasks and
log are not re-sent, since they would duplicate). |
| hive leave | Bring this project back to a local brain: memories with their
history, pins and ages. A dry run until --apply. Nothing is
deleted on the server. |
| hive recall "<query>" | Ask the server directly. --n caps
the results. Ordinary ns-brain recall does the same in an attached
project. |
| hive remember | Store directly: --title, --body,
--type, --source, --node. Queued if the server is
unreachable. |
| hive queue | What is waiting to be sent plus anything the server refused. |
| hive flush | Send what is waiting now. |
People and machines
| Command | What it does |
|---|---|
| hive approve <CODE> | Let somebody in: --email,
--node (default this project's), --role (default contributor),
optionally --guardrail and --axiom. Needs admin on that node. |
| hive machines | Machines enrolled on this brain through the relay. |
| hive pending | Machines waiting to be approved, with their codes. |
| hive approve-machine <CODE> | Admit one permanently. |
| hive password | Set the password that enrols a new machine over the relay. It enrols and does nothing else; it never reads or writes a memory. |
Machines, pending, approve-machine and password concern the relay, which is for machines that cannot reach a server directly. Machines that can open https://hive.fightclub.pro over https do not need it.
Compliance (owner, except settings)
| Command | What it does |
|---|---|
| hive settings --node <id> | Read a node's retention, sensitivity and
how long read-audit rows are kept. Change them with --retention type=days
(comma list; 0 means keep for ever), --sensitivity open|restricted|regulated,
--audit-days N or --audit-for-ever. Needs admin on that node. |
| hive retention | Delete what the retention rules say is past its life. A dry
run until --apply. Nodes on hold are skipped. |
| hive erase --email <who> | Remove one person's writing and attribution
from the organisation. A dry run until --apply. Memories that retract others
are anonymised rather than deleted, so a retracted fact does not come back. |
| hive hold --node <id> --reason "..." | A legal hold: freezes the node against retention and erasure. Prints the hold id. |
| hive hold --release <id> | Lift that hold. |
The server
| Command | What it does |
|---|---|
| hive serve | Run a hive server on this machine. See Running your own. You do not need it to use https://hive.fightclub.pro. |
Every hive flag
Flags may come before or after the subcommand; one dash and two work the same.
--server on an organisation-level command (approve, machines, dashboard,
settings) lets it run outside any project.
| Flag | Used by | Meaning |
|---|---|---|
| --server <url> | all | Which hive. Default: the project's, else the only one this machine holds a credential for; login and logout fall back to https://hive.fightclub.pro. |
| --org <slug|id> | all | Which organisation on that server, when this machine holds credentials for several. |
| --token <tok> | login, any | Use this credential. On login it is stored; elsewhere it is used for that one command. |
| --attach | login | Attach the project without asking. |
| --node <id> | join, approve, remember, hold, settings | Which node. |
| --apply | join, leave, retention, erase | Do it. Without it these are dry runs. |
| --again | join | Re-send memories for an attached project. |
| --email <addr> | approve, erase | Which person. |
| --role <role> | approve | reader, contributor, curator, admin or owner. |
| --guardrail | approve | Pass on guardrail authority (owner only). |
| --axiom | approve | Pass on axiom authority (owner only). |
| --revoke | logout | Revoke this machine's credential on the server, then forget it. |
| --machine <name> | logout | Revoke that enrolled machine. |
| --title --body --type --source | remember | The memory. |
| --n <count> | recall | How many results (default 8). |
| --reason "..." | hold | Why. Required. |
| --release <id> | hold | Lift that hold. |
| --retention type=days | settings | Retention per memory type. |
| --audit-days N | settings | Keep read-audit rows N days. |
| --audit-for-ever | settings | Keep read-audit rows for ever. |
| --sensitivity | settings | open, restricted or regulated. |
| --json | most | Machine-readable output. |
init, for a hive
ns-brain init --hive https://hive.fightclub.pro \
[--org <slug>] [--node <id>] [--project <name>]
| Flag | Meaning |
|---|---|
| --hive <url> | Attach to this server instead of creating a local brain. Needs a credential on this machine first. |
| --org | Which organisation, when this machine holds several for the server. |
| --node | Which node. Default: this project's own node if it has one, else the organisation's, under which the server files the project by name. |
| --project | The name the project goes by, so which node it is. Default: the directory name. Use it when the same repository is checked out under different directory names on different machines. |
| --dir | Where brain.json goes inside the project (default
brain). |
| --agent | Which agents to wire: claude, codex, cursor, gemini. Default: the ones it finds. |
| --no-hook --no-auto-recall | Skip the hooks, or only the per-prompt recall. |
| --channel | Register the direct-message channel in
.mcp.json. |
init is safe to run again: it rewrites the hooks in place and never touches memories.
Files and environment
| Where | What |
|---|---|
| credentials.json | The machine's credentials, one per server and
organisation, mode 600, in the OS config directory under ns-brain/
(~/.config/ns-brain/ on Linux, ~/Library/Application Support/ns-brain/
on macOS). Never inside a project: a token in a project is one git add from
being published. The client refuses a file others can read. |
| queue/ | Writes waiting for the server, beside the credentials, one file per project. |
| brain.json | In the project, committed. Names the server, node and organisation; holds no secret. |
| latest-version.json | The newest ns-brain this machine has heard of, beside
the shared store in ~/.claude/brain/. Every response from this server carries
its version, so a machine attached here learns of a release without asking anyone. When the
binary is behind, it says so on stderr once a day with the upgrade command. |
| NS_BRAIN_NO_UPDATE_CHECK | Set to 1 to turn the version check and its notice off. |
| NS_BRAIN_CREDENTIALS | Use this credentials file instead. |
| NS_BRAIN_QUEUE_DIR | Use this queue directory instead. |
| BRAIN_HOME | Use the brain in this directory instead of searching upward from the working directory. |
The client only sends a credential over https (loopback excepted), because the server URL comes from a committed file that somebody else may have written.
When the server is unreachable
Writes queue on the machine in order and go in on the next command that reaches the
server; hive queue shows them and hive flush sends them. A write the
server refuses is kept in the queue with the reason, never retried and never dropped. Reads
do not queue: they fail and say so.
Errors and what they mean
| It says | Do this |
|---|---|
| no credential for <server> on this machine | ns-brain hive
login on this machine. |
| this machine knows N hive servers and this project names none | Add
--server <url>. |
| several credentials for this server | Add --org <slug>;
it is then written into brain.json. |
| this project is already attached | From hive join: there is
nothing to move. On another machine it only needs hive login. |
| adding one needs contributor on the organisation itself | Your grant covers particular projects. See above. |
| this needs <role> on that node | Ask an admin to approve a fresh login from you with that role. |
| this credential can reach N nodes on ..., so which one this project belongs to is not something init may guess | Your client is older than 26092301. Upgrade it with the
curl line above and run the same command again. On an old client, --node with
the id marked (org) in that list does the same thing: the server files the new
project under the organisation by its name. |
| this credential reaches no nodes | You were approved without a grant, or it was removed. Ask an admin. |
| that code expired before it was approved | Run login again; codes last a few minutes. |
| refusing to talk to <url> over http | Use the https URL. |
| the server needs at least v<N>. Upgrade it | Reinstall the client with the curl line above; the refusal carries it too. |
Running your own server
You do not need this to use https://hive.fightclub.pro. It is the same binary, listening:
ns-brain hive serve --dsn postgres://... --master-key /etc/hive/master.key ns-brain hive serve --dsn ... --init-org acme --init-owner you@acme.example
Postgres holds everything. Each organisation's data key is wrapped by the master key, so
lose that file and nobody can read the memories, you included: copy it off the machine
before the server holds anything real. Put TLS in front of --addr.
| Flag | Meaning |
|---|---|
| --dsn | Postgres connection string (or HIVE_DSN). Required. |
| --master-key | File holding the 32-byte master key in hex (or HIVE_MASTER_KEY_FILE). Required. |
| --addr | Listen address (default 127.0.0.1:7799). |
| --signup | Offer self-serve organisation creation at /signup. |
| --licence | Appliance licence file (or HIVE_LICENCE). |
| --embed-url --embed-model --embed-dims --embed-every | Semantic search: the embedding server (or HIVE_EMBED_URL), its model, vector width and how often to sweep. Without them search is lexical. |
| --axon --axon-dir | Also serve over the relay this machine is enrolled with, using that identity directory. |
| --stripe-key-file --stripe-webhook-secret-file | Card top-ups into the organisation's wallet. |
One-shots, which do their job and exit:
| Flag | Meaning |
|---|---|
| --init-org --init-owner | Create an organisation and its first owner. |
| --approve --approve-email --approve-node --approve-role | Approve a login code from the server's shell: how the first person gets in. |
| --credit --credit-cents --credit-note --credit-ref | Post credit to an organisation. The same ref never posts twice. |
| --adopt-axon --adopt-org | Store a relay authority made by hand as an organisation's. |
| --adopt-axon-root | Give an organisation its authority's root key so its issuing certificate can be rotated. |
| --adopt-machine | Write a machine that already holds a certificate into the register. |
An agent sent here should read /llms.txt. The only route that
answers without a credential is GET /v1/health. It says nothing about
anybody.