FAQ

Does anything leave my machine? Not unless you configure it to. Tiers 0 to 2 are entirely local. Tier 3 talks to an SSH host you name. Tier 4 exposes a public endpoint you set up deliberately.

Do I need Ollama / a vector database / a VPN? No. Each one adds a tier. None is required, and none produces an error by being absent. brainlyy doctor reports it as a capability that is missing and tells you what it would add.

Why two servers instead of one? So the credential that travels your network cannot act. See Concepts.

Can I run it beside an existing deployment? Yes. Ports come from config, and the defaults (8780/8781) are deliberately not the ones a live deployment uses. brainlyy init refuses to continue if the ports it wants are already listening.

Can I reach the dashboard from my phone? Yes, over a mesh VPN, by setting ui.bind: mesh. Write actions stay local unless you also set ui.remote_writes: true. Read Security before you do.

Does upgrading wipe my config? No. The instance lives outside the install, under ~/.brainlyy or BRAINLYY_HOME. init never regenerates an existing token and never overwrites a hand-edited SOUL.

Why does search feel basic? At tier 0 it is lexical ranking over markdown, with no embeddings and no index. That is the trade for working thirty seconds after install with nothing else present. Add a vector store for tier 2.

Something is wrong and nothing is telling me. That is the failure mode this project is built around. brainlyy doctor is the first stop; it reconciles claims against observations and is silent only when healthy.

Honest caveats

• Early software. The boundaries are covered by a property suite; the setup paths are less travelled.
• doctor cannot tell you a claim is wrong, only that it is unmarked, stale, or on your forbidden list. Provenance is a discipline the tool supports, not one it can enforce.
• Tier 3 assumes key-based SSH. A host that wants a password is reported as absent, because an unattended tool cannot use an interactive login.
• The code graph is only as current as your last index. Nothing re-indexes on its own.
• Not on PyPI yet, so uv tool install brainlyy does not work today. Build the wheel from a checkout.