TLS & license verification

brrain serve listens on plain HTTP (default :7843) and does not terminate TLS. On a customer-run host, put a reverse proxy you operate, such as nginx or Caddy, in front of it. Browsers and MCP clients expect https://, and installation verification only accepts an https:// host.

A minimal nginx site

server {
    listen 443 ssl;
    server_name brrain.example.com;

    ssl_certificate     /etc/ssl/brrain/fullchain.pem;
    ssl_certificate_key /etc/ssl/brrain/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    client_max_body_size 200m;

    location / {
        proxy_pass http://127.0.0.1:7843;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        proxy_http_version 1.1;
        proxy_buffering off;
        proxy_read_timeout 300s;
    }
}

• client_max_body_size: people upload documents into the vault. Many proxies default to about 1 MB, which makes uploads fail with 413. Choose a limit that fits your documents.
• proxy_buffering off and a longer proxy_read_timeout: model answers stream. Buffering makes streams look frozen; short timeouts cut long answers off.

sudo nginx -t && sudo systemctl reload nginx
curl -s https://brrain.example.com/version

Test the public HTTPS name, not just 127.0.0.1:7843.

License ID and install secret

On your organization's provisioning page in app.brrain.io, a self-hosted license shows BRRAIN_LICENSE_ID and BRRAIN_INSTALL_SECRET. Treat the secret like a password and set both in a systemd drop-in:

sudo systemctl edit brrain

[Service]
Environment=BRRAIN_LICENSE_ID=<license id>
Environment=BRRAIN_INSTALL_SECRET=<install secret>

Then sudo systemctl restart brrain.

How verification works

On the same provisioning page, enter the customer host (an https:// URL) and press Verify Installation. bRRAIn then:

1. calls GET <host>/version and expects a 200 with a non-empty body;
2. sends POST <host>/api/install/verify with a fresh random nonce and the license ID;
3. your brain answers with an HMAC-SHA256 signature of the nonce and license ID, keyed with the install secret;
4. bRRAIn checks the signature and marks the license installed.

The secret never crosses the wire. Your brain refuses to sign for any license ID other than its own. If you later move the proxy to a new name, use Re-verify host.

| Symptom | Likely cause | |---|---| | Host rejected by the form | Not an https:// URL | | Host unreachable | DNS, firewall or proxy not reachable from the internet | | /api/install/verify returns 503 | BRRAIN_LICENSE_ID or BRRAIN_INSTALL_SECRET missing, or the license ID is not a number | | Signature rejected | Wrong secret, or the license ID does not match |

If the host must not be reachable from the internet at all, verification as described cannot complete; agree the approach with bRRAIn before install day.