Files
Homelab-manager/ROLES.md
T
bobbanandClaude Sonnet 5.5 788b3e073c A To do card on server pages and in a device's drawer
- The open jobs about a server (or device) are listed on its page, with a line to add another already about it and a box to tick one off with Undo
- GET /api/todos takes ?targetType=&targetId= to list only those about one thing
- README and ROLES updated

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-20 22:46:12 +02:00

11 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 (Map → Dependencies) /map?view=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 (Users → Signed in now) /users?view=sessions ❌ ❌ ✅
Audit Log (Change log → Raw audit log) /changes?view=audit ❌ ✅ ✅
Diagnostic Log (Integrations → Call log) /integrations?view=calls ❌ ❌ ✅
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 (with Signed in now) and Settings need admin; the Call log tab of Integrations needs admin (operators and viewers see Integrations without it); the raw audit log, a tab of the Change log, needs operator or admin. Sessions, the Audit Log, the Diagnostic Log and Dependencies were pages of their own once; their old addresses redirect to the sections above.

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 → Notifications → 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.
  • Bulk actions (the bar that appears when rows are ticked) need the same role as the single action: operator to acknowledge, silence, tag, change hardware and undo any of those; administrator for Runs on… on several servers (and its undo). Viewers do not see the tick boxes. The Noise tab of Alerts is for everyone signed in.
  • API tokens (user menu): anyone signed in makes, sees and removes their own, and nobody else's; a token can only read (GET /api/v1), sees what its owner sees, and is removed with its owner. The chart ranges and history are for everyone signed in.
  • My work is shown to operators and administrators and only ever lists their own alerts, maintenance and update runs; the buttons on it (change an acknowledgement, extend or end a window) need operator, like the pages they come from. Settings search is part of Settings, which is administrators'.
  • Network devices (Network → Network devices): everyone can see the devices, networks and Wi-Fi names read from UniFi controllers; Read now and putting a device under maintenance need operator; adding the UniFi integration itself (a key or login) is an administrator's job, like any integration.
  • Dependencies: everyone can see what needs what; adding and removing one needs operator. So does adding or hiding a suggested one.
  • To do and Notes (Operations → To do, the To do and Notes cards on a server's page, a device's Notes drawer): everyone signed in reads them; adding, editing, ticking off and removing a job, and writing a note, need operator.
  • Racks (Inventory → Racks) and the network diagram: everyone signed in. A rack is made from the hardware's where and rack unit, which operators edit on the inventory page.
  • Proxy hosts (Network → Proxy hosts): everyone signed in sees what Nginx Proxy Manager serves; Read now needs operator; adding the integration (its login) is an administrator's job.
  • Home Assistant (Monitoring → Home Assistant): everyone signed in sees what is watched, its state and history; choosing what to watch, its limits, stopping and Read now need operator (the list of all entities is read live, so only operators see it); adding the integration (its token) is an administrator's job.
  • 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.
  • Patch plans (Updates → Patch plans) can be seen by everyone, with how they went; making, changing, switching off and removing one needs administrator (it will run on its own, at night); Run now and Stop need operator, like an update run. The Monthly report page is for everyone signed in; sending it now, and its schedule (Settings), are administrators'. Mark as expected on a server's Ports card (which ends a new-port alert) needs operator, like any note on a port.
  • 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 (Alerts → History) 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 → Data → 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.
  • Heartbeats and the Coming up list are visible to everyone signed in; only administrators see a heartbeat's address, and make, change, remove or give a new address to one, and make the calendar feed of Coming up (a share link). Suggested checks are administrators' like the checks themselves. A job's call to its address needs no role: the token is the access.
  • 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.