rustguac

A lightweight Rust replacement for the Apache Guacamole Java webapp. Browser-based SSH, RDP, VNC, SPICE, Proxmox VE consoles, web browsing, and VDI desktop containers through guacd.

No Java. No Tomcat. Single binary + guacd.

Architecture

Browser (HTML/JS)
    |
    | WebSocket over HTTPS
    v
rustguac (Rust, axum)
    |
    | TLS (Guacamole protocol)
    v
guacd (C, from guacamole-server)
    |
    +---> SSH server
    +---> RDP server
    +---> VNC server
    +---> SPICE server (libvirt/QEMU displays)
    +---> Proxmox VE VM console (SPICE via the PVE spiceproxy API)
    +---> Xvnc + Chromium (web browser sessions)
    +---> Docker container + xrdp (VDI desktop sessions)

Features

Session types

Type	Description
SSH	Browser-based terminal with password, private key, or ephemeral keypair auth. SFTP file transfer.
RDP	Windows/Linux RDP with auto-fit resize, Kerberos NLA, RemoteApp/RAIL, H.264 passthrough, GFX pipeline.
VNC	Connect to any VNC server (KVM/IPMI consoles, remote desktops, VM displays).
SPICE	Direct SPICE displays (libvirt/QEMU consoles) with TLS, CA verification, certificate-subject pinning, and SPICE-proxy support.
Proxmox VE	VM consoles brokered through the Proxmox API. One-time SPICE tickets fetched just-in-time at connect (only the API token is stored), node auto-detected from the VM ID, and SSH-tunnel aware.
Web	Headless Chromium on Xvnc with native autofill, domain allowlisting, login script automation.
VDI	Ephemeral Docker desktop containers per user. Persist after disconnect, auto-cleanup on idle.

Security & authentication

• OIDC single sign-on: Authentik, Google, Okta, Keycloak, or any OpenID Connect provider
• 4-tier role system: admin, poweruser, operator, viewer with OIDC group mapping
• API key auth: SHA-256 hashed keys with IP allowlists and expiry
• Vault-backed connections: credentials in HashiCorp Vault or OpenBao KV v2, never reach the browser (see Requirements)
• TLS everywhere: HTTPS for clients, TLS between rustguac and guacd
• CIDR allowlists: per-protocol network restrictions for session targets
• Per-entry clipboard control: disable copy and/or paste for data loss prevention
• Rate limiting: per-IP, per-endpoint via tower_governor
• Session recording: Guacamole format with playback UI, disk rotation, per-entry limits

Connectivity

• Multi-hop SSH tunnels: chain jump hosts/bastions to reach isolated networks (all session types, including the Proxmox API and console hops)
• Session sharing: share tokens for read-only or collaborative access
• Headless API integration: create a session over the REST API and hand a browser a ready-to-open URL via a single-use WebSocket ticket, with no OIDC login and no API key in the browser (see Connecting to a session)
• Encrypted file transfer: LUKS-encrypted per-session drive storage (RDP), SFTP (SSH)
• Credential variables: shared credentials across connections entries

VDI desktop containers

• Docker-based: one container per user, deterministic naming, BYO image
• Persist after disconnect: reconnect to the same desktop within idle timeout
• Logout detection: desktop logout stops the container, tab close preserves it
• Session thumbnails: live preview in the connections, click to reconnect
• Persistent home directories: bind-mounted user data survives container restarts
• Per-entry resource limits: CPU, memory, idle timeout per connections entry
• VdiDriver trait: extensible for downstream forks (Nomad, Proxmox, cloud)

UI

• Connections with folder-based organisation and OIDC group access control
• Active Sessions section with live thumbnail previews
• Session ended overlay with Reconnect/Close buttons
• Clipboard panel controls (Home + Fullscreen)
• 8 built-in themes with CSS gradient backgrounds, or configure your own
• Reports page with session analytics, history, and CSV export

Requirements

Component	Status	Notes
guacd	Bundled	Built from apache/guacamole-server, ships in the .deb and Docker image. No separate install.
Vault or OpenBao	Required for the Connections UI	Stores connection entries and credentials server-side. Without it the Connections page is unavailable and users can only run ad-hoc sessions via the API. Use contrib/vault-quickstart.sh for one-command setup (auto-detects vault or bao, supports --dev and --local modes).
OIDC provider	Optional	For SSO. API-key auth works on its own. Authentik/Google/Okta/Keycloak/JumpCloud all tested.
Docker	Optional	Only needed for VDI desktop containers.

Quick start

Debian 13 (.deb)

Pre-built packages for amd64 and arm64 are available from Releases:

sudo apt install ./rustguac_*.deb
/opt/rustguac/bin/rustguac --config /opt/rustguac/config.toml add-admin --name admin
sudo systemctl enable --now rustguac

Docker

docker pull sol1/rustguac:latest
docker run -d -p 8089:8089 sol1/rustguac:latest

For VDI support, mount the Docker socket:

docker run -d -p 8089:8089 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --group-add $(getent group docker | cut -d: -f3) \
  sol1/rustguac:latest

Other distributions

Pre-built packages are provided for Debian 13. For other distributions, build from source:

sudo ./install.sh

See the Installation guide for full details including Docker Compose, TLS setup, and development builds.

VDI setup

VDI requires Docker on the host:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker rustguac
sudo systemctl restart rustguac

Add [vdi] to your config and create a VDI entry in the connections. See VDI Desktop Containers for image requirements and configuration.

Documentation

Getting started

• Installation: Debian packages, Docker, bare-metal, development builds
• Configuration: TOML config reference with all sections
• Deployment Guide: step-by-step production setup

Features

• Roles & Access Control: OIDC, roles, group mappings, API tokens
• Web Browser Sessions: autofill, domain allowlisting, login scripts
• VDI Desktop Containers: Docker desktops, image requirements, persistent homes
• RDP Video Performance: H.264 passthrough, GFX pipeline, xrdp tuning
• Credential Variables: shared credentials across entries
• Reports: session analytics, history, CSV export

Integration & reference

• Integrations: Vault, LUKS drives, SSH tunnels, Kerberos, HAProxy, Knocknoc
• NetBox: connections sync via custom fields and webhooks
• Security: TLS, rate limiting, headers, audit logging, hardening
• API Reference: REST API endpoints, the session connection flow, and headless ws-ticket integration
• Migration from Apache Guacamole: MySQL/MariaDB to Vault

Commercial support

Commercial support for rustguac is available from Sol1.

License

Apache License 2.0. See LICENSE for details.