Roles

Roles are profile-local identities for Anyy. A role carries a display name, status, onboarding state, and a SOUL.md persona file. Roles let the same profile switch between different assistant voices or purposes without creating a separate profile.

Roles are not users, permission groups, or provider accounts. They share the profile's memory, skills, channels, providers, and gateway state.

What Is A Role

The default role is always default and maps to:

<home>/SOUL.md

Named roles map to:

<home>/roles/<role_id>/SOUL.md

SOUL.md can define role persona, tone, boundaries, uncertainty style, and how Anyy should collaborate with you. It cannot override provider identity, tool policy, approvals, ChangePlans, audit, or explicit user instructions.

Role Scope

Role identity is part of session scope:

Scope item	Behavior
Existing session	Keeps the role it was created with.
New local session	Uses the profile's default_role pointer, or default if unset.
Default role	Uses <home>/SOUL.md; roles/default/SOUL.md is not materialized.
Named role	Uses roles/<role_id>/SOUL.md.
Missing named SOUL.md	Falls back to default role identity during prompt assembly.

Memory is profile-level. USER.md and MEMORY.md are shared across roles.

Create A Role

anyy role create research --display-name "Research"

Role IDs must be path-safe lowercase identifiers. The ID is used in the role folder path, so treat it as permanent.

List roles:

anyy role list
anyy role list --include-archived
anyy role list --json

Update A Role

Update display name:

anyy role update research --display-name "Research"

Update the role persona from a markdown file:

anyy role update research --soul-file ./research.SOUL.md

The default role can update <home>/SOUL.md, but its display name and base role metadata are guarded. Use a named role when you need a distinct identity.

Use A Role

Set the profile default role for new sessions:

anyy role use research

This writes the profile default_role pointer. It does not rewrite existing session roles.

Inspect one role:

anyy role get research
anyy role get research --json

Delete a role when it is no longer needed:

anyy role delete research

Delete soft-deletes the role and removes it from the Dashboard roles list. Anyy blocks deletion when the role is selected as default or still has active references such as channel bindings, cron jobs, background jobs, session queue items, tasks, or subagent runs.

Role Onboarding

Named roles can start in a pending or active onboarding state. During onboarding, Anyy discusses the role's name, purpose, tone, boundaries, ambiguity handling, disagreement style, and user expectations.

The role_onboarding_complete tool can propose final SOUL.md content, but it requires user approval before writing durable role identity. Approval summary includes a SOUL.md preview.

A completed role records onboarding completion time and uses the written SOUL.md in future prompt assembly.

Roles In Dashboard

The dashboard's Roles page can:

Action	Behavior
List roles	Shows selected role, active roles, and setup state.
Create role	Creates a role identity and opens the SOUL.md editor.
Use role	Selects the profile default role for new sessions.
Edit SOUL.md	Saves role persona through role RPC.
Rename	Updates display name for named roles.
Delete	Soft-deletes roles that are not actively referenced.

Dashboard role writes use authenticated dashboard sessions and same-origin POST checks. Role file writes stay under the active profile home.