Organizations & provisioning — bRRAIn Docs

Provisioning and managing your organization's brain pod from the Console.

Organizations & provisioning

This page covers the operator workflow for provisioning, upgrading, restarting, and (when needed) reprovisioning your organization's brain pod.

What a pod is

A brain pod is the per-organization compute that runs your memory engine. Each organization gets one pod (plus an optional standby on Enterprise tier). The pod runs:

  • The Vault writer and reader.
  • The graph builder and graph query engine.
  • The internal Handler — the bRRAIn-tuned LLM that answers questions and assembles context.
  • The Consolidator — the background process that merges incoming writes.
  • The marketplace-extension supervisor — what hosts your installed extensions.

Pods are isolated. No data, no compute, and no LLM weights are shared between organizations.

Provisioning a pod

For most plans, a pod is provisioned automatically when you create an organization. You don't need to do anything; the dashboard shows the pod as Initializing for a few minutes, then Healthy.

You'll be asked to manually provision if:

  • You're on Sovereign-Cloud and self-hosting (see Self-hosting deployment guide).
  • You're switching regions and the new region needs a fresh pod.
  • A previous pod was decommissioned and you're standing up a replacement.

To manually provision:

  1. Open Console → Organizations (the picker at the top of the sidebar; click the active org name).
  2. Click + Provision new pod if no pod is currently attached.
  3. Choose the region (must match your data residency setting; you can't provision in a region that disagrees with your residency choice).
  4. Choose the size: Starter / Standard / Pro / Enterprise. Sizes determine vCPU, RAM, GPU class, and Vault SSD allocation. The page shows monthly compute cost per size.
  5. Confirm. The provisioner places your pod in the queue; the dashboard's pod-status card shows progress with a phase pip (Reserving compute → Booting → Loading model → Connecting to Vault → Healthy).

End-to-end provisioning typically takes 4–8 minutes for Starter through Standard, longer for Pro and Enterprise GPU sizes.

Restarting a pod

Restarting a pod takes the brain offline for ~60–120 seconds while it reloads:

  • Why you'd do this: apply a configuration change that requires a process restart, recover from a transient issue.
  • What it preserves: every byte in your Vault, every file, your network volume, your graph, your installed extensions.
  • What it doesn't preserve: in-flight requests (they fail and clients should retry).

From Organizations → [Your org], click Restart pod. You're shown a confirmation dialog with the impact statement; restart on confirm.

Upgrading a pod

When we publish a new brain version, your dashboard shows a banner: Upgrade available — pod 1.2.34 → 1.2.36. The release notes are linked from the banner.

Click the banner (or use the Upgrade button on the Organization detail page) to upgrade. The upgrade flow:

  1. Stops the current pod (taking it offline for ~60 seconds).
  2. Boots the new version.
  3. Reattaches your network volume.
  4. Reloads installed extensions.
  5. Marks the pod healthy.

Total downtime is the same as a restart for most upgrades. Major-version upgrades may include a one-time Vault migration; the upgrade dialog tells you in advance.

The single-click Upgrade button uses a Keep-Storage workflow — your Vault contents are preserved across the upgrade. We do not provision a fresh disk.

Reprovisioning ("Stop & Reprovision")

Reprovisioning destroys the running pod and stands up a fresh one against the same network volume. You'd do this to:

  • Clear out a state that resists ordinary restart.
  • Pick up a new configuration that only takes effect on a fresh boot.
  • Move to a different pod size in-place.

The flow is the same as provisioning a new pod, except:

  • The previous pod's network volume is preserved and reattached.
  • Vault contents survive intact.
  • In-flight requests are dropped.
  • Total downtime is similar to a fresh provision: 4–8 minutes typical.

Stopping and starting a pod

From the Organization detail page, Stop pod halts the runtime. While stopped, the dashboard shows the pod as Stopped, members get a friendly maintenance message in the app, and you stop accruing compute charges. Storage charges continue.

Start pod brings it back. Boot time matches a fresh provision.

You'd typically Stop only during a long, planned maintenance window or while you decide how to handle a configuration drift. For most users, Restart and Upgrade are the workhorses.

Network volume and storage

Each pod has a dedicated network volume that holds:

  • The Vault on disk.
  • The graph store.
  • Your installed marketplace extensions (in /opt/brrain/extensions/<slug>/<version>/).
  • Logs and operational state.

You can grow the volume from Storage → Resize without restarting the pod. Shrinks require coordination with support.

Multi-region and standby

Enterprise and Sovereign-Cloud tiers can run a standby pod in a second region for disaster recovery. The standby continuously replicates the primary's Vault. Promotion to primary is a one-click Console action. See Vaults for the replication model.

Audit

Every provisioning action is recorded in the audit log: who initiated it, when, with what parameters, and the outcome. Pod starts and stops are tagged with their reason code. The audit log is your single source of truth for "what happened to the pod."

Where to next