Generate secure login links for Home Assistant to share with your guests.
Guest Mode started as a fork of Virtual Keys by @kcsoft, but is now maintained as an independent Home Assistant integration with its own UI, configuration flow, release cycle, and roadmap.
To install Guest Mode using HACS:
- Click the button above, or add this repository manually as a custom repository in HACS:
- Go to HACS → Integrations → Add Custom Repository.
- Enter the URL of this repository and select Integration as the category.
- Search for "Guest Mode" in HACS and install it.
- Restart Home Assistant.
- Go to Settings → Devices & Services → Add Integration.
- Search for "Guest Mode" and select it.
| Option Name | Description | required | default Value |
|---|---|---|---|
| Tab Icon | Icon for the Guest Mode tab, chosen from 23 MDI icons | No | mdi:shield-key |
| Tab Name | Name of the Guest Mode tab. | No | Guest |
| Path for Admin UI | Custom URL path for accessing the admin interface | No | /guest-mode |
| Login Path | Custom URL path for guest to access the login page | No | /guest-mode/login |
| Copy link directly (skips sharing) | If checked, clicking the share button will copy the link directly to the clipboard instead of opening the native share dialog. | No | Unchecked |
Default User Name (default_user) |
Preselects the user when creating a token. This matches the Home Assistant user's Name field. | No | Empty |
Default Dashboard/View Path (default_dashboard) |
Preselects dashboard or dashboard view when creating a token. Use dashboard or dashboard/view (examples: lovelace-guest, lovelace-guest/entry) and do not include a leading slash. |
No | Empty |
Guest Mode lets you create and manage temporary Home Assistant access links from a dedicated Home Assistant UI, without manually editing YAML or configuration files.
The integration provides:
- A redesigned admin interface to create, view, share, and manage guest access links.
- Temporary links with optional start date, expiration date, duration, and usage limit.
- Optional caller-provided URL tokens for workflows that must prepare links in advance.
- Optional entity-controlled access, allowing guest access only while a
schedule.*orinput_boolean.*entity ison. - Native Home Assistant login using a selected guest user.
- Optional dashboard or dashboard view redirection after login.
- QR code generation for the latest guest link, exposed through the
image.guest_qr_codeentity. - Share options, including native sharing or direct copy to clipboard depending on your configuration.
- Token status tracking, so you can see whether a guest link has already been used.
- Home Assistant services, allowing guest tokens to be created from automations.
For security, the Home Assistant long-lived access token is created only when the guest opens a valid link during the allowed time window, while the optional access control entity is on, and before the usage limit is reached. When that entity turns off, becomes unavailable, or is removed, Guest Mode revokes the Home Assistant refresh token it created for that guest token. It does not disable or remove the Home Assistant user.
I want to share an access with my friends that is valid for a limited time and that they can use to access specific entities in Home Assistant like the fron gate. The access is actually a link to my Home Assistant that can be opened in a browser.
To make this work, I need to make some optional and additional steps (before or after installing Ha Guest Mode):
-
Create a new user in Home Assistant e.g. "guest" (recommended)
-
Set permission, create group e.g. "guests" and add this user this group, and also the devices you want to give access to, e.g. "cover.front_gate". See User Permissions
-
Customize the interface by creating a new View (tab) in the default Lovelace UI and add the entities you want to give access to, e.g. "cover.front_gate", set the visibility to only show to user "guest". (optional)
-
Use Kiosk Mode or Browser Mod to hide unnecessary UI elements for guests, like sidebar. (optional)
You can now generate a secure link to share with your guests.
This integration provides services that can be used in automations.
Creates a new guest mode token.
| Parameter | Description | Required |
|---|---|---|
username |
The name of the user to create the token for. | Yes |
token_name |
The name of the token. | No |
custom_token |
A caller-provided URL token using 1–128 letters, numbers, underscores, or hyphens. A random UUID is generated when omitted. | No |
expiration_duration |
The duration until the token expires (e.g., '02:00:00'). | No |
expiration_date |
The date when the token expires. | No |
start_date |
The date when the token becomes valid. | No |
dashboard |
The URL path of the desired dashboard (e.g., 'lovelace-guest'). Do not include the leading slash. | No |
access_entity_id |
Optional schedule.* or input_boolean.* entity. Guests can only access while this entity is on; credentials created by Guest Mode are revoked when it stops being on. |
No |
Note: If neither expiration_duration nor expiration_date is provided, the token will never expire.
- service: ha_guest_mode.create_token
data:
username: "guest"
token_name: "My Guest Token"
custom_token: "booking-12345-20261020"
expiration_duration: "01:00:00" # 1 hourWarning
A custom token is the secret contained in the guest access URL. Predictable values are easier to guess, and a static prefix does not make a short code significantly safer. Use a value that is unique to each stay. Reusing a deleted value makes every old copy of that URL valid again while the new token is active. Duplicate values belonging to existing tokens are rejected.
For a reusable link controlled by a helper, omit the expiration fields and set an input boolean:
- service: ha_guest_mode.create_token
data:
username: "guest"
token_name: "Recurring Guest"
access_entity_id: input_boolean.guest_accessThe previous schedule_entity_id service field remains accepted for compatibility with existing automations.
This integration creates the following entity:
| Entity ID | Name | Description |
|---|---|---|
image.guest_qr_code |
Guest QR Code | An image entity that displays a QR code for the most recently created guest token. The QR code contains the direct login URL for the guest. The state of the entity will be Ready if a token is available and a QR code has been generated, and No token otherwise. |
-
Removing seconds in UI or Using ha-date-range-picker 🚀
-
Fix timezone in display of the token 🛠️
-
Adding a function to sanitize url for loginPath and path_to_admin_ui 🛠️
-
Improving error handling and code maintainability. 🛠️
If you want this component to support another language, feel free to submit a PR or create an issue. If you open an issue, I’ll gladly handle the translation for you! 😄
See CONTRIBUTORS.md for the full list of contributors.