Managed personas

A persona shapes how the desktop assistant answers — its identity, voice, guardrails and expertise. Normally a user authors their own, and it only ever reaches that user’s other devices.

A managed persona is authored here instead, on the Managed Personas page (/admin/managed-personas), assigned to one or more groups, and delivered read-only to every member of every assigned group. The driving case is a shared brand voice: one prompt that every colleague uses, that nobody can silently fork.

A managed persona can also own resources. Bind a knowledge base or a connector to it and that resource becomes reachable only while that persona is selected — invisible in ordinary chat.

Managed personas are stored and delivered in plaintext

A shared row cannot be wrapped with any one user’s key, so managed personas are never end-to-end encrypted — not even for accounts that have E2EE enabled. Do not paste confidential material into the prompt, the guardrails, or any other field. The editor carries the same warning permanently, and it cannot be dismissed.

The list

Three tiles sit above the grid: Total managed personas, Active (the ones whose Active switch is on), and Unassigned.

Unassigned counts personas assigned to zero groups — authored, possibly active, and reaching nobody. It is not an error state; a persona you are still drafting belongs there. But if a colleague says they can’t find the persona you published, this tile is the first thing to read: a non-zero count means at least one persona has no audience, and the Groups column below says which.

Column	Reads
Name	The persona’s name, with its emoji
Tagline	The short subtitle shown under the name on the client
Status	Whether the Active switch is on
Groups	How many groups it is assigned to
Bound plugins	How many knowledge bases and connectors are bound to it
Updated	Last write of any kind

A persona with 0 groups reaches nobody. That column is the answer to “why can’t anyone see it?”

Creating a persona

1. Press New persona.

2. Optionally pick a template under Start from a template. The seven personas that ship with the desktop client — Pia · Personal, Pia · Business, Experienced Coder, Marketing Writer, Financial Expert, Worldwide Company CEO, Explain It Simply — are available as starting points. The copy is taken once, at create time; the managed persona is independent of its template afterwards.

3. Fill in Identity: Name (required), Tagline, Archetype (assistant, analyst, creative, visionary, explainer, or custom), Emoji, and Accent color as #RRGGBB. Leave Active on unless you are drafting.

4. Fill in Content: System prompt (required — this does most of the work), Guardrails, Output format guidance, and comma-separated Expertise tags.

5. Under Model behavior, set Model type, Tool scope and Reasoning effort — see Model behavior below.

6. Press Create. Group assignment and plugin bindings only appear after the first save — they need a persona id to attach to.

Model behavior

Model type — the routing key the desktop client sends with every Assistant turn this persona drives. Leave it blank and the persona is answered by whatever the group normally uses. Type a word the group maps — fast, code, private, or one of your own — and Assistant turns driven by this persona go to that provider instead. The words are free-form; all that matters is that the same word appears in the group’s persona type routing on Groups. Up to 50 characters.

Tool scope — three values, defaulting to Full:

Option	Stored as
None — no server-side tools	0
Read-only (reserved)	1
Full	2 (default)

Tool scope is not a security control

The editor says so on the page, and it is worth repeating: tool scope is stored on the persona but is not enforced by the server today. It is guidance surfaced to the client, not a hard gate — the same position as the tool scope on personas users author themselves. Setting a persona to None does not stop tools from being reachable in a turn driven by it.

To actually restrict what a group can reach, use the group’s plugin allowlist and the bindings below. Read-only is reserved for a future release and behaves like the others today.

Reasoning effort — passed through to providers that accept it: (provider default), None, Minimal, Low, Medium, High, XHigh. Leave it at (provider default) unless a persona genuinely needs more or less deliberation than the group’s model normally applies; a model that does not support the parameter ignores it.

There is no preferred provider

Unlike a user’s own persona, a managed persona cannot pin an AI provider. Provider ids are per-user rows in each client’s local store, so an id an admin picks here would not resolve on anybody else’s machine. Route models per group on the group’s provider override instead — or use Model type above, which names a routing key the group resolves to a provider rather than naming the provider itself.

Assigning it to groups

Open the persona and check the groups under Group assignment. Save group assignment commits just that card; the page’s own Save button commits everything — content, groups and bindings — so either works.

Members of a checked group see the persona in their client’s persona picker on the next sync. It is invisible to everyone else, and to nobody at all until assigned.

Assignment is capped per group by Quotas.ManagedPersonas, which defaults to 25. This is a separate counter from Quotas.Personas (default 50) — a managed persona never charges a user’s own persona quota.

Binding knowledge bases and connectors

Under Plugin bindings, check the knowledge bases and connectors this persona may reach, then press Save plugin bindings (or the page’s Save, which covers this card too).

This is what makes persona-scoped resources work. Resolution happens per turn:

Bound via	Visible when
The group only	Always, for every member of that group
This persona only	Only while the user has this persona selected
Both	Always

A knowledge base bound solely to a persona stays out of the group’s default tool set entirely. A Brandvoice glossary is therefore absent from ordinary chat and appears only under Brandvoice.

Persona-bound knowledge bases still charge the group's KB quota

Quotas.KnowledgeBases counts a group’s knowledge bases whether the group reaches them directly or through a managed persona it is assigned to. Binding a KB to a persona is a routing decision, not a way around the cap — assignment and binding are both refused with 409 if the result would exceed it. See Knowledge bases.

Stale bindings — a plugin that has since been deleted — are pruned when the editor loads and rejected if sent back.

“No knowledge bases in the catalog.”

Both binding lists show only resources that are active and not deleted. So a knowledge base or connector you know exists can be missing here for one reason: its Active switch is off. Turn it back on (Knowledge bases, Connectors) and it reappears in the list on the next load.

The message is also literal when the catalog is genuinely empty — a fresh instance has no knowledge bases and no connectors, so both lists say this until you create one.

Taking one out of service

Two ways, and they mean different things:

• Turn off Active. The persona stops being delivered but keeps its groups and bindings. Clients drop it on the next sync. Turn it back on to republish.
• Delete it. A soft delete — the row is tombstoned; assignments and bindings are left in place rather than cascaded away.

Either way the client handles the disappearance gracefully: a user who had that persona selected is switched to a fallback and told once, by name, that it is no longer available.

An omitted Active flag never republishes

Every content field on the editor is full-replace on save — clear one and it is cleared. Active deliberately is not: a partial save made to fix a typo cannot silently re-enable a persona somebody disabled on purpose.

Licensing

Reading this page needs no feature. Every write — create, update, delete, group assignment, plugin binding — requires the GroupManagement licence feature. Without it the editor’s controls are disabled and the API refuses the write. See Licensing.

What reaches the client

Managed personas travel down only, on the managedPersonas channel of GET /api/sync/pull. A client never pushes one back: there is no push path, a pushed managed id is quarantined rather than applied, and the desktop editor is locked.

In the desktop client a managed persona appears in Settings → Assistant → Personas with a Managed badge next to the built-ins and the user’s own. Edit and delete are refused; Duplicate makes an ordinary, editable user persona with a fresh id. See the Personas guide.

The client tells the server which persona is driving a turn via the X-Pia-Persona header. The server does not trust it — it re-checks that the persona is assigned to the caller’s group before honouring any of its bindings, so a crafted header cannot reach another group’s resources.

Auditing

Every write logs exactly one event: ManagedPersona.Created, ManagedPersona.Updated, ManagedPersona.Deleted, ManagedPersona.GroupsChanged, ManagedPersona.PluginsChanged. Filter for them on the Audit log.