NixOS - Guacamole Clientless Remote Desktop Gateway Setup

Once Guacamole is installed on a machine, in my case running NixOS, all you need to access your desktop environment and CLI is a web browser. It supports standard protocols like VNC, RDP, and SSH.


Open configuration.nix:

sudo nano /etc/nixos/configuration.nix

First add the following options as described in the documentation:

services.xserver.enable = true;
services.xserver.displayManager.sddm.enable = true;
services.xserver.desktopManager.plasma5.enable = true;

services.xrdp.enable = true;
services.xrdp.defaultWindowManager = "startplasma-x11";
services.xrdp.openFirewall = true;

Then add the Guacamole server and client services:

# Guacamole
services.guacamole-server = {
  enable = true;
  host = "";
  userMappingXml = ./guacamole/user-mapping.xml;
  package = pkgs.unstable.guacamole-server; # Optional, use only when you want to use the unstable channel

services.guacamole-client = {
  enable = true;
  enableWebserver = true;
  settings = {
    guacd-port = 4822;
    guacd-hostname = "";
  package = pkgs.unstable.guacamole-client; # Optional, use only when you want to use the unstable channel

I used the services and packages from the unstable channel because the stable channel did not work well (which I haven’t actually experienced before).

Save the changes to configuration.nix.

Now you can switch to the new configuration:

sudo nix-collect-garbage # optional: clean up
sudo nixos-rebuild switch

You can view my complete configuration.nix here.

Now we need to create the user-mapping.xml where you can enter the user information with which you can log in to Guacamole. And also the connections you want to use to connect to NixOS.

First generate the sha256 hash so you don’t have to save your password in plain text:

echo -n PASSWORD | openssl dgst -sha256
# Or use:
# echo -n PASSWORD > file.txt
# sha256sum file.txt

Adjust the following:

Replace with your password, which will be used to log in to Guacamole

Copy the result (the hash after =).

Now create the guacamole folder and the user-mapping.xml file:

cd /etc/nixos
sudo mkdir guacamole
sudo nano guacamole/user-mapping.xml

Add the following text:

<?xml version="1.0" encoding="UTF-8"?>
     <!-- User using SHA-256 to hash the password -->
        password="sha256 hash"

        <connection name="NixOS Server SSH">
            <param name="hostname"></param>
            <param name="port">22</param>

      <connection name="NixOS Server RDP">
          <param name="hostname"></param>
          <param name="port">3389</param>
          <param name="ignore-cert">true</param>

Adjust the following:

Replace with your username, which will be used to log in to Guacamole

sha256 hash
Replace with the sha256 hash generated earlier

Save the changes to user-mapping.xml.

Using Guacamole

Guacamole can be reached via the URL:


Then log in with your username and password. The result:

If you want to access Guacamole via a local domain name (for example you can add the Caddy service to configuration.nix:

services.caddy = {
    enable = true;
    virtualHosts."" = {
    extraConfig = ''
        tls internal
        handle {
	        reverse_proxy {
	            flush_interval -1

And don’t forget to create a local DNS record where points to the IP address of the NixOS machine, see this note for more information.

Read other notes


    No comments found for this note.

    Join the discussion for this note on this ticket. Comments appear on this page instantly.


    Notes mentioning this note

    Notes Graph