Installation — bRRAIn Docs

Get a bRRAIn brain running: a hosted pod provisioned from app.brrain.io, or the installer on your own Linux amd64 host.

Installation

Every bRRAIn organization has one brain: the brrain service that holds the organization's vault, serves the Handler (bRRAIn's own model) and answers the console, clients and extensions. There are two ways to get one:

| Path | Who runs the host | How you start | |---|---|---| | Hosted (Hosted Standard, and Co-located or Data-Resident as quoted) | bRRAIn | Start Provisioning on your organization's provisioning page in app.brrain.io | | Sovereign On-Prem | You | Run the installer on a Linux amd64 server you operate |

Hosting options are quoted separately from the per-user plan. See Self-Hosting for how the options differ.

Hosted: provision a pod

  1. Sign in at app.brrain.io and open your organization's provisioning page.
  2. Press Start Provisioning. bRRAIn allocates a dedicated GPU pod, boots it and polls until it is running. A few minutes is typical.
  3. Copy the Brain URL shown when it finishes. That is the address you give Claude Desktop, VS Code, the browser extension and mobile clients.
  4. Check https://<brain URL>/version and /healthz, then open console.brrain.io and confirm the organization's Zones and Status pages are healthy.

If the page offers an Upgrade, apply it before you go live. Details: Hosted pods.

Self-hosted: run the installer

What you need

  • A Linux amd64 server. The installer refuses any other OS or architecture.
  • Root access.
  • curl, tar, and sha256sum or shasum. Missing curl, tar, gzip and zstd are installed for you with apt-get or dnf; on any other package manager, install them first.
  • A GPU suitable for serving the Handler through Ollama.
  • Disk for the release tarball (several gigabytes), with room for the staged and previous copies an upgrade keeps.
  • Outbound HTTPS to bRRAIn's artifact origin, and to ollama.com if Ollama is not already installed.

Full list: System requirements.

Read it, check it, run it

The installer is one script. Read it before you run it as root:

curl -fsSL https://install.brrain.io -o brrain-install.sh
less brrain-install.sh
sudo sh brrain-install.sh --check     # report installed and available versions, change nothing
sudo sh brrain-install.sh             # install

Or, piped:

curl -fsSL https://install.brrain.io | sudo sh

Flags (pass them after sh -s -- when piping):

| Flag | Effect | |---|---| | --check | Report installed and available versions, then exit | | --version V | Install or upgrade to exactly version V instead of the current stable release | | --force | Reinstall even when already at the target version | | -h, --help | Show usage |

Environment:

| Variable | Default | Purpose | |---|---|---| | BRRAIN_INSTALL_ROOT | /opt/brrain | Install prefix | | BRRAIN_VAULT_ROOT | /var/lib/brrain/vault | Vault location | | BRRAIN_LISTEN_ADDR | :7843 | Address the service listens on | | BRRAIN_MANIFEST_BASE | bRRAIn's artifact origin | Where release manifests are read from; point it at a mirror for air-gapped sites |

sudo usually resets the environment, so pass variables explicitly, for example sudo BRRAIN_VAULT_ROOT=/srv/brrain/vault sh brrain-install.sh. Decide the vault path before the first install: it is written into the systemd unit.

What the installer does

  1. Checks the platform (Linux amd64) and that it is running as root.
  2. Reads the release manifest (latest.json, or <version>.json with --version). A manifest without a SHA-256 digest is refused.
  3. Prints installed: X available: Y. With --check it stops here; if already at the target (and not --forced) it exits.
  4. Installs missing prerequisites, then Ollama if it is not present.
  5. Downloads the release tarball and verifies it against the manifest's SHA-256. On mismatch it stops without touching the installed files.
  6. Extracts to a staging directory and checks that the brrain binary, the Handler's Modelfile and the continuity templates are present.
  7. Stops the brrain service, moves the outgoing files to /opt/brrain/.previous and moves the new ones in. extensions/ and the model store are left alone.
  8. Registers the Handler model with Ollama from the artifact's Modelfile.
  9. If no vault exists at the vault path, runs brrain init there and prints the recovery phrase. An existing vault is never touched.
  10. On first install, writes and enables the brrain systemd unit, then (re)starts it. If the service fails to start, it prints the last 30 journal lines and tells you the previous install is preserved.
  11. Links /usr/local/bin/brrain to the installed binary if nothing is there already.

Re-running the installer is also an upgrade path. Nothing updates on its own.

First boot: the recovery phrase

The vault's master key is wrapped with a key derived from a recovery phrase. bRRAIn never stores the phrase and cannot reissue it. The installer prints it once, on the first install against an empty vault path:

  • Have the people who will hold the phrase at the terminal for that run.
  • Do not tee or log the installer's output; that file would contain the phrase.
  • Prove the phrase works the same day, reading it from a root-only file rather than the command line:
sudo install -m 600 /dev/null /root/phrase.tmp
sudo nano /root/phrase.tmp            # paste the phrase
sudo brrain recover verify --vault=/var/lib/brrain/vault --phrase-file=/root/phrase.tmp
sudo shred -u /root/phrase.tmp

Exit code 0 means the vault unlocks with the phrase, with no bRRAIn services involved.

Confirm the service

systemctl status brrain --no-pager
curl -s http://127.0.0.1:7843/healthz
curl -s http://127.0.0.1:7843/readyz
curl -s http://127.0.0.1:7843/version

brrain serve listens on plain HTTP. Put a TLS-terminating reverse proxy in front of it and verify the installation with bRRAIn: see TLS & license verification.

If the install fails

  • Before the swap (platform, prerequisites, manifest, checksum, "artifact is missing"): nothing in /opt/brrain changed. Fix the cause and re-run. Never work around a SHA-256 mismatch.
  • After the swap (service will not start): fix forward if the journal (journalctl -u brrain -n 100 --no-pager) shows a cause you understand, or restore the previous artifact with sudo brrain upgrade -rollback. A first install has no previous artifact to roll back to.

What is not supported

There is no Docker Compose product, Helm chart, Kubernetes operator or Terraform module for running bRRAIn, and no public container image is a customer install path. The self-hosted path is the installer on a Linux amd64 host. macOS, Windows and arm64 hosts are not supported for the brain.

Next steps