How to Use Guacamole: The Beginner's Guide

CodexFuse Team · 2026-10-31T14:43:10.726Z · 15 min read min read

Set up Apache Guacamole on your own server: Docker deploy, database auth, first RDP and VNC connections, HTTPS, and TOTP two-factor — the full beginner arc.

If you want to learn how to use Guacamole, you are about to give everyone on your team browser-based access to your servers without installing a single remote-desktop client. Apache Guacamole is a free, open-source, clientless remote desktop gateway: you open a web page, sign in, and click through to Windows machines over RDP, Linux boxes over SSH, or desktops over VNC. This Guacamole tutorial takes you from an empty VPS to a hardened, HTTPS-served gateway in one arc: launching the three Docker containers, initializing the database, killing the default guacadmin password on first login, wiring your first RDP and VNC connections, adding HTTPS, and switching on TOTP two-factor. Since this is a container deployment, pair this guide with our Docker beginner guide if Docker Compose is new to you.

What Is Apache Guacamole?

Apache Guacamole is a clientless remote desktop gateway maintained by the Apache Software Foundation and licensed under the Apache License 2.0. You install it once on a server, and from then on anyone with a browser and an account can reach the machines it is configured for — over RDP, VNC, SSH, telnet, or Kubernetes — with no plugins, VPN client, or remote-desktop app on their device. The "clientless" part is the whole point: the heavy protocol work happens server-side in the guacd daemon, while the Guacamole web application translates everything into plain HTML5 in your browser tab. The current release is Guacamole 1.6.0 (2025-06-22), which brought improved rendering performance, better Docker support, batch connection import, and Duo v4 support.

Guacamole has exactly two moving parts you must understand. guacd is the proxy daemon that speaks RDP, VNC, SSH, and the rest to your target machines; it listens on port 4822 and deliberately performs no authentication of its own, which is why it must never be exposed to untrusted networks. The web application is the Tomcat 9.x-based front end (default: port 8080, path /guacamole/) that handles logins, permissions, and the in-browser desktop. A third component, a database (PostgreSQL or MySQL), stores users, connections, and permissions — the production-grade lane the manual insists on, because the built-in file-based option is explicitly "not intended for production use."

Why Use a Clientless Gateway Instead of a VPN or a Remote-Desktop App?

Guacamole solves the "how do I let someone onto a machine quickly and safely" problem without shipping software to every user. A VPN gives a device full network access and needs a client; a remote-desktop app needs installing on every machine that connects. Guacamole needs only a browser — the person helping you, the contractor on a Chromebook, or you on a borrowed laptop just opens a URL, and the gateway never hands out the underlying machine's credentials to the viewer if you configure it that way. That is why teams put Guacamole in front of lab machines, customer VMs, and home servers: one hardened login page instead of open RDP ports or shared VPN profiles.

The consent rule matters and the manual's spirit is clear: only connect Guacamole to machines you own, rent, or have explicit permission to access. A gateway that lets browsers reach desktops is exactly the kind of tool that must never be pointed at someone else's infrastructure.

What You Need Before You Start

You need one Linux server with Docker and Docker Compose installed and a domain name (or subdomain like remote.yourdomain.com) pointed at it. A 1 vCPU / 2 GB RAM VPS is enough for a small team; Guacamole itself is light, and most of the load lands on guacd during active sessions. If you have not bought server space yet, see our what is VPS hosting guide for how to choose one.

You will also want the machine you are connecting to reachable from the Guacamole server on the right protocol port (3389 for Windows RDP, 22 for SSH, 5900 for VNC by default). On Windows, enable Remote Desktop in Settings; on Linux, any SSH server works for terminal access. Note one hard Guacamole fact: audio over RDP and network-drive redirection are not fully supported, so plan accordingly if those matter to you.

The 7-Step Beginner Arc

This is the whole Apache Guacamole setup in order. Each step builds on the last, and nothing here assumes you have touched Guacamole before.

Launch the three containers. Write the compose file (guacd, Guacamole web app, Postgres) and start it.
Initialize the database. Generate the schema SQL with Guacamole's own initdb.sh and let Postgres run it on first boot.
Log in as guacadmin — then change the password immediately. The default credentials are guacadmin/guacadmin, and everyone on the internet knows that.
Create your first connection. An RDP connection to a Windows box first, then a VNC or SSH one.
Create your own user account. Stop using the admin account for daily access.
Put HTTPS in front. A reverse proxy with a real certificate, plus the Remote IP Valve so logs show real client IPs.
Turn on TOTP two-factor. The gateway now needs a password and a phone code.

Step 1: Launch the Three Containers (Guacamole Docker)

The official Apache Guacamole Manual's Docker chapter says a typical deployment is three separate containers connected over one Docker network: guacamole/guacd (the proxy daemon, built from the released guacamole-server source with VNC, RDP, SSH, telnet, and Kubernetes support), guacamole/guacamole (the Tomcat 9.x web app with WebSocket support), and a database (PostgreSQL here). Keeping the database in its own container is deliberate: the web app and guacd can be destroyed and recreated freely, but the database container is the one that must persist your users and connections through upgrades.

Create a project directory and a docker-compose.yml:

services:
  guacd:
    image: guacamole/guacd
    container_name: guacamole-guacd
    networks:
      - guacnet
    restart: unless-stopped

  guacamole:
    image: guacamole/guacamole
    container_name: guacamole-web
    depends_on:
      - guacd
      - postgres
    networks:
      - guacnet
    ports:
      - "8080:8080"
    environment:
      GUACD_HOSTNAME: guacd
      POSTGRES_HOSTNAME: postgres
      POSTGRES_DATABASE: guacamole_db
      POSTGRES_USER: guacamole_user
      POSTGRES_PASSWORD: "${GUACAMOLE_DB_PASSWORD}"
    volumes:
      - initdb:/opt/guacamole/extensions/guacamole-auth-jdbc/postgresql/schema
    restart: unless-stopped

  postgres:
    image: postgres:16
    container_name: guacamole-postgres
    networks:
      - guacnet
    environment:
      POSTGRES_DB: guacamole_db
      POSTGRES_USER: guacamole_user
      POSTGRES_PASSWORD: "${GUACAMOLE_DB_PASSWORD}"
    volumes:
      - pgdata:/var/lib/postgresql/data
      - initdb:/docker-entrypoint-initdb.d
    restart: unless-stopped

volumes:
  initdb:
  pgdata:

networks:
  guacnet:

Two details worth understanding. GUACD_HOSTNAME: guacd is how the web app finds the daemon: because both containers share the guacnet network, the container name resolves as a hostname, and port 4822 is the default so GUACD_PORT can be omitted. Second, the initdb named volume trick comes straight from the manual: mounting Guacamole's bundled schema scripts into the Postgres container's /docker-entrypoint-initdb.d makes Postgres execute them automatically on first boot — which is exactly Step 2. Set a real password before starting: export GUACAMOLE_DB_PASSWORD=$(openssl rand -base64 24), then docker compose up -d. The web app will be reachable at http://YOUR_SERVER_IP:8080/guacamole/.

Step 2: Initialize the Database

The manual is blunt: if you use PostgreSQL or MySQL for authentication, you must initialize the database manually — Guacamole will not create its own tables, and the web container refuses to start without at least one authentication mechanism configured. Guacamole ships a helper for this inside the web image. Run it once to extract the full PostgreSQL schema script:

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

That SQL file contains the complete schema for Guacamole 1.6.0. The compose file above already handles initialization for you: the initdb volume pulls the schema scripts out of the Guacamole container, and Postgres executes every script in /docker-entrypoint-initdb.d when the data volume is first created. If you are using an existing Postgres instead, create the database and user yourself — the manual's exact grants are:

CREATE DATABASE guacamole_db;
CREATE USER guacamole_user WITH PASSWORD 'a-strong-password';
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO guacamole_user;
GRANT SELECT, USAGE ON ALL SEQUENCES IN SCHEMA public TO guacamole_user;

Guacamole only needs read/write on its own tables and sequences — nothing more. After docker compose up -d, check the web container's logs: a database-auth failure shows up there immediately, which beats guessing at the login page.

Step 3: Log In and Change guacadmin Immediately (The guacadmin Rule)

Open http://YOUR_SERVER_IP:8080/guacamole/ in your browser. The login screen asks for a username and password, and the factory defaults are guacadmin / guacadmin — published in every Guacamole guide ever written, including this one. Change them before you do anything else: click the guacadmin menu at the top right, choose Settings, open the Users tab, click the guacadmin user, and set a new long password. The official manual's administration chapter manages users entirely through this web interface, and the database-backed auth you just set up is what makes it possible — the legacy file-based user-mapping.xml method offers no admin UI at all, which is one more reason the manual says the goal should always be the database.

Treat this like the router-admin-password rule: anyone who can reach your Guacamole port can try guacadmin/guacadmin, and scanners try it within hours on a public IP. Until Step 6 (HTTPS) and Step 7 (TOTP) are done, keep port 8080 firewalled to your own IP if you can.

Step 4: Create Your First Connection (Guacamole RDP and Guacamole VNC)

With the database auth active, you have the full web admin interface. Go to Settings → Connections → New Connection. Give the connection a name (e.g. "Office PC"), pick the protocol, and fill in the target's network address, port, username, and password. For an RDP connection to a Windows machine, protocol RDP, hostname = the machine's IP, port 3389; enable "Ignore server certificate" only for a first test against a self-signed cert, then install a proper certificate later. For a VNC desktop, protocol VNC, port 5900, and the VNC server's password. For SSH, protocol SSH, port 22, and your SSH credentials — Guacamole even renders the terminal with proper fonts out of the box because the guacd Docker image ships them preinstalled.

Save, return to the home screen, and click the connection tile. The remote desktop opens in a new browser tab — that is the clientless promise in action: the person at the keyboard needs nothing but this URL. A few daily-use facts from the official "Using Guacamole" chapter make life easier: the hidden sidebar menu (clipboard, input options, settings) appears with Ctrl+Alt+Shift, or by swiping right from the left edge on a touchscreen; the on-screen keyboard (for sending Ctrl+Alt+Del and other keys the browser would otherwise steal) toggles with the same shortcut; and file transfer works by dragging files into the browser window for upload, while downloads on RDP go through the special Download folder of the emulated drive, and SSH transfers use SFTP. Log out from the original tab's connection list when you are done — closing just the session tab leaves your Guacamole session signed in.

Step 5: Create Your Own User Account

Stop logging in as guacadmin for daily use. In Settings → Users → New User, create your personal account with a strong password, then grant it only the connections it needs via the Connections permissions tab on the user. This is where the database auth lane earns its keep: per-user, per-connection permissions, connection groups for organizing dozens of machines, and a full audit of who can reach what — none of which exists in the file-based setup. If you ever need to revoke someone's access, you uncheck one box instead of editing a shared config file and restarting services.

Step 6: Put HTTPS in Front (Guacamole HTTPS)

Never log into Guacamole over plain HTTP from anywhere but your own LAN — the login page handles the keys to your machines. Put a reverse proxy in front of the web container and terminate TLS there; the official manual covers this under "Running Guacamole behind a proxy" and "Securing a Guacamole install." A Caddy front end is the shortest path: point your domain at the server, proxy to the web container on 8080, and Caddy issues and renews the Let's Encrypt certificate automatically. Our Caddy beginner guide walks through exactly that reverse-proxy pattern.

One Guacamole-specific detail: when running behind a proxy, Tomcat must be told to trust the proxy's forwarding headers, or Guacamole will log the proxy's IP for every user instead of the real client address. The Guacamole Docker image handles this through its Remote IP Valve settings — set REMOTE_IP_VALVE_ENABLED=true on the web container and restrict PROXY_ALLOWED_IPS_REGEX to your proxy's IP range. The manual documents both variables alongside the proxy chapter, and getting this right is what keeps your brute-force monitoring (the manual also covers blocking brute-force attacks) aimed at real attacker IPs instead of your own proxy.

Step 7: Turn On TOTP Two-Factor

A gateway page deserves more than a password. Guacamole ships first-party multi-factor extensions — TOTP (the authenticator-app codes), Duo (the 1.6.0 release added Duo v4 support), plus LDAP, RADIUS, CAS, OpenID Connect, and SAML lanes. For TOTP: download the guacamole-auth-totp extension matching your Guacamole version into the container's extensions directory (the Docker image reads custom extensions from GUACAMOLE_HOME, which you can mount as a volume), restart the web container, then open your user profile in the web UI and enroll: scan the QR code with any authenticator app and enter the first code to confirm. From then on, logging into Guacamole requires the password plus the rotating code — so even a leaked password no longer opens your machines.

Order matters here: HTTPS first, then TOTP. Enrolling a second factor over plain HTTP would hand the enrollment secret to anyone watching the network.

Guacamole vs RustDesk: When to Pick Which

The most common "which remote tool" question in this lane pits Guacamole against RustDesk — the classic Guacamole clientless RDP decision — and they are not the same kind of product. RustDesk is a client application: you install its app on both the machine you sit at and the machine you reach. Guacamole is a browser gateway: you install it once on a server, and everyone else needs only a browser. If you want the full breakdown of the client-app lane, see our RustDesk beginner guide.

	Apache Guacamole	RustDesk
User-side requirement	Any modern browser — nothing to install	RustDesk client app installed on both ends
Where it runs	Your server (self-hosted gateway)	Client app + your own or public relay server
Protocols	RDP, VNC, SSH, telnet, Kubernetes via guacd	Its own remote-desktop protocol
Best for	Teams, contractors, shared lab machines, browser-only devices	Personal use, quick help-a-friend sessions
Admin model	Central users, per-connection permissions, groups	Per-device address book and keys
Setup effort	One server setup (this guide), then zero per user	Per-device install, then zero servers
File transfer	RDP virtual drive / SSH SFTP via browser drag-and-drop	Built into the client app

The rule of thumb: if the people connecting are many, changing, or on locked-down devices, Guacamole's one-time server setup wins. If it is just you and one helper reaching two machines, a client app is simpler.

7 Beginner Mistakes to Avoid

Mistake	What happens	Do this instead
Leaving guacadmin/guacadmin on a public IP	Automated scanners find and try it within hours	Change it in Settings → Users on first login (Step 3)
Using user-mapping.xml for a real deployment	No admin UI, no per-user permissions, restart-to-edit	Use the database auth lane (Step 2) — the manual's explicit recommendation
Exposing guacd's port 4822 to the internet	guacd performs no authentication; it becomes an open proxy	Keep guacd on the isolated Docker network only, never published
Logging in over plain HTTP	Credentials and session cookies travel unencrypted	Terminate HTTPS at a reverse proxy before going live (Step 6)
Skipping the Remote IP Valve	All users appear to come from the proxy's IP in logs	Set REMOTE_IP_VALVE_ENABLED=true and restrict PROXY_ALLOWED_IPS_REGEX
Using guacadmin as the daily account	One shared superuser, no accountability, no least-privilege	Create personal users with per-connection permissions (Step 5)
Enabling TOTP before HTTPS	The enrollment secret crosses the network unencrypted	HTTPS first (Step 6), then enroll TOTP (Step 7)

Sources

Apache Guacamole Manual v1.6.0, "Installing Guacamole" — install methods; user-mapping.xml not for production — https://guacamole.apache.org/doc/gug/installing-guacamole.html (fetched 2026-10-31)
Apache Guacamole Manual v1.6.0, "Installing Guacamole with Docker" — official images, three-container layout, guacd port 4822, env vars, manual DB init — https://guacamole.apache.org/doc/gug/guacamole-docker.html (fetched 2026-10-31)
Apache Guacamole Manual v1.6.0, "PostgreSQL authentication" — initdb.sh extraction command, schema location, CREATE USER/GRANT statements — https://guacamole.apache.org/doc/gug/postgresql-auth.html (fetched 2026-10-31)
Apache Guacamole Manual v1.6.0, "Using Guacamole" — login, connection list, Ctrl+Alt+Shift menu, on-screen keyboard, RDP/SFTP file transfer — https://guacamole.apache.org/doc/gug/using-guacamole.html (fetched 2026-10-31)
Apache Guacamole releases page — 1.6.0 released 2025-06-22 (rendering performance, Docker support, batch connection import, Duo v4) — https://guacamole.apache.org/releases/ (fetched 2026-10-31)
Shapehost, "Get Up and Running with Apache Guacamole for Remote Desktop" — default guacadmin/guacadmin credentials, full gateway arc — https://shape.host/resources/how-to-set-up-a-remote-desktop-gateway-with-apache-guacamole-on-almalinux-9 (crawled 2026-10-27)
C-sharpcorner, "Apache Guacamole: Remote Access Without the Headache" — clientless architecture explainer — https://www.c-sharpcorner.com/article/apache-guacamole-remote-access-without-the-headache (crawled 2026-10-30)
guacamole.apache.org home — Apache License 2.0 licensing — https://guacamole.apache.org/ (fetched 2026-10-31)

Frequently Asked Questions

Is Apache Guacamole really free?

Yes. Guacamole is an Apache Software Foundation project licensed under the Apache License 2.0, so there is no per-user or per-connection fee. Your only cost is the server you run it on and your time to maintain it.

Do users need to install anything to use Guacamole?

No — that is the "clientless" in clientless remote desktop gateway. Users need only a modern browser and their Guacamole account. Everything protocol-specific runs in the guacd daemon on your server.

What is the default Guacamole login?

The fresh-install default is username guacadmin with password guacadmin. It is the first thing you change: Settings → Users → guacadmin, and set a strong password before exposing the server to the internet.

Can Guacamole replace my VPN?

For remote-desktop access, often yes: instead of giving devices full network access through a VPN, you give users browser access to specific machines with per-connection permissions. It does not replace a VPN for other traffic (file shares, internal web apps), but many teams find the gateway covers their actual need.

Which is better for a small team, Guacamole or RustDesk?

Guacamole wins when the connecting users are many, changing, or on devices where you cannot install software — one server setup, then everyone uses a browser. RustDesk is simpler when it is just a couple of people and machines and installing a client app on each is no burden.