Homelab-manager/ROLES.md

Roles & menu access

Homelab Manager has three roles, ranked lowest to highest: viewer, operator, admin. The first person to sign in becomes admin; everyone after that starts as viewer until an admin changes their role under Administration → Users.

A role can do everything the roles below it can, plus what's listed for it — operator includes everything viewer has, admin includes everything operator has.

Sidebar menu, by role

✅ = the menu item appears for that role · ❌ = it's hidden entirely (not just disabled) — a group that would end up with zero visible items disappears too, and a group left with exactly one just shows as that page's own top-level link.

Menu item	Path	Viewer	Operator	Admin
Dashboard	/	✅	✅	✅
Infrastructure
Servers	/servers	✅	✅	✅
Proxmox	/proxmox	✅	✅	✅
Synology	/synology	✅	✅	✅
Proxmox Backup	/pbs	✅	✅	✅
Docker	/docker	✅	✅	✅
Tailscale	/tailscale	✅	✅	✅
Network
DNS	/dns	✅	✅	✅
Domains	/domains	✅	✅	✅
IP Addresses	/ipam	✅	✅	✅
Consistency	/consistency	✅	✅	✅
Automation
Semaphore	/semaphore	✅	✅	✅
Gitea	/gitea	✅	✅	✅
Secrets	/secrets	✅	✅	✅
Operations
Maintenance	/maintenance	✅	✅	✅
Uptime Kuma	/uptime-kuma	✅	✅	✅
Generator	/generator	✅	✅	✅
Administration
Integrations	/integrations	✅	✅	✅
Users	/users	❌	❌	✅
Sessions	/sessions	❌	❌	✅
Audit Log	/audit-log	❌	✅	✅
Diagnostic Log	/diag-log	❌	❌	✅
Settings	/settings	❌	❌	✅
Privacy (footer link, not in a group)	/privacy	✅	✅	✅

So in practice: every page is visible to every role except the five under Administration — Users, Sessions, and Diagnostic Log need admin; Audit Log needs operator or admin; Settings needs admin.

Being able to see a page isn't the same as being able to change things

Almost every page above is visible to viewers, but most of the buttons on them aren't — a viewer can look at everything but can't act on anything. Operators can use the page's normal working actions (starting a container, syncing DNS, adding a secret, opening a maintenance window…). Some actions on otherwise-viewer-visible pages are held back even further, to admin only:

• Integrations & DNS providers: any operator can use an integration once it's configured (start/stop a guest, run a template, sync DNS records, etc.), but adding, editing, testing, or deleting an integration or DNS provider is admin-only.
• Servers: registering a new server, rotating its agent token, and editing/deleting a server are admin-only; tagging a server and linking/unlinking it to a Proxmox guest just need operator.
• Tags: creating, renaming, recoloring, or deleting a tag is admin-only (applying an existing tag to a server needs operator).
• Everything under Settings (notification channels, badge colors, display prefs, log retention, backup/restore) is admin-only, matching the page itself being admin-only.

If you need the exact role for one specific button rather than this summary, check the corresponding route in server/src/routes/ — each one that needs more than "signed in" calls requireRole("operator") or requireRole("admin") right where that action is defined.