Roles

Roles let one Anyy Profile contain several assistant identities. A Role changes Anyy's persona and default working style; it does not create a separate user or data space.

Role and Profile boundaries

Every Role in a Profile shares that Profile's:

• Workspace and database;
• USER.md and MEMORY.md memory;
• models, Tools, Skills, and MCP configuration;
• Channels and Cron jobs; and
• session history boundary.

A Role does not select tool names, tool permissions or Codemode mode. Manage those through Tools and Session tool selection.

Use a Role when you want a different voice or working approach. Use a Profile when you need an independent home, memory, credentials, configuration, and history.

Create a Role

1. Open Dashboard → Roles.
2. Select New Role.
3. Enter a permanent Role ID such as scribe.
4. Optionally enter a display name such as Scribe.
5. Select Create role.

Role IDs begin with a lowercase letter or digit and use lowercase letters, digits, dashes, or underscores. The ID becomes part of the Role's storage path and cannot be renamed later. The display name can be changed.

After creation, Dashboard opens the Soul editor. Saving non-empty Soul content completes onboarding while it is pending or active, including for the base default Role.

You can also finish setup in the first-use Role conversation. Anyy saves the current session's Role SOUL.md through a normal tool call and continues the conversation. This tool cannot edit another Role or its display name. It is no longer exposed after onboarding is completed or skipped.

Onboarding state survives restarts, including for default. Direct file edits and CLI Soul updates do not recalculate a saved state; clearing Soul does not reopen completed or skipped onboarding. Finished setup cannot be restarted or changed to the other outcome. An outdated completion request is rejected without changing Soul; ordinary Soul edits remain available.

Write the Soul

Soul is Markdown that defines the Role's identity and default working style. Good Soul instructions are stable and specific:

# Scribe

You turn rough notes into concise, structured writing.

- Preserve the author's meaning.
- Ask before inventing missing facts.
- Prefer short headings and concrete language.

Useful content includes:

• the Role's purpose;
• tone and communication preferences;
• recurring priorities;
• working principles; and
• boundaries that should apply across tasks.

Do not put a one-time request, password, API key, or other secret in Soul. Send temporary instructions in the conversation instead.

Keep Soul small

Write the minimum durable guidance that changes how this Role should work. Long checklists consume context on every turn and are harder to keep consistent.

Select and edit a Role

Open a Role to:

• select Use and make it the Profile's default Role;
• edit its Soul;
• rename its display name; or
• review its ID, onboarding state, and Soul path.

The selected Role is used when a new session does not request another Role explicitly. Existing sessions keep their own Role identity.

The base default Role is always present. You can edit its Soul, but you cannot rename or delete it.

Delete a Role

A non-base Role can be deleted only when it is not selected and no sessions or schedules still reference it. Switch to another Role first, then remove or update those references.

Deleting archives the Role record and removes it from active selection; its Soul file remains. Inspect archived records with anyy role list --include-archived. Shared Profile memory, Workspace, Channels, Skills and other Roles are retained.

CLI equivalents

anyy role list
anyy role get scribe
anyy role create scribe --display-name "Scribe"
anyy role update scribe --soul-file ./SCRIBE.md
anyy role use scribe
anyy role delete scribe

Use --home PATH to target a specific Anyy home and --json when scripting.

Troubleshooting

Problem	Fix
Role ID is rejected	Begin with a lowercase letter or digit; use letters, digits, - or _
Onboarding is pending or active	Save non-empty Soul content in Dashboard
Role cannot be deleted	Select another Role and remove session or Cron references
New chat uses the wrong identity	Confirm the selected Role, or pass --role ROLE_ID when creating the session
You need private memory or credentials	Create a separate Profile instead of another Role

Continue with Memory to manage the personal context shared by Roles.