Architecture

One Rust binary between the browser and guacd

rustguac replaces Guacamole's Java webapp and keeps guacd, the same C protocol daemon from guacamole-server. It proxies the Guacamole protocol over WebSockets and handles sign-in, session lifecycle, recording and VDI containers.

Browser HTML5 client No plugins, no client

WebSocket over HTTPS

rustguac Rust · axum · single binary

OIDC + roles
Sessions
Recording
VDI

Vault / OpenBaocredentials
OIDC providersign-in

TLS · Guacamole protocol

guacd from guacamole-server Bundled, loopback only

SSH serverterminal + SFTP
RDP serverWindows / xrdp
VNC serverKVM, IPMI, VMs
SPICE serverlibvirt / QEMU
Proxmox VEVM console via API
Xvnc + Chromiumweb sessions
Docker + xrdpVDI desktops

Both links are encrypted by default: HTTPS between browsers and rustguac, TLS between rustguac and guacd. SSH, RDP, VNC, web and Proxmox sessions can also be routed through a chain of SSH jump hosts.

Session types

Seven ways in, one browser tab

Everything guacd speaks, plus two session types Apache Guacamole doesn't have: a hardened Chromium on the server and a Linux desktop per user.

SSH

A browser terminal rendered by guacd's SSH plugin (xterm-256color), with file transfer straight to the target.

Password, private key or an ephemeral Ed25519 keypair generated per session
SFTP between the browser and the target, with no files stored on the rustguac server
Optional plain-text typescript recording per connection
Per-entry font size, and multi-hop jump hosts

SSH in the docs

RDP

Windows and Linux desktops with auto-fit resize, from plain password logins to Kerberos and RemoteApp.

Kerberos NLA authentication, domain logins and security mode settings
RemoteApp (RAIL) and Wake-on-LAN per entry
23 keyboard layouts, set on the connection or once for yourself under My keyboard layout
H.264 passthrough and the GFX pipeline for smooth video
Drive redirection with optional LUKS-encrypted per-session storage

RDP in the docs

VNC

Connect to any VNC server: KVM and IPMI consoles, existing remote desktops and virtual machine displays.

Password auth, VeNCrypt and macOS Screen Sharing logins, and UltraVNC's Windows login for Active Directory accounts
Network presets for LAN, WAN and slow links set the encodings, compression and JPEG quality
Per-entry clipboard copy and paste control
Fits the remote screen to the window or shows it at actual size with scroll bars, or resizes servers with their own virtual screen
Reachable through multi-hop SSH tunnels

VNC in the docs

SPICE

Direct SPICE displays for libvirt and QEMU consoles.

TLS with CA verification and certificate-subject pinning
SPICE proxy support
Checked against the VNC/SPICE network allowlist

SPICE in the docs

Proxmox VE

VM consoles brokered through the Proxmox VE API, so only an API token is ever stored.

One-time SPICE tickets fetched from the PVE spiceproxy API at connect time
Cluster node auto-detected from the VM ID
SSH-tunnel aware, including the API and console hops
Token needs only VM.Console (plus VM.Audit for node auto-detect)

Proxmox VE in the docs

Web

A real Chromium browser running headless on Xvnc on the server, streamed to the user's own browser.

Native autofill from Vault credentials, so passwords never reach the user
Per-entry domain allowlisting and login scripts (CDP-based, e.g. Playwright)
Isolated profile per session, deleted when the session ends
Chromium managed policy blocks downloads, file dialogs, DevTools UI and extensions

Web in the docs

VDI

Ephemeral Docker desktop containers, one per user, running xrdp and a Linux desktop. Bring your own image.

Persist after disconnect and are cleaned up after an idle timeout
Logging out of the desktop stops the container; closing the tab keeps it
Persistent home directories bind-mounted per user
Per-entry CPU, memory and idle limits, plus an image allowlist
Typed with your own keyboard layout, set once under My keyboard layout

VDI in the docs

Highlights

Built for people who run remote access for a living

Security-first defaults, credentials that never leave the server, and a deployment you can explain in one sentence.

No Java, no Tomcat

A single Rust binary in front of guacd, the same battle-tested protocol daemon Apache Guacamole uses. Install from a .deb, a Docker image or one script.

Seven session types

SSH, RDP, VNC, SPICE, Proxmox VE consoles, headless Chromium web sessions and per-user Docker VDI desktops, all in the browser with no client software.

Credentials stay in Vault

Connections and their secrets live in HashiCorp Vault or OpenBao KV v2. They are read server-side and never reach the browser.

OIDC SSO and four roles

Sign in with Authentik, Keycloak, Okta, Entra ID, Google or any OpenID Connect provider. OIDC groups map to admin, poweruser, operator and viewer.

Multi-hop SSH tunnels

Chain jump hosts to reach isolated networks for SSH, RDP, VNC, web and Proxmox sessions, with per-hop credentials kept in Vault.

Recording you can hand over

Every session recorded in Guacamole format with an in-app player, disk rotation, one-click MP4 downloads and plain-text SSH typescripts.

Locked down by default

TLS to the browser and to guacd, localhost-only CIDR allowlists out of the box, per-entry clipboard control, rate limiting and strict framing rules.

H.264 straight to the browser

Opt-in RDP H.264 passthrough forwards the server's stream to WebCodecs instead of re-encoding every frame, with AVC444 for crisp text.

Explore every feature

Screenshots

A tour of the web UI

Pick a screen, or flip this site's theme: the screenshots follow, in rustguac's own aurora and light themes.

A live SSH session: rustguac ssh session screen — **A live SSH session.** A full terminal in the browser through guacd, with clipboard, SFTP file transfer and session controls in the side tabs.

A live web session: rustguac web session screen — **A live web session.** Chromium runs on the server and streams into the browser, so internal web apps are reachable without exposing them.

Connections: rustguac connections screen — **Connections.** Folders of SSH, RDP, VNC, SPICE, Proxmox, web and VDI entries, shown only to the OIDC groups and users each folder allows.

Connection editor: rustguac rdp entry screen — **Connection editor.** Every per-entry setting in one form, from security mode and Kerberos to H.264 and clipboard control. Credentials are stored in Vault.

Web session entry: rustguac web entry screen — **Web session entry.** Point Chromium at an internal app, restrict it to allowed domains and let it autofill credentials the user never sees.

VDI desktop entry: rustguac vdi entry screen — **VDI desktop entry.** Pick the Docker image and set CPU, memory and idle limits for each user's desktop container.

Multi-hop SSH tunnels: rustguac jump hosts screen — **Multi-hop SSH tunnels.** Chain bastions per entry, each hop with its own credentials, to reach targets on isolated networks.

Active sessions: rustguac sessions screen — **Active sessions.** Live sessions with share links for control or view-only access, and watch and shadow controls for admins.

Recordings: rustguac recordings screen — **Recordings.** Every recorded session in one list, with playback in the browser and one-click MP4 downloads.

Recording player: rustguac player screen — **Recording player.** Play a session back in the browser and seek through it, without exporting anything.

Reports: rustguac reports screen — **Reports.** Summary cards, a searchable session history and top connections and users, with CSV export.

Admin: rustguac admin screen — **Admin.** Manage users, roles and the OIDC group-to-role mappings evaluated on every login.

Security

Locked down before you change a setting

Credentials stay in Vault and on the server. Network allowlists start at localhost. Both hops are encrypted. Then you open up exactly what you need.

TLS on both links. HTTPS to browsers via rustls, and TLS between rustguac and guacd, which listens on loopback only. Or terminate TLS at your reverse proxy.
Rate limiting. OIDC login is always limited per client IP. Turn on rate_limit for per-IP limits on the API, session creation and WebSockets.
Per-entry clipboard control. Disable copy, paste or both on any connection for data loss prevention, using guacd's native disable-copy and disable-paste.
Anti-clickjacking. No page can be framed by another site. Only sessions from entries an admin marks fullscreen-on-connect may be framed, and only by rustguac itself.
Hardened Chromium. Web sessions run with Chromium's sandbox, a managed policy that blocks downloads, file dialogs and extensions, and a fresh profile per session.
Audit trails. Authentication, session and admin events are logged with client IPs. Token operations and administrative CLI actions each get their own audit table.

Read the security guide

/opt/rustguac/config.toml

# config.toml: which networks each protocol may reach.
# Every list defaults to localhost only (SSRF-safe).
ssh_allowed_networks = ["127.0.0.0/8", "::1/128", "198.51.100.0/24"]
rdp_allowed_networks = ["203.0.113.0/24"]
vnc_allowed_networks = ["127.0.0.0/8", "::1/128"]
web_allowed_networks = ["127.0.0.0/8", "::1/128"]

# Per-IP limits on the API, session creation and WebSockets
rate_limit = true

[tls]
cert_path = "/opt/rustguac/tls/cert.pem"
key_path = "/opt/rustguac/tls/key.pem"
# Set this and rustguac talks TLS to guacd as well
guacd_cert_path = "/opt/rustguac/tls/cert.pem"

Found a vulnerability?Report it privately through GitHub's private vulnerability reporting.

Quickstart

Running in a couple of minutes

Docker anywhere, a .deb for Debian 13 (amd64 and arm64), or build it all from source. guacd is bundled every way.

Docker

docker pull sol1/rustguac:latest

# Web sessions need the image's seccomp profile for Chromium's sandbox
docker run --rm --entrypoint cat sol1/rustguac:latest /opt/rustguac/seccomp-chromium.json > seccomp-chromium.json
docker run -d --name rustguac -p 8089:8089 --security-opt seccomp=seccomp-chromium.json sol1/rustguac:latest

# First start prints a one-time admin API key
docker logs rustguac

Serves HTTP on port 8089, so put a reverse proxy in front for HTTPS. Bind-mount config.toml to /opt/rustguac/config.toml to keep settings. For VDI, also mount /var/run/docker.sock and add the docker group.

Debian 13 (.deb)

# Download rustguac_*.deb (amd64 or arm64) from GitHub Releases
sudo apt install ./rustguac_*.deb
/opt/rustguac/bin/rustguac --config /opt/rustguac/config.toml add-admin --name admin
sudo systemctl enable --now rustguac

Installs to /opt/rustguac and starts both rustguac-guacd and rustguac. Save the printed API key: it is shown once. Edit /opt/rustguac/config.toml, then set up Vault or OpenBao for the Connections UI.

From source

git clone https://github.com/sol1/rustguac.git
cd rustguac
sudo ./install.sh
/opt/rustguac/bin/rustguac --config /opt/rustguac/config.toml add-admin --name admin
sudo systemctl start rustguac

For Debian 13. Builds patched guacd and rustguac, creates the rustguac user, generates a self-signed certificate and installs systemd services. Use --no-tls to serve plain HTTP on port 8089, or --hostname=FQDN to name the certificate.

Install with Docker, the Debian package or the install script. Each one ships guacd and starts it for you.
Save the admin API key. It is printed once: by add-admin, or in the container logs on first start.
Connect Vault or OpenBao to turn on the Connections UI. contrib/vault-quickstart.sh sets one up in a single command.
Add OIDC and map your groups to admin, poweruser, operator and viewer.

Installation guide Production deployment

Not on Debian 13? Use the Docker image: the packaged guacd needs FreeRDP 3.15 or newer. See all install options.

Use cases

Where rustguac fits

From a homelab with a Proxmox cluster to an MSP handing out access per customer.

MSPs and multi-tenant teams

Give each customer or team a folder shared with their OIDC groups or named users, keep everyone's credentials in Vault, sync devices from NetBox, and lend folder default credentials to new entries.

Privileged access and bastions

Replace jump-box logins with browser sessions through multi-hop SSH tunnels, with per-protocol allowlists, ephemeral SSH keys, clipboard control and Knocknoc gating at HAProxy.

Audit and compliance

Record every session, export MP4s for review, keep greppable SSH typescripts on a LUKS volume, and pull session history as CSV for auditors.

Homelabs and Proxmox

Open Proxmox VE VM consoles with a single API token, reach libvirt SPICE displays and IPMI/KVM VNC consoles, and install from one .deb or Docker image.

Desktops for contractors

Hand out an isolated Linux desktop per user from your own Docker image, with persistent homes, resource limits and nothing to install on their machine.

Remote sessions inside your tools

Create sessions from your own backend with the REST API and send users to a single-use ticket URL, or lock a web session to one internal app with autofill.

Coming from Apache Guacamole?

Same guacd, a different webapp

Apache Guacamole is a mature, feature-rich platform. rustguac keeps its battle-tested protocol daemon and swaps the Java stack for one Rust binary with Vault, OIDC and more session types.

Area	rustguac	Apache Guacamole
Web application runtime	Rust, single binary	Java (Tomcat + Guice + Jersey)
Protocol daemon	guacd from guacamole-server, bundled	guacd from guacamole-server
Connection credentials	Vault / OpenBao KV v2, server-side only	Database tables
User authentication	OIDC SSO, API keys, user API tokens	LDAP, RADIUS, TOTP, SAML, database
Web browser sessions	Headless Chromium on Xvnc, with autofill and domain allowlists	Not supported
VDI desktops	Ephemeral Docker container per user	Not supported
Maturity	Newer project; built and tested on Debian 13, Docker elsewhere	Mature, feature-rich platform

The full comparison Import your Guacamole connections

FAQ

Common questions

What is rustguac?

rustguac is a lightweight, open-source replacement for the Apache Guacamole Java web application, written in Rust. It gives you browser-based SSH, RDP, VNC, SPICE, Proxmox VE consoles, web browser sessions and Docker VDI desktops through guacd, the same protocol daemon Guacamole uses. It adds OIDC single sign-on, a four-tier role system, Vault-backed connection storage, multi-hop SSH tunnels and session recording. See the overview.

Is rustguac a drop-in replacement for Apache Guacamole?

Not quite: rustguac replaces Guacamole's Java web application but keeps guacd and the Guacamole protocol, so your targets don't change while the management side does. Connections live in Vault or OpenBao instead of a SQL database, users sign in with OIDC instead of LDAP, RADIUS, TOTP, SAML or database accounts, and Guacamole user and group permissions are not carried over. The import-guacamole command brings across SSH, RDP and VNC connections from a MySQL/MariaDB dump. See rustguac vs Apache Guacamole.

Do I need HashiCorp Vault to run rustguac?

You need HashiCorp Vault or OpenBao for the Connections UI, which is rustguac's main user-facing feature. Connection entries and credentials are stored in Vault or OpenBao KV v2 and read server-side. Without one, rustguac still runs, but users can only make ad-hoc connections, from Connect to a host beside the search box or through the API. The bundled contrib/vault-quickstart.sh sets up an existing server, a dev server or a local install in one command; see Vault quickstart.

How do I install rustguac with Docker?

Run docker run -d -p 8089:8089 sol1/rustguac:latest, then read the one-time admin API key from the container logs. The image bundles guacd, uses TLS between rustguac and guacd, and serves HTTP on port 8089, so put a reverse proxy in front for HTTPS. To keep your settings, bind-mount a config.toml to /opt/rustguac/config.toml. Web browser sessions also need the seccomp profile shipped in the image (--security-opt seccomp=seccomp-chromium.json), because Docker's default profile blocks Chromium's sandbox; see running under Docker. The installation guide has a Docker Compose example with volumes for data and recordings.

Does rustguac support LDAP, SAML, RADIUS or TOTP?

No. rustguac authenticates users with OIDC single sign-on, plus API keys and personal API tokens for automation. It has no LDAP, SAML, RADIUS or built-in TOTP login. If your directory or MFA lives behind an identity provider that speaks OIDC, such as Keycloak, Authentik, Okta or Entra ID, put rustguac behind that. Credential variables give a similar experience to Guacamole's LDAP credential passthrough without binding to LDAP.

How do I migrate from Apache Guacamole?

Dump the guacamole_connection, guacamole_connection_parameter and guacamole_connection_group tables with mysqldump, then run rustguac import-guacamole --file guacamole-dump.sql --dry-run to preview and run it again without --dry-run to write to Vault. SSH, RDP (including RemoteApp) and VNC connections are imported, and connection groups become name prefixes. --map turns Guacamole's ${GUAC_USERNAME} tokens into rustguac credential variables. Users and permissions are not imported. See the migration guide.

All questions

Commercial support

Backed by the team that builds it

24 hour commercial support available

rustguac is developed by Sol1, a Sydney IT company. Running it somewhere that matters? Have a chat with the team.

Open-source specialistsSol1 has provided managed IT services for businesses since 1999, with Linux and open-source infrastructure at the core of its work.
The stack around rustguacSol1 also supports Proxmox VE, NetBox and Ansible network automation, Icinga monitoring and managed Linux firewalls.
Support hours and SLAsStandard support runs 8am to 5pm AEST, Monday to Friday, with extended hours under a service level agreement.

Open source

Apache-2.0, built in the open

rustguac is developed by Sol1 and contributors on GitHub. Star the repo, report a bug, or send a pull request.

Star on GitHub Documentation

Releases.deb packages for amd64 and arm64, and release notes. Docker HubThe sol1/rustguac image, guacd included. IssuesReport a bug or request a feature. SecurityPrivate vulnerability reporting.

Remote access in the browser, without the Java stack.