I maintain this and other Home Assistant add-ons in my free time: keeping up with upstream changes, HA changes, and testing on real hardware takes a lot of time (and some money). I use around 5-10 of my >110 addons so regularly I install test machines (and purchase some test services such as vpn) that I don't use myself to troubleshoot and improve the addons

If this add-on saves you time or makes your setup easier, I would be very grateful for your support!

Addon informations

Thanks to everyone having starred my repo! To star it click on the image below, then it will be on top right. Thanks!

About

Apache Guacamole is a clientless remote desktop gateway that supports standard protocols like VNC, RDP, and SSH. It provides a web-based interface for accessing remote systems without requiring any client software on the user's device. Guacamole acts as a proxy, translating between the web-based frontend and the actual remote desktop protocols.

This addon combines both the Guacamole server (guacd) and web application components with an integrated PostgreSQL database for storing connection configurations and user management. The solution provides a complete remote desktop gateway that can be used to securely access computers and servers from anywhere via a web browser.

This addon is based on the docker image from: https://github.com/abesnier/docker-guacamole

Configuration

Webui can be found at <your-ip>:8080 or through the sidebar using Ingress.

The default username is guacadmin with password guacadmin. It is strongly recommended to change this password immediately after first login.

Options

Option	Type	Default	Description
`EXTENSIONS`	str	`auth-totp`	Guacamole extensions to enable (e.g., `auth-totp`, `history-recording-storage`)
`recording_search_path`	str	`/config/recordings`	Directory added to `guacamole.properties` as the `recording-search-path` used by the history recording storage extension
`TZ`	str		Timezone (e.g., `Europe/London`)

Example Configuration

EXTENSIONS: "auth-totp,history-recording-storage"
recording_search_path: "/config/recordings"
TZ: "Europe/London"

Database Setup

The addon automatically configures a PostgreSQL database for storing Guacamole configurations, users, and connections. The database files are stored in /config/postgres and are automatically created on first startup.

Custom Scripts and Environment Variables

This addon supports custom scripts and environment variables through the addon_config mapping:

Custom scripts: See Running Custom Scripts in Addons
env_vars option: Use the add-on env_vars option to pass extra environment variables (uppercase or lowercase names). See https://github.com/alexbelgium/hassio-addons/wiki/Add-Environment-variables-to-your-Addon-2 for details.

Installation

The installation of this add-on is pretty straightforward and not different in comparison to installing any other Hass.io add-on.

Add my Hass.io add-ons repository to your Hass.io instance.
Install this add-on.
Click the Save button to store your configuration.
Start the add-on.
Check the logs of the add-on to see if everything went well.
Go to the web interface and log in with the default credentials (guacadmin/guacadmin).
Change the default password immediately for security.
Configure your remote connections through the Guacamole web interface.

Setup

After installation and first login:

Change Default Password: Go to Settings → Users → guacadmin and change the password
Create Connections: Use the web interface to add RDP, VNC, or SSH connections to your remote systems
Configure Extensions: If using TOTP authentication, configure it in the user settings
User Management: Create additional users and assign connection permissions as needed

Support

Create an issue on GitHub