Regain access to the panel

hctl talks to the agent on the master through a local socket, so it works when the panel login is unavailable to you. Use it to unlock a locked account, set a new password, clear a lost authenticator or create a new Owner.

Before you start

You need a shell on the master. Panel users live there, so run the user commands on it.
Run the commands as root with sudo, or add your account to the hyperion-admin group and log in again. Membership gives full control of the node:
Terminal window
```
sudo usermod -aG hyperion-admin "$USER"
```
Know the username of the account. hctl also accepts the numeric id shown by hctl user list.

Steps

List the panel users to see names, roles and which accounts are locked:
Terminal window
```
sudo hctl user list
```
Each line reads id=<n> <username> <<email>> role=<role>. A user with two-factor enrolled has 2FA✓ after the role, and a locked account ends with LOCKED.
Pick the command that matches the problem.

The account is locked (the sign-in page says “This account is locked. Ask an administrator to unlock it.”):
Terminal window
```
sudo hctl user unlock <username>
```
A role was changed by mistake. Set a built-in role back, for example Owner:
Terminal window
```
sudo hctl user set-role <username> super_admin
```
The password is lost. Without --password-stdin the command generates a 24-character password and prints it once:
Terminal window
```
sudo hctl user reset-password <username>
```
To choose the password yourself, pipe it in. No command takes a password as an argument, because other local users can read arguments from /proc:
Terminal window
```
read -rs NEW_PW
printf '%s\n' "$NEW_PW" | sudo hctl user reset-password <username> --password-stdin
```
The authenticator device is lost and no backup codes remain. This removes the user’s two-factor enrollment and its backup codes:
Terminal window
```
sudo hctl user disable-2fa <username>
```
No Owner can sign in at all. Create a new one. The role value for Owner is super_admin:
Terminal window
```
sudo hctl user create <username> --email <address> --role super_admin
```
The command generates a password and prints it once. The other role values are admin, operator (the default), customer and viewer.
Give the person the new password and ask them to change it. They do this on My profile, under Password. See Manage your own account.

Check that it worked

sudo hctl user list shows the account without LOCKED, with the expected role, and without 2FA✓ after disable-2fa.
The person signs in. After disable-2fa, an Administrator or Owner who signs in with the password alone is sent to My profile to enroll again when two-factor sign-in is required. Everyone else can enroll from My profile whenever they like.
The action is in the audit log. Run sudo hctl audit search -q <username> or open Audit log in the panel.

If it fails

The command says the agent socket cannot be reached or access is denied: run it with sudo, or confirm you are in the hyperion-admin group and started a new login session after adding yourself.
no panel user "<name>": no account has that username or id. The match ignores case. Copy the name from sudo hctl user list, and check that you are on the master.
“validation failed: refusing — this would leave the cluster with no active super_admin”: the command would lock, demote or delete the last active Owner. Create or unlock another Owner first.