Apache Guacamole

Apache Guacamole is a free, open-source clientless remote desktop gateway: a server on your network turns RDP, VNC, SSH, Telnet and Kubernetes sessions into an HTML5 page, so users reach internal machines from a web browser with nothing installed. It is built for sysadmins who want one secured entry point for staff, contractors or students instead of handing out VPN access. There is no Windows program behind an Apache Guacamole download: the project ships server source code, a Java web application and official Docker images, licensed under Apache License 2.0.

The architecture has two parts. guacd is a native proxy daemon that speaks the remote desktop protocols. The web application runs in a Java servlet container such as Tomcat, handles logins and connection lists and streams the display to the browser. You install both on Linux, or run them as two containers.

Apache Guacamole at a glance

What it does

• Browser access to RDP, VNC, SSH, Telnet and Kubernetes connections, with no plugin or client on the user’s device.
• Central connection management: users and groups see only the connections assigned to them.
• Authentication from a database (MySQL/MariaDB, PostgreSQL or SQL Server), LDAP or Active Directory, single sign-on (SAML, OpenID Connect, CAS) and second factors such as TOTP and Duo.
• Session recording to files that can be played back or converted to video with the guacenc utility.
• Connection sharing, so a second person can watch or join a live session through a link.
• File transfer through RDP drive redirection and SFTP, plus clipboard and audio support.
• Version 1.6.0 added faster rendering, better Docker support, batch connection import, configurable username case sensitivity and Duo v4 support.

How IT teams use it

Run Guacamole with Docker Compose and PostgreSQL

1. Generate the database schema from the official image:

   docker run --rm guacamole/guacamole:1.6.0 /opt/guacamole/bin/initdb.sh --postgresql > initdb.sql

2. Create docker-compose.yml next to it:

   services:
     guacd:
       image: guacamole/guacd:1.6.0
       restart: unless-stopped
     postgres:
       image: postgres:16
       environment:
         POSTGRES_DB: guacamole_db
         POSTGRES_USER: guacamole_user
         POSTGRES_PASSWORD: change-me
       volumes:
         - ./initdb.sql:/docker-entrypoint-initdb.d/initdb.sql:ro
         - pgdata:/var/lib/postgresql/data
     guacamole:
       image: guacamole/guacamole:1.6.0
       depends_on: [guacd, postgres]
       environment:
         GUACD_HOSTNAME: guacd
         POSTGRESQL_HOSTNAME: postgres
         POSTGRESQL_DATABASE: guacamole_db
         POSTGRESQL_USERNAME: guacamole_user
         POSTGRESQL_PASSWORD: change-me
       ports:
         - "8080:8080"
   volumes:
     pgdata:

3. Start it with docker compose up -d and open http://server:8080/guacamole/.
4. Sign in as guacadmin / guacadmin, the default account created by the schema, and change that password or replace the account immediately.

Publish it safely behind Nginx

1. Terminate HTTPS on Nginx and keep port 8080 closed to the outside.
2. Guacamole needs WebSocket upgrades and unbuffered responses:

   location /guacamole/ {
       proxy_pass http://127.0.0.1:8080/guacamole/;
       proxy_buffering off;
       proxy_http_version 1.1;
       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection $http_connection;
       access_log off;
   }

3. Enable TOTP or Duo before exposing the login page to the internet.

Add a Windows server over RDP

1. As an administrator, open Settings → Connections → New Connection and choose the RDP protocol.
2. Enter the host name, port 3389 and, if needed, the domain; set Security mode to match the server (NLA in most domains).
3. If the server uses a self-signed certificate, tick Ignore server certificate or, better, deploy a trusted certificate.
4. Assign the connection to a user group, then test it from a normal user account.

Install and first run

Docker. The quickest route: the official guacamole/guacd and guacamole/guacamole images. Database tables are not created automatically; load the SQL from initdb.sh as shown above.

Native Linux. Build guacamole-server from source. Required libraries are Cairo, libjpeg-turbo, libpng and libuuid; protocol support depends on optional libraries such as FreeRDP 2.0.0 or later for RDP, libvncserver for VNC, libssh2 and Pango for SSH, libtelnet for Telnet and libwebsockets for Kubernetes. With systemd use ./configure --with-systemd-dir=/usr/local/lib/systemd/system, then make and make install. Deploy the web application archive in Tomcat.

Ports. guacd listens on TCP 4822; keep it on localhost or a private network. The gateway itself must reach targets on their protocol ports (3389, 5900, 22).

Windows. There is no native Windows server build. On a Windows host, run the containers in Docker or use a Linux VM; Windows machines are reached as RDP targets.

Limitations

• It is a gateway, not an agent: every target must already run an RDP, VNC or SSH server reachable from the Guacamole host.
• Setup takes real work (database, reverse proxy, TLS, MFA) compared with install-and-go remote support tools.
• Releases are infrequent; 1.6.0 from June 2025 is still current.
• Full-motion video and multimedia feel worse in the browser than in a native RDP client.
• No built-in ticketing or unattended agent deployment; it is not a help-desk product.

Apache Guacamole vs alternatives

Thinfinity Remote Desktop is a commercial HTML5 gateway with vendor support. MeshCentral is free and self-hosted too, but uses its own agent and does not need RDP or VNC on the targets. RustDesk Server serves a different need: a self-hosted relay for the RustDesk client rather than a browser gateway.

FAQ

What is the Apache Guacamole default login?

With database authentication the schema creates the user guacadmin with password guacadmin. Change it immediately after the first sign-in.

Can Apache Guacamole run on Windows?

Not natively. Run the official Docker images or a Linux VM on the Windows host; Windows PCs and servers are then reached over RDP.

Is Apache Guacamole free?

Yes. It is open source under the Apache License 2.0 with no paid edition from the project itself.

How do I transfer files with Guacamole?

Enable drive redirection on RDP connections or SFTP on SSH and VNC connections; files are then uploaded by drag and drop or through the Guacamole menu.

Apache Guacamole vs RustDesk?

Guacamole gives browser access to existing RDP, VNC and SSH servers with central accounts. RustDesk is a remote desktop client with its own agent and optional self-hosted server, better suited to supporting individual PCs.

What are good Apache Guacamole alternatives?

Thinfinity Remote Desktop for a supported commercial gateway, or MeshCentral if you prefer an agent-based, self-hosted web console.

Does Guacamole support two-factor authentication?

Yes, through the TOTP and Duo extensions, or through your identity provider when you use SAML or OpenID Connect.

Last checked against official sources: 1 October 2026 (developer website: guacamole.apache.org). Versions and licence terms change — confirm on the developer's site before deploying in production.