Create a custom role

Use a custom role when none of the five built-in roles fits, for example a support person who may restart sites and read backups but never delete anything. A custom role is a name, a hosting scope and a list of ticked capabilities.

Before you start

• Sign in as an Owner. Only Owners can open Roles.
• Read Built-in roles and capabilities to see what each capability covers and which pages stay Owner-only. A custom role cannot open Users, Roles, Nodes or edit Settings, even with the matching capability ticked.
• Create the user first with Add and manage panel users if the person does not have an account yet.

Steps

Build the role

1. Open Roles in the sidebar under Administration.
2. Click New role. To start from an existing custom role, click Clone on its row instead. The builder opens pre-filled and the name ends in (copy).
3. In Name, type a short unique label such as Junior support. The field takes up to 64 characters and cannot be empty.
4. Under Hosting scope, choose one.
   • All hostings: the role can act on every hosting in the cluster, limited by its capabilities.
   • Only assigned: the role acts only on hostings an Owner grants to the user on each hosting’s Access tab.
5. Under Capabilities, tick what the role may do. The boxes are grouped as Hosting, WordPress, Backups, TLS, Security, Monitoring, Cluster and Platform. Click Select all on a group to tick all of its boxes. The button then reads Clear all.
6. Click Create role. The Roles page shows Role "<name>" created.

Capabilities that reach beyond one site

Write raw nginx config (admin-level: nginx runs as root) lets the holder write directives that nginx loads as root. Tick it only for people you would trust with an Administrator account. The built-in Operator, Customer and Read-only roles never hold it.

With All hostings scope, the role does not need a per-site grant, but it still can do only what its ticked capabilities allow.

Assign the role

Before you assign a custom role to an Owner

Assigning a custom role replaces the user’s built-in role. A custom role can never open Users, Roles, Nodes or save Settings, even with matching capabilities ticked. Hyperion does not stop you from doing this to the last active Owner, and you would then have nobody who can manage users.

Confirm a second active Owner first: open Users and check another row shows the Owner role with Status active. To undo, run sudo hctl user set-role <username> super_admin on the master, or create a new Owner. See Regain access to the panel.

1. Open Users in the sidebar and click Manage on the user’s row.
2. Under Role, pick the role from the Custom group, then click Save role.

The role applies on the user’s next request. The Users list shows the role name followed by custom.

Edit, clone or delete a role

• Click Edit on the role’s row, change the fields and click Save changes. Every user on the role gets the new permissions on their next request. The page shows Role "<name>" updated.
• Click Clone to make a variant. Save it under a new name.
• Click Delete and confirm Delete role. The button is disabled while the In use column shows users. Move those users to another role first. If you submit the delete anyway, Hyperion refuses with “validation failed: role in use by N user(s)”. The page shows “Role deleted” when a role with no users is removed.

Check that it worked

• The role appears under Custom roles with the right Scope, a Capabilities count and an In use count that matches the users you assigned.
• Ask the person to sign in. Their sidebar shows only the pages their capabilities cover.
• For an Only assigned role, the user sees no hostings until you grant some. See Give a user access to a site.
• The audit log records web.role.create, web.role.update and web.role.delete. See Review the audit log.

If it fails

• “validation failed: role name must not be empty”: type a name in Name.
• The builder returns to the form with an error after Create role: the name is already used by another role, or the agent rejected the save. Read the message above the form and pick a different name.
• “validation failed: role in use by N user(s)”: reassign the users, then delete the role.
• A ticked capability does nothing: some pages check for the Owner role itself. They are listed in Built-in roles and capabilities.
• The user cannot be picked on a site’s Access tab: see Give a user access to a site.