Skip to main content
Homarr provides comprehensive user management capabilities, allowing you to control access to boards, integrations, and administrative functions through a flexible groups and permissions system.

​
Authentication Providers

Before managing users, you need to configure authentication providers. Homarr supports:
  • Credentials: Username and password authentication
  • OIDC: OpenID Connect for SSO integration
  • LDAP: Active Directory and LDAP authentication
Configure providers via the AUTH_PROVIDERS environment variable: 
AUTH_PROVIDERS="credentials,oidc"
See Authentication Providers for detailed setup.

​
Creating User Accounts

​
Creating Users via Web Interface

1

Access User Management

Navigate to Settings > Users in the Homarr interface. You need admin permissions to access this section.
2

Create New User

Click the Add User button to open the user creation form.
3

Enter User Details

Fill in the required information:
  • Username: Must be unique and follow the username schema
  • Password: Required for credentials provider (minimum requirements apply)
  • Provider: Select the authentication provider (credentials, OIDC, LDAP)
Usernames must be between 3 and 20 characters and can only contain letters, numbers, underscores, and hyphens.
4

Assign to Groups

Select one or more groups for the user. Groups determine the user’s permissions and access levels.At minimum, users should be in the everyone group for basic access.
5

Save User

Click Create to create the user account. The user can now log in with their credentials.

​
Creating Users via CLI

For automated user creation or when the web interface is unavailable, use the CLI.
The CLI is especially useful for creating the first admin user or recovering from lost credentials.

​
Groups and Permissions

​
Understanding Groups

Groups are collections of users with shared permissions. Every user belongs to at least one group, and permissions are assigned at the group level. Default Groups:
  • everyone: Special group that all users automatically belong to. Provides basic access rights.

​
Available Permissions

Homarr uses a role-based permission system:
admin - Full system accessGrants complete control over:
  • All boards and widgets
  • User and group management
  • System settings
  • Integration configuration
Only grant admin permission to trusted users. Admins can modify any system setting.
Board-level permissions control access to specific boards:
  • board-view: View the board and its widgets
  • board-modify: Edit board layout and widget settings
  • board-full: Complete control including deleting the board
Permissions can be assigned to groups or individual users.
Control access to integrations:
  • integration-use: Use the integration in widgets
  • integration-interact: Execute actions through the integration
  • integration-full: Modify integration settings

​
Creating Groups

1

Navigate to Groups

Go to Settings > Groups in the admin interface.
2

Create New Group

Click Add Group and enter:
  • Group Name: Descriptive name (e.g., “Moderators”, “Family Members”)
  • Position: Order in the group list (lower numbers appear first)
3

Assign Permissions

Select the permissions this group should have:
  • Check admin for full access
  • Or select specific board and integration permissions
4

Add Members

Add existing users to this group. Users can belong to multiple groups and will inherit permissions from all their groups.

​
Managing Group Memberships

Users can be added to or removed from groups at any time:
  1. Go to Settings > Groups
  2. Select the group to modify
  3. Add or remove users from the member list
  4. Save changes
Permission changes take effect immediately. Users may need to refresh their browser to see updated access rights.

​
Setting Board Permissions

Board permissions can be configured per-board:
  1. Open the board settings
  2. Navigate to the Permissions tab
  3. Add user or group permissions:
    • Select the user/group
    • Choose permission level (view, modify, full)
    • Save changes

​
Managing User Invites

Invite links allow new users to join your Homarr instance:
1

Create Invite Link

  1. Go to Settings > Invites
  2. Click Create Invite
  3. Configure invite settings:
    • Expiration date (optional)
    • Maximum uses (optional)
    • Default groups for new users
2

Share Invite

Copy the generated invite link and share it with the user. They can use this link to create their account.
3

Track Usage

The invites page shows:
  • How many times an invite was used
  • When it expires
  • Who created it
You can revoke invites at any time.
Use invite links with expiration dates and usage limits for better security. Revoke unused invites regularly.

​
Using the CLI for User Operations

The Homarr CLI provides several commands for user management, particularly useful for administrative tasks or automation.

​
Installation and Setup

The CLI is included with Homarr. Access it via: Docker: 
docker exec -it homarr homarr-cli [command]
Bare Metal: 
cd /path/to/homarr
node packages/cli/index.js [command]

​
CLI Commands

Reset a user’s password. Useful when a user forgets their credentials.
homarr-cli reset-password --username <username>
Options:
  • -u, --username <name>: Username of the account to reset
Example:
docker exec -it homarr homarr-cli reset-password --username admin
The command will:
  1. Generate a new secure random password (48 characters)
  2. Update the user’s password in the database
  3. Delete all existing sessions for that user
  4. Display the new password
The new password is only displayed once. Make sure to save it securely.
Requirements:
  • Credentials provider must be enabled
  • User must exist and use credentials provider
Create a new admin user when no credential-based admin exists. This is a recovery command for when you’ve lost admin access.
homarr-cli recreate-admin --username <username>
Options:
  • -u, --username <name>: Username for the new admin account
Example:
docker exec -it homarr homarr-cli recreate-admin --username newadmin
The command will:
  1. Verify no credential-based admin exists
  2. Create a temporary group with admin permissions
  3. Generate a secure random password
  4. Create the user and assign to admin group
  5. Display the credentials
Output:
We created a new admin user for you.
Please keep in mind, that the admin group has a temporary name.
You should change it to something more meaningful.

  Username: newadmin
  Password: <random-password>
  Group: <temporary-group-id>
After using this command, log in and rename the temporary group to something meaningful like “Administrators”.
Requirements:
  • Credentials provider must be enabled
  • No existing credential-based admin users
  • Username must not already exist
Fix username formatting issues that may exist in older Homarr installations.
homarr-cli fix-usernames
This command normalizes usernames to match the current username schema requirements.

​
CLI Best Practices

Security

  • Always run CLI commands as a privileged user
  • Save generated passwords securely
  • Delete session logs that contain passwords

Recovery

  • Keep CLI access available for emergencies
  • Document your CLI procedures
  • Test recovery commands in development first

​
Setting Home Boards

Users and groups can have custom home boards:

​
User Home Board

  1. Go to User Settings > Preferences
  2. Select Home Board from the dropdown
  3. Choose different boards for desktop and mobile if desired
  4. Save changes

​
Group Home Board

Admins can set default home boards for groups:
  1. Navigate to Settings > Groups
  2. Edit the group
  3. Set Default Home Board and Mobile Home Board
  4. Save changes
Users without a personal home board will use their group’s default.

​
User Settings and Preferences

Users can customize their own experience:
  • Color scheme (light/dark/auto)
  • Language preference
  • Date and time format
  • Animation preferences
  • Default board on login
  • Widget refresh intervals
  • Notification preferences
  • Change password (credentials provider)
  • Update email/profile information
  • Manage active sessions
  • View login history

​
Session Management

Admins and users can manage active sessions:

​
Viewing Active Sessions

  1. Go to Settings > Security
  2. View list of active sessions showing:
    • Device information
    • IP address
    • Login time
    • Last activity

​
Revoking Sessions

Revoke compromised or old sessions:
  • Click Revoke next to a session to end it
  • Use Revoke All to log out from all devices except current
  • Sessions are automatically revoked after password changes

​
Best Practices

Permission Structure

  • Use groups instead of per-user permissions
  • Follow principle of least privilege
  • Create groups by role (Admin, User, Guest)
  • Regular review and audit permissions

Account Security

  • Enforce strong password requirements
  • Use OIDC/LDAP for centralized auth when possible
  • Regularly review active sessions
  • Enable audit logging

User Onboarding

  • Create user guides for your instance
  • Use invite links with expiration
  • Set appropriate default groups
  • Provide initial training on features

Maintenance

  • Remove inactive users periodically
  • Update group structures as needs change
  • Document your permission scheme
  • Keep the CLI accessible for recovery

​
Troubleshooting

Check:
  • Username and password are correct
  • User account exists in the database
  • Correct authentication provider is selected
  • Account is not locked or disabled
Use reset-password CLI command if password is forgotten.
Verify:
  • User is assigned to at least one group
  • Group has appropriate permissions set
  • Board permissions are configured correctly
  • User has refreshed their browser
If the web interface is unavailable:
  1. Use the recreate-admin CLI command
  2. Ensure credentials provider is enabled in AUTH_PROVIDERS
  3. Check database connectivity
Common issues:
  • Credentials provider not enabled in environment variables
  • Database connection issues
  • Insufficient file system permissions
  • User running command doesn’t have access to Homarr files
Check logs for detailed error messages.

​
Next Steps

Authentication Setup

Configure OIDC, LDAP, and other authentication providers

Board Permissions

Learn about board-level access control

CLI Reference

Complete CLI command reference and examples

Security Best Practices

Learn about securing your Homarr instance

Build docs developers (and LLMs) love

Get started for freeTalk to us