Groups

A group is how policy is applied to a set of users without editing each account. Almost everything an operator can tune per-population — token limits, quotas, which upstream model answers, which plugins and knowledge bases are reachable, whether requests are guarded — lives on a group.

Membership

A user belongs to exactly one group, or to none. There is no multi-group membership and therefore no override precedence to reason about: whichever group a user is in is the one that governs them.

One group can be marked Default. Users with no group of their own inherit it, so it governs everyone who was never explicitly assigned. On the members page those two populations are distinguished — assigned members and inherited ones.

Membership is managed from the Members page of a group: select accounts and Move them in. The same bulk move exists on Accounts, which is usually the faster route when you are already looking at the person. Changes take effect on the user’s next request; no client restart.

The Members page also lists credits this week per member — what they have drawn against the group’s per-member weekly allowance, how much of it came from the shared pool, and whether they are on the pool, on their allowance or at their limit. The figures come from the same report as the Weekly budget tab, so the two pages cannot disagree.

Group flag	Meaning
Default	Governs every user without an explicit group. Cannot be deleted while it holds that role
Built-in	Ships with the server. It can be configured but not renamed or deleted (group_protected)

Deleting a group asks where its members should go, and reassigns them as part of the delete — nobody is left group-less by accident.

What a group configures

The group editor is a stack of sections. Each one is optional; leave a section alone and the server default applies.

Section	Sets
Identity	The group’s name
Credit Limits	Hourly, daily and weekly credit ceilings, applied per member, plus the sliding pool multiplier. 0 means unlimited. See below for what a credit is
Group-wide Ceiling	Daily and weekly credit ceilings applied to the group’s members together, on top of the per-member limits above. 0 means unlimited. See below
Per-User Quotas	Maximum templates, personas, providers, sessions, memories and todos each member may hold
Knowledge Base Quotas	Maximum knowledge bases, documents per KB, total KB storage in bytes, and monthly embedding tokens. The KB count and the embedding tokens are per group; documents and storage are per knowledge base. Embedding tokens stay a monthly TOKEN quota — they are not credits
AI Provider Override	Which catalog provider answers for this group, overall and per mode
Guardrails	Whether requests are classified before answering, and by which models
Plugin Allowlist	Which plugins members may use
Client Policy	Which client policy this group publishes to its members

Runtime limits that are not per-group — rate limits, identity policy, AI payload caps — live on Policies.

Credit limits

Limits are per member, not per group: each member gets the full hourly, daily and weekly figure, and 0 means unlimited.

The unit is a credit. One credit is 1,000 tokens on a provider at the default rate; a provider priced above or below that costs proportionally more or less. Every AI provider carries a rate card — input, output, cached input and connector, each in credits per million tokens — and the card in force when a request was answered is stamped onto that usage row. Re-pricing a provider therefore changes what its future traffic costs and leaves the current hour, day and week exactly as the member already experienced them.

Hourly and daily are rolling windows: the last 60 minutes, the last 24 hours. Weekly is a calendar week starting Monday 00:00 in the server’s TokenUsage:WeekStartTimeZone (default Europe/Berlin), so every member of a group resets together.

A member over any of the three ceilings is refused with 429 and a Retry-After telling them when the window rolls.

Group-wide ceiling

The credit limits above bound one member; nothing about them bounds the group as a whole, so N members are N allowances with no total. The Group-wide Ceiling section adds that total: a daily and a weekly figure counted across every member’s spend together, including shared-pool draws. Daily is a rolling 24 hours; weekly is the same calendar week the per-member limits use. 0 means unlimited, and every group ships at 0 — nothing changes until an operator sets a real number.

Once the group’s combined spend reaches either figure, every member is refused until the window rolls, regardless of their own individual limit. This is a deliberate trade: it turns an unbounded bill into a bounded, visible outage instead, which matters most for a group with open or low-trust signup. It is not a substitute for the per-member limits above — a group can be well within its per-member ceilings and still trip the group-wide one, and vice versa.

The weekly limit is the pricing baseline

members × 4 × weekly credits is the monthly fee basis. Four weeks, not a calendar month — a month averages 4.33 weeks, so a month with five Mondays bills the same four weeks. The Weekly budget tab on Token Usage reports the baseline and what has been drawn against it.

Sliding pool

Unused per-member weekly credits partly carry into the next week as a shared pool the whole group draws on:

pool(next week) = sliding multiplier × Σ over members of max(0, weekly − own use this week)

The multiplier is 0 by default, which switches the pool off and leaves the weekly limit a plain per-member cap. At 1.0, a group whose members left 30,000 credits unspent starts the next week with a 30,000-credit pool; at 0.1, with 3,000.

Four rules make the pool safe to hand out:

• Consumed first. Charges land against the shared pool until it is exhausted. Only then does a member start spending their own weekly allowance.
• First come, first served. There is no per-member share. One heavy member can take the whole pool on Monday morning.
• Frozen for the week. The pool is computed once, at the first request of the week, from the previous week’s under-use. Changing the weekly limit or the multiplier mid-week does not resize a pool the group is already drawing on.
• Never compounds. Whatever is left of a pool expires with its week, and only own use — never last week’s pool draws — feeds the next one. A pool can renew at the same size, but it can never grow.

Together these bound the total: after the first pooled week, own use plus pool draws stays inside members × weekly per week. The operator never gives away more than the baseline was paid for, apart from the one-off multiplier × members × weekly a brand-new group starts with (see below).

Three consequences worth knowing:

• A newly created group has no previous week to under-use, so every member counts as fully unused and the group’s first pooled week is multiplier × members × weekly. After that the pool tracks real under-use.
• A member who moves into a group brings their previous week’s spend with them, so they cannot arrive looking unused and hand their new group a pool their old one already paid out.
• A group that stays inside its pool never touches its members’ own allowances, so it reports the whole baseline as unused and is handed back a pool the same size — the same pool, week after week. At 1.0 that makes a group spending up to multiplier × members × weekly permanently pool-funded. This is the trade first-consumption makes: the pool no longer burns itself down the way it did when it was spent last. The per-week total is still bounded, and the pool never grows.

Provider-side connector spend (Mistral’s web search reports it separately, and it dwarfs the model tokens) is free at the default rate, so it stays out of the budget unless an operator prices it deliberately.

AI provider overrides

Requests from members are routed to the group’s chosen provider instead of the server-wide default. Providers come from the server-wide catalog on AI Providers — entries defined under Ai:Providers in configuration plus rows added on that page. Only entries that are currently resolvable are offered here.

A per-mode override takes precedence over the group default, so a group can answer assistant traffic on one model and research traffic on another. Leaving a mode set to the group default is the common case.

Persona type routing goes one step finer. A persona can declare a model type — fast, code, private, or any word you choose — and this section says which provider each type goes to. It applies to Assistant traffic only and is checked before the per-mode override, so a mapped type wins even when the group also routes Assistant elsewhere; a persona with no type, or a type nothing here maps, falls through to the per-mode override and then the group default. Both the personas members author themselves and managed personas can carry a type.

`private` can be allowed to skip the classifier

The private type is the one mapping that can do more than pick a model — but only if you also switch Let private personas answer unclassified on in the group’s Guardrails section. With both in place, an Assistant chat from a persona of that type skips the classifier entirely and answers on the mapped provider, marked as a protected route in the desktop client. Mapping alone changes nothing, every other type keeps being classified, and the bypass is recorded in the decision log as a BYPASS row whenever the group has guardrails running.

Override scope

Overrides only affect which upstream model answers. They do not change which features a group can access — that is the allowlist and policy sections above.

Guardrails

The Guardrails section is where classification is switched on for this group: the master switch, the classifier model, the model that answers a hit, the model that answers a clean request, and which guard types apply.

Guard types themselves are authored centrally, and the whole routing model — what counts as a hit, what happens when it does, what the user sees — is documented on Guardrails.

Plugin allowlist

Check the plugins members may use. Only active catalog rows appear here; connectors and operators are deliberately excluded and granted on their own pages instead.

Managed personas

A group is also how an admin-authored persona reaches users. Assign one on the persona’s own page — see Managed personas — and every member of the group finds it in their desktop persona picker, read-only.

Assignment is capped by Quotas.ManagedPersonas, which defaults to 25 per group. It is a separate counter from Quotas.Personas (default 50, the cap on a user’s own personas): publishing a persona to a group never eats into anyone’s personal quota.

Client policy

The Pia desktop app can have some of its settings preset or pinned by an enterprise policy — traditionally a policy.json file on each managed device, and now a document you write once in the server’s admin console.

The document itself lives in the Client Policies catalog, not on the group. The group only picks one: choose it under Client Policy in the group editor, or leave it on (none). Every member receives it over the ordinary sync pull, and it applies the next time they start Pia.

Any number of groups can publish the same policy, which is the point of the split — one document to correct when a value turns out wrong, instead of one copy per group drifting apart. A group publishes one policy or none; there is no merging of several.

Users with no explicit group follow the default group’s policy.

Attention

A group-scoped document cannot be end-to-end encrypted, and where both it and a device’s policy.json set the same key, the server wins. serverUrl, syncEnabled and trustSelfSignedCertificates are refused for that reason — see Client policies.

Auditing

Group create, update and delete are written to the audit log as Group.Created / Group.Updated / Group.Deleted; moving a user between groups is User.Group.Changed. Each entry records the acting administrator and the target user or group.