Roles
Built-in and custom roles, feature grants, role priority, and the rules for assigning and editing roles.
Roles in Neuralis govern humans and agents with one vocabulary: the same grants that decide which tabs a user sees decide which tools, skills and files an agent's model is even told about, and provisioning an agent is gated exactly like inviting a colleague. Nobody can mint an agent stronger than themselves.
Authorization has two independent dimensions, both defined per project. Feature grants answer "what can this role do": every route, tool and contribution declares the feature it requires, checked on the server. Role priority answers "how strong is this role", and with it "which roles may this caller hand out or edit".
Built-in roles
Five built-in roles anchor the scale. Their priorities are fixed; their grants are editable per project like any role's.
| Role | Priority | Agent access | Can invite | Can manage roles | Default grants |
|---|---|---|---|---|---|
owner | 1 | all agents | yes | yes | every feature (*) |
admin | 2 | all agents | yes | yes | every native feature outside platform.*, listed one by one |
manager | 10 | all agents | no | no | a curated set |
member | 20 | own agents | no | no | a curated set |
viewer | 30 | view only | no | no | a curated set |
Agent access own restricts a user to the agents they created or are assigned
to, and view is read-only (see Multi-tenancy).
Role priority
Priority is one whole number per role in 1..99, lower = stronger. The
built-ins sit at 1, 2, 10, 20 and 30, and the gaps are deliberate: a role you
define declares its own number and slots between two built-ins without
renumbering anything. Anything outside 1..99 (including 0, 100, a
fraction or a numeric string) is refused on every write path.
A custom role's name is cosmetic; its priority is enforced. Calling a role
"Director" grants nothing, and a role label with no declared priority resolves
to the weakest possible strength, so it can always be assigned but never be an
escalation. A role you define at priority 1 governs like the built-in owner:
feature grants, priority thresholds and route guards read strength and grants,
never the name.
Assigning a role
A caller may assign a role only if its priority is equal to or weaker than the caller's own.
A member (20) can hand out member or viewer but cannot invite an
admin; an admin (2) cannot promote anyone to owner. The rule holds on
every assignment surface (invitations, role changes, agent provisioning) through
one shared check, and removing a member follows it too: you cannot remove
someone stronger than yourself. A disallowed assignment answers 403. A
member's strength always comes from their role; there is no per-member override.
Editing a role
Changing what a role is (its grants, flags or priority) is stricter than handing it out:
Strength. You may edit only roles strictly weaker than your own. A role at or above your strength cannot be modified or deleted, including your own role.
Conservation. You may grant only, and revoke only, features you hold yourself.
Because you cannot edit your own role, locking yourself out of your own project is impossible. Governance flows downward, and the strongest role in a project is fixed once the project exists; defining a new role at your own strength is the one place equality is allowed. Conservation stops a project administrator from quietly stripping capabilities from a role above them; deleting a role runs the same check over everything it held. Role and membership maps are submitted whole, so leaving an entry out is a deletion and is authorized as one.
Feature grants
A feature is a string key such as core.execute, files.read or
platform.config:
- a role lists what it holds, and the
*wildcard passes every check; - a surface that requires several features requires all of them;
- a surface that declares none is ungated;
- a feature no loaded package provides is held by nobody except a wildcard holder, so requiring an unknown feature denies by default.
Two tiers
The prefix states where a decision acts:
project.*acts inside your current project and never touches another tenant;platform.*crosses the project boundary: another tenant's data, a platform-global file, cross-user records or the platform-wide credential scope.
No platform.* feature carries a default grant. An owner can grant one to
any role, but nothing seeds it. So the seeded admin is the strongest role
inside a project and does not cross it: it cannot see a project it is not a
member of, read the platform audit log, change platform settings or act on
another member's scope. Its list is enumerated rather than a wildcard, so a
feature contributed by a package dropped into a project is not inherited
automatically; an owner grants it by hand. The admin package's features are
listed on admin Features.
Running a shell needs two features
core.execute runs an agent. Opening a shell also needs the entry feature
of the plane it opens on:
| Plane | Entry feature | Notes |
|---|---|---|
| The local plane (the app container, or the server itself without Docker) | exec.local | Granted wherever core.execute is |
| The local plane, unrestricted | exec.unconfined | A bypass of the path policy and OS sandbox on the local plane only; it grants nothing on a device. Owner and admin by default |
| A paired device you own | device.own | Member default |
| A paired device someone else owns | exec.device | Admin tier, never a bypass; only while that device runs sandboxed and online |
| A virtual desktop or other exec-capable source | the feature its connector declares | the desktop's is exec.machine |
An entry feature grants nothing by itself; the source's own path policy then decides whether that caller may start a command in that directory.
Governance is a flag, not a feature
Editing a project's role map, members, limits or agent ownership needs the
role's canManageRoles flag, not a feature, so governance can never be granted
through a capability toggle. owner and admin carry it; any role you define
can be given it. A role holding project.roles can read the role map;
rewriting it needs the flag.
Who created a project is not who governs it
A project keeps its creator for provenance and display, and that grants
nothing. Archiving, restoring or deleting a project, and changing its name or
description, need an owner-strength role (priority 1) in it. Acting on a
platform user's account (disable, enable, password reset, rename, delete) needs
governing that user in every project they belong to, and deleting also needs
platform.users. Transferring governance is therefore just a role change, and a
creator who was demoted keeps no residual powers.
Roles and path rules
URI policies can grant a path to callers by strength: a rule naming a built-in role as "at least as strong as" matches any role whose priority is at least that strong, whatever its name, so a custom owner-strength role passes an owner rule. The rules the packages ship are all written this way. A rule your project stores itself may also name the project's own roles directly; such a rule matches that name only, and its names are checked against the project's roles when you save it.
Where features come from
Packages own their feature vocabulary; nothing is hardcoded in the host or the admin UI. A package declares the features it provides and may declare default grants for specific roles, merged once per package version so a later manual revoke is not re-applied on restart. Uninstalling a project package revokes the features it granted. The roles editor reads a catalog built from the packages installed in that project. The package-side contract is on package-system Features.
Multi-tenancy
Projects as the tenancy boundary: membership, isolation guarantees, notifications, spend limits, project lifecycle, per-project packages and agent scoping.
Security
The one security page: the six layers every request passes, deny by default, and the guarantees behind sessions, admin, secrets, agent data, MCP and package content.