Self-Hosting — bRRAIn Docs

bRRAIn's hosting options, what changes when you run the brain on your own Linux amd64 host, its on-disk layout, and the CLI you operate it with.

Self-Hosting

This guide is for the people who operate a bRRAIn brain: on a hosted pod that bRRAIn provisions, or on a Linux amd64 server you run yourself.

Hosting options

bRRAIn sells four hosting options. All four are quoted to the configuration, separately from the per-user plan.

| Option | Who operates the host | |---|---| | Hosted Standard | bRRAIn. Your organization's brain runs on a dedicated GPU pod provisioned from app.brrain.io. | | Co-located | As set by the quote. Facility arrangements are part of the quote. | | Data-Resident | As set by the quote. Location terms (country, facility, failover region) are written into the contract. | | Sovereign On-Prem | You, on your own Linux amd64 GPU server, using the installer. |

What a hosting option guarantees about location is whatever your contract says, and nothing more. Commercial models you opt into through the LLM Registry are a separate data flow; review them against your contract before enabling them.

What is the same everywhere

  • The same brain release runs on every option.
  • The vault is the canonical store, initialized once and protected by a recovery phrase that only the customer holds.
  • The Handler, bRRAIn's own model served locally through Ollama, is the default model. Commercial models are opt-in per organization.
  • Upgrades are explicit. Nothing updates on its own.
  • The organization is administered in the console at console.brrain.io.

What changes on Sovereign On-Prem

On a host you run, you take on what bRRAIn does for a hosted pod:

  • Hardware and OS: a Linux amd64 server with a GPU for the Handler. See System requirements.
  • Install: curl -fsSL https://install.brrain.io | sudo sh. See Installation.
  • Hardening: firewall, SSH, OS patching and admin accounts are yours.
  • TLS: brrain serve listens on plain HTTP (default :7843). Put your own TLS-terminating reverse proxy in front of it. See TLS & license verification.
  • License verification: set the license ID and install secret from the provisioning page, then verify the host with bRRAIn.
  • Backups and DR: snapshots and getting them off the host are your design. See Backup & restore.
  • Upgrades: you decide when to run brrain upgrade. See Updates & releases.
  • Air gap, if required: mirror the release origin. See Air-gapped install.

Layout on a host

| Path | Contents | |---|---| | /opt/brrain (BRRAIN_INSTALL_ROOT) | The installed release: the brrain binary, the Handler's Modelfile and the continuity templates | | /opt/brrain/.previous | The previous release, kept for brrain upgrade -rollback. Do not delete it to free space. | | /opt/brrain/extensions | Installed marketplace extensions; untouched by upgrades | | /opt/brrain/ollama | The model store; untouched by upgrades | | /var/lib/brrain/vault (BRRAIN_VAULT_ROOT) | The vault | | /usr/local/bin/brrain | Link to the installed binary (created if nothing was there) |

The installer creates a brrain systemd unit that starts after ollama.service, restarts the brain automatically (Restart=always, two seconds apart) and sets BRRAIN_VAULT_ROOT, BRRAIN_INSTALL_ROOT, BRRAIN_LISTEN_ADDR and the Handler model name. Add your own settings, such as the license ID and install secret, with sudo systemctl edit brrain rather than editing the unit.

A brain that keeps restarting is a signal to decide, not a fix: read journalctl -u brrain, then fix forward or roll back.

Health endpoints

| Endpoint | Meaning | |---|---| | GET /healthz | Liveness: 200 once the server is up | | GET /readyz | Readiness: JSON report of zones and storage notes | | GET /version | The running version |

The brrain CLI

Every subcommand accepts -h for its own help; brrain help lists them all.

| Area | Commands | |---|---| | Install and run | init <vault-path>, serve, version | | Upgrades | upgrade (-check, -dry-run, -pin V, -rollback, -no-restart), check-updates (same as upgrade -check), update (legacy alias for upgrade) | | Identity and access | login, logout, whoami, users, roles, policies, mfa | | Working with memory | session, workspace, record, mcp, consolidator | | Recovery and evidence | dr (snapshot, restore, failover, migrate, status), export, recover verify, audit verify | | Documentation | docs |

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. Hosted brains run on pods bRRAIn provisions; customer-run brains use the installer on Linux amd64.

Where to next