User Management

Pinchy uses an invite-only system for user onboarding. Admins create invite links, new users claim them by setting up their account, and then they are guided through an onboarding conversation with Smithers. This guide covers the full lifecycle: inviting, onboarding, managing, and deactivating users.

Prerequisites

• Pinchy is running (see Quick Start)
• You are logged in as an admin

Inviting users

Only admins can invite new users. Here is how:

1. Go to Settings → Users.
2. Click the Invite User button in the top right.
3. Fill out the invite form:
   • Email (optional) — Pre-fills the email for the new user’s account. If left empty, the invite link can be used by anyone.
   • Role — Choose Member or Admin.
   • Groups Enterprise — If you have an active enterprise license and have created groups, you can assign the new user to one or more groups during invitation. See Groups for details.
4. Click Create Invite.
5. Copy the generated invite link and share it with the user.

On devices that support it, a Share button appears instead of Copy, letting you send the link directly via your operating system’s share sheet.

Tip

The email field is optional. If you leave it empty, anyone with the link can claim the invite. If you enter an email, the new account is created with that address.

Note

If your enterprise license has a seat cap and all seats are in use, the Invite User button is disabled and a banner explains how many seats are in use. To free up a seat, revoke a pending invitation or deactivate an existing user. See Enterprise Setup — Seat cap enforcement for details.

Invite token details

• Each invite token is valid for 7 days from creation.
• Tokens are single-use — once claimed, the token cannot be reused.
• Tokens are stored as SHA-256 hashes in the database. The plain token only appears once, in the invite link.
• If a token expires before the user claims it, you can resend the invite from the user list (this creates a fresh token).
• Pending invites can be revoked at any time by clicking the Revoke button next to the invite entry.

Accepting an invite

When a new user opens the invite link, they see the account creation page:

1. The page shows the heading “You’ve been invited to Pinchy”.
2. The user enters their name and chooses a password. Passwords must be at least 12 characters, contain at least one letter and one digit, and must not be on the breach-list of common passwords.
3. After clicking Create account, a success message confirms the account was created.
4. The user clicks Continue to sign in and logs in with their email and password.
5. After their first login, Smithers (the onboarding agent) greets them with a short interview to learn about the user and set up their personal context.

Note

If the invite link is invalid or expired, the user sees an error message. Ask an admin to resend the invite.

Managing users

The Settings → Users page shows all users and pending invites in a single list. Each entry displays:

• Name — The user’s display name (or a dash for pending invites).
• Email — The user’s email address.
• Role — Admin or Member.
• Groups Enterprise — Group memberships. Only visible with an active enterprise license.
• Status — Active, Pending (invite not yet claimed), Expired (invite token expired), or Deactivated.

Viewing user details

Click on any active user row to open the user detail panel. From here you can:

• Change their role — Switch between Admin and Member using the Role dropdown. You cannot change your own role, and you cannot demote the last remaining admin.
• Manage group memberships Enterprise — Check or uncheck groups to add or remove the user from groups.
• Reset their password — Generate a password reset link (see below).
• Deactivate the user — Prevent the user from logging in (see below).

Click Save to apply any role or group changes.

How groups affect agent access

Group membership determines which restricted agents a user can see. Agents configured with Restricted visibility in Agent Settings → Access list one or more groups; only members of those groups (and admins) can see the agent in the sidebar or message it via Telegram. Agents set to All users ignore group membership entirely.

Changes propagate immediately: removing a user from a group revokes their access to restricted agents on the next sidebar refresh, and adding them grants access without a restart. For the full group model, see Groups.

Changing a user’s role

1. Click on the user in the user list.
2. In the detail panel, change the Role dropdown from Member to Admin (or vice versa).
3. Click Save.

Caution

You cannot demote the last admin. Pinchy requires at least one active admin at all times.

Resetting a user’s password

If a user forgets their password, an admin can generate a reset link:

1. Click on the user in the user list.
2. In the detail panel, click Reset Password.
3. A reset link appears. Copy it and share it with the user.
4. The user opens the link, enters a new password, and regains access.

Reset links follow the same rules as invite tokens: valid for 7 days, single-use.

Deactivating a user

Deactivation prevents a user from logging in without permanently deleting their data.

1. Click on the user in the user list.
2. In the detail panel, click Deactivate.
3. Confirm the action in the dialog.

When a user is deactivated:

• They can no longer log in.
• Their personal agents are soft-deleted.
• Their data remains in the database and can be restored.
• The user appears as “Deactivated” in the user list with reduced opacity.

You cannot deactivate your own account.

Reactivating a user

To restore a deactivated user:

1. Click on the deactivated user in the user list.
2. In the detail panel, click Reactivate.

The user can log in again immediately.

Managing pending invites

Pending and expired invites appear in the user list alongside active users:

• Pending invites show a Pending status badge and a Revoke button to cancel the invite.
• Expired invites show an Expired status badge and a Resend button to generate a fresh invite link.

Profile settings

Every user (not just admins) can manage their own profile at Settings → Profile. This page has three sections:

Changing your name

1. Go to Settings → Profile.
2. Update the Name field.
3. Click Save.

Changing your password

1. Go to Settings → Profile.
2. In the Change Password section, enter your current password, then your new password, and confirm it. Passwords must be at least 12 characters, contain at least one letter and one digit, and must not appear on the breach-list of common passwords.
3. Click Change Password.

Logging out

Click the Log out button in the Session section to end your current session and return to the login page.

Emergency admin password reset (CLI)

If the admin has lost their password and there is no other admin who can generate a reset link through the UI, you can reset the password directly from the command line.

Run the following command on the server where Pinchy is deployed:

docker compose exec pinchy pnpm reset-admin

This finds the first admin user, generates a new random password, and prints it to the terminal:

Admin password reset for: admin@example.com
New password: aB3kLm9xPqRs7wZn

To reset the password for a specific user by email:

docker compose exec pinchy pnpm reset-admin --email admin@example.com

Caution

The generated password is shown only once. Make sure to copy it immediately. After logging in, change the password via Settings → Profile → Change Password.

Note

This command requires direct access to the server running Pinchy. It connects to the database using the DATABASE_URL environment variable configured in Docker Compose.

Audit trail

All user management actions performed by admins are logged in the audit trail:

Action	Audit event
User invited	user.invited
Invite blocked (seat cap)	user.invite_blocked
Role changed	user.role_updated
Group memberships changed	user.groups_updated
User reactivated	user.updated
User deactivated	user.deleted

Each entry records which admin took the action, the affected user’s name and email, and before/after values for role or group changes. See Audit Trail for more information on viewing and exporting audit logs.