Apache Guacamole Server: guacd, libguac and the Protocol Libraries

What guacamole-server actually is, and who needs it

This repository is not the Guacamole you log into. It is the C foundation underneath it: guacd, libguac, and a set of protocol support libraries. The README states the reason plainly. JavaScript cannot handle binary protocols like VNC and remote desktop efficiently, so a text-based protocol was developed containing a common superset of the operations needed for remote desktop access, and guacd is the proxy that translates between arbitrary protocols and the Guacamole protocol.

So the audience is narrow and specific. You are building or operating the Guacamole web application and framework, and you need the daemon it connects to. Or you are writing a client against libguac. If you want a remote desktop gateway with a login page, this repository gives you the engine and nothing else. There is no web interface here, no authentication layer, no connection inventory.

The translation model is what makes the project interesting. Rather than teaching a browser to speak RDP, guacd speaks RDP on one side and a line-oriented text protocol on the other. Any client that can parse that text can render any supported protocol, which is why the same JavaScript front end works for VNC, RDP, SSH and Telnet without protocol-specific browser code.

How guacd translates binary protocols into the Guacamole protocol

The data flow is a relay with a codec in the middle. A client connects to guacd, guacd opens a connection to the target machine using the relevant protocol library, and from then on it decodes what the remote server sends and re-encodes it as Guacamole protocol instructions.

That re-encoding is not free. The required dependencies list Cairo, libjpeg-turbo or libjpeg, and libpng, which tells you the daemon is doing image work in the middle of the stream: decoding and re-encoding framebuffer updates before they go out. Optional dependencies extend that. libwebp enables WebP image compression, and PulseAudio enables audio within VNC. FFmpeg is only needed for guacenc, the video encoding utility, not for guacd itself.

The protocol support is genuinely optional at build time, and the README is blunt about the consequence: while the various supported protocols are technically optional, you will no doubt wish to install the dependencies of at least ONE supported protocol, as Guacamole would be useless otherwise. That is an accurate description of the architecture. guacd without any protocol library builds and runs, and can do nothing useful.

Each protocol pulls its own dependency set. RDP needs FreeRDP. SSH needs libssh2, OpenSSL and Pango. Telnet needs libtelnet and Pango. VNC needs libVNCserver. SFTP file transfer for VNC or RDP needs libssh2 and OpenSSL. The overlap is real, so an SSH plus SFTP deployment costs you the same libraries.

Installing guacamole-server from source with Automake

The README describes the standard GNU Automake flow. Install the required dependencies first (Cairo, libjpeg-turbo or libjpeg, libpng, OSSP UUID) plus whichever protocol dependencies you need, then run configure. The README notes that if all dependencies are installed, this should succeed without errors.

$ ./configure
$ make
# make install

If you want the init script installed too, configure takes a directory for it, typically /etc/init.d, and make install then places the script there for your distribution's service management to pick up.

$ ./configure --with-init-dir=/etc/init.d

The README states that guacd installs to /usr/local/sbin by default, and that the --prefix option to configure changes the install location. That matters if you are packaging rather than installing by hand.

Running it is the next step. With the init script in place, the README gives this command as root:

# /etc/init.d/guacd start

Root is needed to write the pidfile at /var/run/guacd.pid. Without the init script, guacd runs directly as any user with `guacd`. The daemon listens on port 4822 by default, which the -l option changes. The -b option changes the host or address it binds. The -L option sets the maximum log level to syslog and, when running in the foreground, the console, with legal values debug, info, warning and error, defaulting to info. The -f flag keeps it in the foreground instead of forking into the background. The README points to `man guacd` for the rest.

The repository also carries a Dockerfile, which is the more practical route for most people. It is built on Alpine, and the comment in the file is worth reading before you change it: the base image is pinned to 3.18 because the required openssl1.1-compat-dev package was removed in more recent versions. The Dockerfile takes build arguments including ALPINE_BASE_IMAGE, BUILD_ARCHITECTURE, BUILD_JOBS, BUILD_DIR, FREERDP_VERSION (defaulting to version 2) and PREFIX_DIR, which defaults to /opt/guacamole and is hard-coded in the entrypoint.

Where guacamole-server is the wrong tool

The clearest limitation is structural rather than technical: this is a component, not a product. Nothing in this repository authenticates a user, stores a connection, or presents an interface. If your requirement is "let staff reach internal machines from a browser", guacamole-server alone does not meet it. You need the web application, and you need to accept the two-process architecture that comes with it.

The build is also unforgiving in a specific way. Protocol support is gated on optional dependencies that configure does not treat as errors. A missing libssh2 does not stop the build; it silently produces a guacd that cannot do SSH. The README's warning about needing at least one protocol dependency is the only signal you get, and it is easy to skim past. Container images built from the Dockerfile inherit the same property: what you get depends on which optional packages made it into the image.

The Alpine 3.18 pin is a real constraint, not a footnote. The Dockerfile comment says the openssl1.1-compat-dev package was removed in more recent Alpine versions, so moving to a newer base image is not a matter of changing one argument. Anyone who treats the base image as freely upgradable will find out otherwise.

Finally, the README does not document rollback, downgrade or database migration, which makes sense because this repository has no database. Upgrade planning belongs to the web application, not here.

Guacamole server versus connecting to VNC directly

The obvious alternative is skipping the proxy and pointing a native VNC client, or a browser-based VNC client, straight at the machine. That works, and it is simpler: one connection, no daemon, no protocol translation, no Cairo or libpng in the path.

The difference in approach is where the translation happens. A direct VNC client speaks RFB end to end and renders it itself. Guacamole inserts guacd in the middle, which decodes RFB and emits Guacamole protocol instructions that a JavaScript client renders. You pay for a hop, a re-encoding step and a daemon to operate, and you get protocol independence in return: the same client code works whether the far end is VNC, RDP, SSH or Telnet.

That trade only makes sense if you have more than one protocol, or if you specifically need browser access without a plugin. For a single VNC target and a desktop client, the proxy is pure overhead. For a fleet mixing Windows RDP, Linux SSH and legacy VNC behind one browser-facing interface, the translation layer is the whole point. The README's framing supports that reading: the protocol was designed as a common superset of the operations needed for efficient remote desktop access, which is a statement about breadth, not about beating RFB at its own job.

Maintenance, licensing and what an upgrade costs you

The repository is not archived, and the last push was on 2026-09-14, which is recent. Beyond that, there is no release history to work from, so there is nothing to say about version cadence or long-term support windows. The README points to the downloads section of the project website for source archives and to a full manual at guacamole.apache.org/doc/gug/, and bugs go to the JIRA instance at issues.apache.org/jira/browse/GUACAMOLE rather than to GitHub issues.

Licensing is Apache-2.0, and the source files carry the standard ASF header, including the Dockerfile. There is also a NOTICE file at the repository root, which matters because Apache-2.0 section 4 requires that NOTICE contents be propagated in redistributions. If you build a container image or a package from this code and ship it, keep the NOTICE with it. That is a description of the licence terms, not legal advice; get your own counsel for anything consequential.

The upgrade cost is dominated by dependencies rather than by the daemon's own code. Moving to a newer FreeRDP, or changing the Alpine base, changes what guacd can do and how it renders. The Dockerfile exposes FREERDP_VERSION as a build argument precisely because that choice is a deployment decision. The practical upgrade procedure is to rebuild from source or from the Dockerfile with the dependency set you intend, then confirm that the protocols you rely on were actually compiled in, since a successful configure proves nothing about optional protocol support.

Editorial conclusion

Adopt guacamole-server if you need a protocol-translating proxy that a browser-facing JavaScript client can talk to, and you are willing to install Cairo, libjpeg-turbo or libjpeg, libpng and OSSP UUID before you even run configure. Do not adopt it if you want a finished remote desktop product: this repository has no web UI, no user database and no connection management, so nothing here is usable on its own without the Guacamole web application. Verify first that the protocol you actually need has its optional dependency present (FreeRDP for RDP, libssh2 and OpenSSL for SSH, libVNCserver for VNC), because configure will succeed without them and you will only discover the gap when a connection is attempted. Also check whether your distribution's openssl1.1-compat-dev situation forces you onto the Alpine 3.18 base image named in the Dockerfile.

Frequently asked questions

Official sources

1. apache/guacamole-server on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README