Files
Homelab-manager/ROLES.md
T
bobbanandClaude Sonnet 5.5 c05c847d17 Profile pictures from Gravatar or the identity provider, fetched and kept by the server
Both sources are off until switched on under Settings, Sign-in. The server asks only
gravatar.com (by a hash of the email) and the identity provider's own host, accepts only
small PNG/JPEG/WebP/GIF, keeps each picture for a day and serves it from /api/avatars/<id>,
so browsers never contact either. Shown in the user menu and on the Users page, with initials
as the fallback; the Privacy page says when it is on.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-18 23:47:50 +02:00

7.6 KiB

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 ✅ ✅ ✅
Backup coverage /backups ✅ ✅ ✅
Inventory /inventory ✅ ✅ ✅
Dependencies /dependencies ✅ ✅ ✅
Endpoints /endpoints ✅ ✅ ✅
Change log /changes — ✅ ✅
Docker /docker ✅ ✅ ✅
Tailscale /tailscale ✅ ✅ ✅
Network
DNS /dns ✅ ✅ ✅
Domains /domains ✅ ✅ ✅
IP Addresses /ipam ✅ ✅ ✅
Ports /ports ✅ ✅ ✅
Consistency /consistency ✅ ✅ ✅
Automation
Semaphore /semaphore ✅ ✅ ✅
Gitea /gitea ✅ ✅ ✅
Secrets /secrets ✅ ✅ ✅
Operations
Alerts /alerts ✅ ✅ ✅
Maintenance /maintenance ✅ ✅ ✅
Updates /updates ✅ ✅ ✅
Uptime Kuma /uptime-kuma ✅ ✅ ✅
osTicket /osticket ✅ ✅ ✅
Admin Links /admin-links ✅ ✅ ✅
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).
  • Ports: everyone can see both the agent-reported and manual tables; adding, editing, or deleting a manual port opening needs operator.
  • Admin Links: everyone can see and open every server's admin bookmarks, from that server's own page or the summary page; adding, editing, or removing one needs operator, from either place.
  • Generator: everyone can use it; the name lists it picks server names from are edited under Settings → Names, which is admin-only (and so is importing names from Skatteverket).
  • Alert tickets: everyone sees which alerts have an osTicket ticket (a badge on the Alerts page, linking to the ticket in osTicket); switching the feature on, choosing what opens a ticket, and sending a test ticket are under Settings → Alert tickets, which is admin-only.
  • Runbooks: everyone reads them (on a server's page, an integration's card, next to an alert); writing, editing and removing one needs operator.
  • Inventory: everyone can see the hardware (and print its labels); adding, editing and removing needs operator, and so does Refresh from agent; the price of power used for the running cost is admin-only.
  • Dependencies: everyone can see what needs what; adding and removing one needs operator.
  • Endpoints: everyone sees the checks and how they are doing; adding, changing and removing one is administrator-only (each makes the server connect somewhere); Check now needs operator.
  • Restore tests: everyone sees them on the Backup coverage page; recording one needs operator; removing one is administrator-only.
  • Change log: operators and administrators (it is made from the audit log, which has the same readers).
  • Push notifications: an administrator switches the channel on (Settings → Notifications). Each person, whatever their role, adds and removes their own browsers and can send a test to them; an administrator can remove anyone's.
  • Backup coverage is a read-only page for everyone. On Updates, everyone sees what is waiting and how update runs are going; starting an update run (Update…) or stopping one needs operator.
  • Acknowledging an alert, handing it over, and taking it back need operator (the person it is handed to must be an operator or administrator); everyone sees who has what. Incidents are readable by everyone signed in; writing a note needs operator, and a note can be removed by its author or an administrator.
  • Database backups (Settings → Backup: making, downloading, uploading, checking, restoring and deleting them, and the schedule) are administrator-only: a backup holds the audit log, every server's address, the hashed agent tokens and all the stored credentials (encrypted).
  • Alert limits on a server's page: everyone can see the ones a server has of its own; only an administrator changes them. The same goes for the services to ignore on its Host health card. Everyone sees What the agent couldn't collect.
  • Host health (failed services, disk health, ZFS pools) is shown to everyone on a server's page; Update agents automatically on the Servers page is admin-only.
  • Profile pictures are shown to everyone signed in (/api/avatars/<id>, the same people whose names everyone already sees); which sources are allowed is under Settings → Sign-in, so admin-only.
  • Sign-in groups, metrics tokens, event webhooks, share links (the wall display and the status pages, and what is on them) and the Grafana dashboard download are all under Settings, so admin-only; /metrics itself needs a metrics token, not a login.
  • 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.