Brainlyy

Install

Python 3.10 or newer is the whole prerequisite list. Where the instance lives, and how to add capabilities later.

Prerequisites: Python 3.10 or newer. That is the whole list.

Install the package

uv tool install brainlyy

(or pipx install brainlyy / pip install brainlyy)

Not on PyPI yet. From a checkout:

git clone https://github.com/bidurkhatri/Brainlyy
cd Brainlyy
uv build --wheel
uv tool install dist/brainlyy-0.1.0-py3-none-any.whl

Set up an instance

brainlyy init

Three questions, all defaulted:

  1. Organisation or project name. Defaults to the current directory name
  2. Where notes live. Defaults to ~/.brainlyy/vault
  3. Bind address for the read server. Defaults to a detected mesh address, else 127.0.0.1

Then it generates tokens, renders templates, registers with your MCP client, and runs its property suite. Non-interactive shells take every default, so brainlyy init --no-register < /dev/null works in CI.

Where things go

~/.brainlyy/                 # or $BRAINLYY_HOME
  config.yaml               # yours to edit; no secrets in it
  read-token.txt            # generated, never rotated silently
  write-token.txt
  vault/                    # your markdown notes
  brain/knowledge/          # rendered knowledge base
  brain/souls/              # one file per agent

The instance lives outside the install, so uv tool upgrade brainlyy never touches your config, your secrets or your notes.

Platform notes

Windows. Everything works in PowerShell and in Git Bash. If you register the MCP server manually, note that where/Get-Command resolve .cmd shims that a bare process launch does not. brainlyy handles this internally by resolving the executable before invoking it.

macOS / Linux. No special steps. If brainlyy is not on your PATH after uv tool install, run uv tool update-shell and restart your shell.

All platforms. brainlyy doctor never requires anything to be running. If it reports tier 0 on a machine where you know Ollama is up, the probe is telling you it could not reach it on the configured port. Check ports.ollama in your config.

Adding capabilities later

Nothing needs reinstalling. Start the dependency, and the next brainlyy doctor picks it up:

To reach Start
Tier 1 a local model runner on ports.ollama
Tier 2 a knowledge-base backend on ports.knowledge_api
Tier 3 set hosts.vps_ssh_alias to a working SSH alias
Tier 4 set hosts.public_fqdn and enable edge

Uninstall

uv tool uninstall brainlyy
rm -rf ~/.brainlyy          # only if you want your notes gone too
PreviousOverviewNextHow it works