Users & RBAC
Cloud OS supports multiple user accounts with role-based access control (RBAC). There are three roles, and all user actions are tracked in an audit log.
Built-in Roles
Today the dividing line is Admin vs. everyone else: anything that manages the server is admin-only, and Operator is exactly the same as Viewer — no endpoint grants an Operator anything a Viewer cannot do. (The two non-admin roles are kept separate so existing accounts and invitations stay valid and the roles can diverge later; there is no “operator can install apps or run backups” tier.)
| Role | Can do | Cannot do |
|---|---|---|
| Admin | Everything: install, uninstall, start, stop and restart apps; app and container logs; container details (environment, command, mounts); domains and reverse-proxy routes; backups and restores; updates; users, invitations and roles; the audit and activity logs; SSO; system settings and services; mail relay, mail stack and mailboxes; the host terminal and host File Manager; Server Mode (containers, disks, storage, network, crontab, database manager, tunnels); AI runtimes, models, providers, MCP servers and tools, skills, workflows; changing the shared AI memory store and learned agent knowledge; public-tunnel logs; plugins and marketplace installs and uninstalls; Family supervision (monitoring, policies, live screen, pairing); the host tools of Molly and the AI chat | Read other users’ AI or Molly conversations — those are private to their owner |
| Operator | Sign in, use the personal apps (Notes, Drive, Docs, Sheets, Slides, Calendar, their own Mail inbox, Bookmarks, Whiteboards, …), view the dashboard, monitoring, alerts, app and container status; chat with Molly and the AI assistants (read-only tools; their own conversations only), run Docker-sandboxed skills; browse and rate the marketplaces; see what Family collects about them; create their own API keys and pair a phone | Anything in the Admin column: no app installs or app start/stop, no app or container logs, no backups (not even the list), no user management, no host shell or file access, no workflow or skill changes, no Family supervision |
| Viewer | Same as Operator | Same as Operator |
Conversations with Molly and the AI Hub are private: each user sees only their own, and requests for someone else’s conversation answer 404 — for admins too. If Molly or the AI Hub is asked to open a conversation you can’t see (an old link, or the last conversation remembered by this browser from another account), it says This conversation isn’t available and starts a new one.
What non-admins see
The desktop follows the same rules, so Operators and Viewers don’t run into 403 errors:
- Logs (Security → Logs) is not in their menus; a direct link shows an “Admins only” screen. The app detail page has no Logs tab.
- Containers and Public Tunnel show the list without row actions (start/stop, restart, inspect, exec shell, logs, delete).
- Settings → Mail shows a short note instead of the mail server, relay and DNS sections; their own inbox stays in Mail. When the mail server is off, Mail tells them to ask an administrator.
- Settings → Family shows what is collected about them and the hardening attestation read-only, without the Control Panel pairing section.
- The dashboard’s Quick actions (install, terminal, backup, logs) are dimmed with an “Admins only” tooltip.
Permission enforcement happens at the API level. Unauthorized requests return a 403 Forbidden response regardless of how they are made (UI, CLI, API key, paired phone, Molly or direct API call). When a non-admin asks Molly or the AI chat to do an admin action, nothing runs — the assistant answers that an administrator has to do it. See Security Hardening for the full list.
User Management
Open Users (Server mode: dock → Admin → Users, or Ctrl/⌘+K → Users) to manage user accounts. The page has Users, Invitations and Activity Log tabs, with role filter chips and search. Admin users can:
- View all users with their role and status
- Invite new users
- Edit user roles
- Disable or delete user accounts
- Manage individual user sessions
User Invitations
- Click Invite User
- Enter the user email address
- Select a role (Admin, Operator, or Viewer)
- Click Send Invitation
The invited user receives an email with a setup link where they create a password and optionally enable 2FA. The invitation expires after 72 hours.
If email is not configured, you can share the invitation link manually. It is displayed in the UI after creating the invitation.
Invitation links open the invitation page, where the new user sets a name and password.
Two-Factor Authentication (2FA)
For passwordless sign-in with passkeys, approving a sign-in from another device and the lock screen, see Sign-in & Lock Screen.
Cloud OS supports TOTP-based 2FA compatible with Google Authenticator, Authy, and similar apps.
Enabling 2FA
- Open Profile → Security (account menu → Profile)
- Click Enable 2FA
- Scan the QR code with your authenticator app
- Enter the 6-digit code to verify
- Save the backup codes in a secure location
Backup Codes
During 2FA setup, Cloud OS generates a set of one-time backup codes. These can be used to log in if you lose access to your authenticator app. Each code can only be used once.
Store backup codes securely. If you lose both your authenticator device and backup codes, an Admin user will need to disable 2FA on your account.
Enforcing 2FA
Admins can require 2FA for all users in Settings > Security > Require 2FA. When enabled, users without 2FA are prompted to set it up on their next login.
Session Management
Each user can view and manage their active sessions under Profile → Security → Sessions. A session entry shows:
- Browser and operating system
- IP address
- Last activity time
- Creation time
Click Revoke next to any session to immediately invalidate it. Admins can view and revoke sessions for any user from the user management page.
API Keys
Users can generate API keys for programmatic access to the Cloud OS REST API.
Key Format
API keys use the qzr_ prefix followed by a unique identifier:
qzr_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6Key Authentication
Send the key in the X-API-Key header:
X-API-Key: qzr_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6Managing API Keys
Manage keys in either of two places:
- The API page (Ctrl/⌘+K → API keys, or dock → Admin → API in Server mode). It shows the REST and MCP reference together with an API keys panel and a Create key button.
- Settings → API Keys, also linked from Profile → Security.
From there you can:
- Create a key with a name, scopes (or All scopes) and an optional expiry in days. The key is shown once: copy it straight away.
- See when each key expires and when it was last used.
- Revoke a key. Revoking asks for confirmation.
API keys act as the user who created them, with that user’s current role: a Viewer’s key is a Viewer, demoting the owner demotes their keys at once, and deleting the owner revokes them. Keys created with specific scopes (for example monitoring or apps) reach only those areas of the API; a key with all scopes (*) reaches everything its owner may.
Activity and Audit Logging
Cloud OS records all user actions in an audit log shown on the Users → Activity Log tab and, for every action on the node, in Audit log (dock → Security → Audit log). Each log entry includes:
| Field | Description |
|---|---|
| Timestamp | When the action occurred |
| User | Who performed the action |
| Action | What was done (e.g., “Installed Nextcloud”, “Stopped Grafana”) |
| Resource | The affected resource (app, user, backup, etc.) |
| IP Address | The IP the user connected from |
| User Agent | The browser or CLI used |
Filtering the Activity Log
Use the filters at the top of the activity log to narrow results:
- User — show actions from a specific user
- Action type — filter by category (app, auth, backup, settings, etc.)
- Date range — show activity within a specific time period
Troubleshooting
Invited user did not receive the email
Check the outbound SMTP relay under Settings → Mail. Send a test email to verify the SMTP settings work. Also check the invited user spam folder.
User cannot access a feature
Verify the user role. Everything that manages the server (apps, app and container logs, backups, users, settings, mail administration, the host shell and files, Server Mode, AI administration, Family supervision) needs the Admin role; Operators and Viewers get 403. Check the role assignment on the Users page.
2FA code is incorrect
TOTP codes are time-based. Ensure the authenticator device clock is synchronized. A drift of more than 30 seconds will cause codes to fail. If the user is locked out, an Admin can disable 2FA on their account from the user management page.
Forgot the admin password?
If nobody who can sign in is an admin any more, reset the password from the server’s console (SSH or a local terminal):
sudo quazzar-cli admin users # find the admin's email
sudo quazzar-cli admin reset-password # prompts for the email and the new password (twice)All of that account’s sessions are signed out. If the admin also lost their authenticator, add
--reset-2fa to turn two-factor authentication off — turn it back on after signing in. In
Docker, run it inside the container: docker exec -it <container> quazzar-cli admin reset-password.
The reset shows up in the activity log. Step-by-step guide: Password Recovery; see the CLI reference
for scripting and error messages.
API key returns 401 Unauthorized
Verify the key has not expired or been revoked, that its owner still exists, and that it is sent as X-API-Key: qzr_…. A 403 means the owner’s role does not allow the endpoint, or the key’s scopes don’t cover it.