Enterprise

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.

RolePriorityAgent accessCan inviteCan manage rolesDefault grants
owner1all agentsyesyesevery feature (*)
admin2all agentsyesyesevery native feature outside platform.*, listed one by one
manager10all agentsnonoa curated set
member20own agentsnonoa curated set
viewer30view onlynonoa 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:

PlaneEntry featureNotes
The local plane (the app container, or the server itself without Docker)exec.localGranted wherever core.execute is
The local plane, unrestrictedexec.unconfinedA 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 owndevice.ownMember default
A paired device someone else ownsexec.deviceAdmin tier, never a bypass; only while that device runs sandboxed and online
A virtual desktop or other exec-capable sourcethe feature its connector declaresthe 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.

On this page