Licensing & tiers

Free vs paid, seat pooling, and which features need a licence.

Hive runs without a licence key on a free tier. A few capabilities are paid add-ons rather than capacity limits, and knowing which is which saves a support round-trip when a control is greyed out.

Capacity: seats and pooled allowances

Allowances are per seat and pooled, not per brain. With 3 seats on the free tier you get 15 brains and 1,500 neurons in total, spendable however you like across those brains.

State	Seats	Brains / seat	Neurons / seat
No licence key (out of the box)	2	5	500
Registered free licence	3–20	5	500
Enterprise / custom	Per agreement	Per agreement — 0 means unlimited

Registering a free licence is free and self-serve — it lifts you from 2 seats to as many as 20. Do it from Admin → Configuration.

Paid features

These are switches that are either available or not; adding seats on the free tier does not unlock them.

Feature	What it gives you
Audit history	Append-only change history per brain, with configurable retention, queryable through `aiqbee_get_audit_history` and `aiqbee_get_brain_audit_history`. Every write is attributable to the user or service account that made it.
Advanced security	Per-neuron-type access control — grant or withhold individual neuron types from users and groups, rather than access being all-or-nothing at the brain level.
Neuron metadata	Declared metadata fields per brain, values on neurons, and `metadata_filter` on search and listings — see Neuron metadata. Only writing is gated: reading and filtering stored metadata work on any tier.

Audit and advanced security are per-brain toggles that default to off, so a paid licence does not retroactively switch anything on. Enable them per brain from the brain's page. Metadata has no toggle: a brain with no declared fields simply has nothing to write or filter.

How the gate behaves

Only enabling is gated. Turning a feature off is always allowed, so a lapsed subscription never traps a brain in a state it cannot leave.
Enforced at every entry point — the web UI, the MCP tools and the REST API all refuse equally. The greyed-out control is a courtesy; the real check is server-side.
A lapsed licence does not disable what is already on. A brain that had audit enabled keeps auditing, and keeps its history. You can still turn it off.
Metadata already written is retained, readable and filterable after a downgrade. Only new or changed values are refused; removing a value, clearing a neuron and deleting a declared field stay available.

Pairing and refresh

A licence obtained through pairing carries a JWT plus a refresh token. Hive rotates the JWT automatically — at startup and daily thereafter, refreshing once fewer than 23 days remain.

After a subscription change is made upstream, press Check License Now on Admin → Configuration rather than waiting for the daily cycle. It contacts the licence server immediately and applies the result, including any change of tier — new entitlements take effect at once, with no restart.

Air-gapped deployments can skip the licence server entirely and have a key installed directly; refresh then becomes a no-op and the key must be replaced manually before it expires.

What happens at the limits

Situation	Behaviour
Pooled brain or neuron allowance reached	Creates are refused with a message naming the cap and how to lift it. Existing data is untouched and stays readable.
Seat count reached	New user sign-ins are refused; existing users are unaffected.
Licence expired	Read-only mode — nothing is deleted, and restoring a valid licence restores writing.

Because allowances are pooled and enforced at write time, these show up as a clear error from the tool call — which is another reason to pass Hive's error text back to your model verbatim rather than replacing it.