# Roles (https://docs.neuralisapp.com/enterprise/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 [#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](https://docs.neuralisapp.com/enterprise/multi-tenancy.md#agent-scoping)).

## Role priority [#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 [#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 [#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 [#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 [#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](https://docs.neuralisapp.com/admin/features.md).

### Running a shell needs two 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 [#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 [#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 [#roles-and-path-rules]

[URI policies](https://docs.neuralisapp.com/package-system/uri-policies.md) 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 [#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](https://docs.neuralisapp.com/package-system/features.md).
