# rustguac

> rustguac is 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.

- Latest version: 1.13.4 (released 2026-10-21), Apache-2.0 licensed
- Source, releases and issues: https://github.com/sol1/rustguac
- Docker image: sol1/rustguac (https://hub.docker.com/r/sol1/rustguac)
- Packages: Debian 13 .deb for amd64 and arm64 from https://github.com/sol1/rustguac/releases
- Session types: SSH, RDP, VNC, SPICE, Proxmox VE, Web, VDI
- Requires guacd (bundled) and HashiCorp Vault or OpenBao for the Connections UI; OIDC is optional
- This is an independent community website, not affiliated with the Apache Software Foundation

## Site

- [Home](https://sol1.github.io/rustguac-website/): overview, architecture, session types, screenshots and quickstart
- [Features](https://sol1.github.io/rustguac-website/features/): the full feature catalog with links into the docs
- [Apache Guacamole alternative](https://sol1.github.io/rustguac-website/guacamole-alternative/): how rustguac compares, and how to migrate
- [FAQ](https://sol1.github.io/rustguac-website/faq/): installation, Vault, OIDC, protocols, recording and migration
- [Documentation](https://sol1.github.io/rustguac-website/docs/): every guide, synced from the rustguac repository
- [Full documentation as one text file](https://sol1.github.io/rustguac-website/llms-full.txt)

## Documentation

### Getting started

- [Overview](https://sol1.github.io/rustguac-website/docs/overview/): rustguac is a lightweight Rust replacement for the Apache Guacamole Java webapp.
- [Installation](https://sol1.github.io/rustguac-website/docs/installation/): Pre-built .deb packages are available from the releases page for Debian 13 (Trixie) and compatible distributions.
- [Configuration Reference](https://sol1.github.io/rustguac-website/docs/configuration/): rustguac reads a TOML configuration file. All settings have sensible defaults and are optional.
- [Deployment Guide](https://sol1.github.io/rustguac-website/docs/deployment-guide/): A step-by-step guide for planning and deploying rustguac in production.
- [Reverse Proxy Configuration](https://sol1.github.io/rustguac-website/docs/reverse-proxies/): HAProxy, nginx, Caddy, Apache and Traefik in front of rustguac, and the %2F gotcha.

### Features

- [Roles and Access Control](https://sol1.github.io/rustguac-website/docs/roles-and-access-control/): OIDC, the 4-tier role hierarchy, group mappings, folder access and API tokens.
- [Web Browser Sessions](https://sol1.github.io/rustguac-website/docs/web-sessions/): Web browser sessions give users a full Chromium browser running on the server, streamed to their own browser via the Guacamole protocol.
- [SPICE and Proxmox VE Sessions](https://sol1.github.io/rustguac-website/docs/spice-and-proxmox/): SPICE displays and Proxmox VE VM consoles: API tokens, one-time tickets, TLS pinning and tunnels.
- [VDI Desktop Containers](https://sol1.github.io/rustguac-website/docs/vdi/): rustguac can spawn ephemeral Docker desktop containers on demand. Each user gets their own isolated Linux desktop accessible via the browser, with no client…
- [RDP Video Performance](https://sol1.github.io/rustguac-website/docs/rdp-video-performance/): Guide to optimizing RDP video quality and frame rate through rustguac, particularly for video monitoring workloads.
- [H.264 passthrough for RDP](https://sol1.github.io/rustguac-website/docs/rdp-h264/): rustguac can forward an RDP server's H.264 stream straight to the browser's WebCodecs decoder instead of having guacd decode it and re-encode the pixels as…
- [Credential Variables](https://sol1.github.io/rustguac-website/docs/credential-variables/): Credential variables let connections entries reference shared credentials by name instead of storing passwords directly.
- [Reports](https://sol1.github.io/rustguac-website/docs/reports/): The reports page provides usage analytics and session history for your rustguac deployment. It is available to users with the poweruser role or higher.
- [Themes](https://sol1.github.io/rustguac-website/docs/themes/): rustguac ships with a small set of built-in colour presets and lets you add your own without recompiling.

### Integration & reference

- [Integrations](https://sol1.github.io/rustguac-website/docs/integrations/): OIDC SSO, Vault/OpenBao, SSH tunnels, Kerberos, HAProxy, Knocknoc and LUKS drives.
- [NetBox Integration](https://sol1.github.io/rustguac-website/docs/netbox/): rustguac integrates with NetBox to provide one-click remote console access from device pages.
- [Security](https://sol1.github.io/rustguac-website/docs/security/): rustguac is designed with a security-first approach. This document covers all security features and their implementation.
- [API Reference](https://sol1.github.io/rustguac-website/docs/api/): All API endpoints are under /api/. Authentication is via Authorization: Bearer <api-key> header, X-API-Key: <key> header, or OIDC session cookie.
- [Migrating from Apache Guacamole](https://sol1.github.io/rustguac-website/docs/migration/): rustguac can import connections from an Apache Guacamole MySQL/MariaDB database into its Vault-backed connections.

## Highlights

- 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.

## FAQ

### 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.

### Does rustguac need Java or Tomcat?

No. rustguac is a single Rust binary plus guacd, with no Java, no Tomcat, no WAR files and no JVM tuning. guacd is built from Apache guacamole-server and bundled in the .deb package and Docker image, so there is nothing separate to install.

### Which protocols does rustguac support?

rustguac supports seven session types: SSH, RDP, VNC, SPICE, Proxmox VE VM consoles, web browser sessions (headless Chromium on Xvnc) and VDI desktops (Docker containers running xrdp). SSH supports SFTP and ephemeral keys, and RDP supports Kerberos NLA, RemoteApp, H.264 passthrough and the GFX pipeline. Telnet and Kubernetes are not supported.

### 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.

### Can I run rustguac with Docker Compose or Kubernetes?

Yes, rustguac ships as a Docker image, and the docs include a Docker Compose example with volumes for the database and recordings. The documentation does not provide a Helm chart or Kubernetes manifests. It does document logging into Vault or OpenBao with a projected Kubernetes service-account token (workload JWT auth, added in 1.12), so a pod needs no stored Vault secret. See Docker Compose and workload JWT authentication.

### Which Linux distributions are supported?

rustguac is built and tested on Debian 13 (Trixie), with pre-built .deb packages for amd64 and arm64. On other distributions the Docker image is the recommended path, because the bundled guacd needs FreeRDP 3.15 or newer. An RPM spec and build script are included but untested, and source builds on Ubuntu 24.04 are possible but untested. See other Linux distributions.

### Which OIDC providers work with rustguac?

rustguac works with any OpenID Connect provider. Authentik, Google, Okta, Keycloak and JumpCloud have been tested, and the docs include step-by-step guides for Authentik and Microsoft Entra ID. OIDC groups can be mapped to roles and used to restrict Connections folders. See OIDC single sign-on.

### Why does rustguac say my identity provider has not verified my email address?

rustguac matches OIDC logins to users by email, so since 1.12 it refuses a login when the provider sends email_verified: false. authentik's default email scope mapping sends false for every user, so every authentik login is refused until you fix it. The recommended fix is an email scope mapping in authentik that sends "email_verified": True, used on the rustguac provider instead of the default one, as long as users can't change their own email in authentik. For providers you can't change, rustguac 1.13.4 adds allow_unverified_email = true under [oidc], with the same caveat. See the Authentik setup guide and how a login is matched to a user.

### 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.

### Does rustguac record sessions?

Yes. rustguac records sessions in the standard Guacamole format, plays them back in the browser, and rotates them by disk usage or count. Since 1.12, any recording can be downloaded as MP4. SSH connections can also write an opt-in plain-text typescript for audit, which is listed in the UI but never downloadable through it. See recording settings.

### Which browsers does rustguac support?

rustguac works in any modern browser, including Chrome, Firefox, Edge, Safari, Chromium and Brave. The only caveat is H.264-accelerated RDP, which is off by default and enabled per connection. It needs a browser that decodes H.264 through WebCodecs, which means Chrome or Firefox. Chromium and Brave builds without the bundled H.264 codec, and older Safari, show a blank display on those connections. Lock all keys in fullscreen, which sends Win, Alt+Tab and other shortcuts to the remote desktop, needs Chrome or Edge.

### What is rustguac's licence?

rustguac is licensed under the Apache License 2.0. The source, releases and issue tracker are on GitHub.

### Who maintains rustguac, and is commercial support available?

rustguac is developed by Sol1 and contributors in the open on GitHub, where issues and pull requests are welcome. According to the project README, commercial support for rustguac is available from Sol1; see commercial support for how to reach them. This website is a community project and is not affiliated with the Apache Software Foundation.

### 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.

### Is rustguac secure, and how do I report a vulnerability?

rustguac ships with secure defaults: TLS to the browser and to guacd, network allowlists that default to localhost only, credentials kept server-side in Vault, hashed API keys, strict framing headers and optional rate limiting, all described in the security guide. Report vulnerabilities privately through GitHub's private vulnerability reporting at github.com/sol1/rustguac/security, not in a public issue. Security fixes go into the latest release.

### What do I need to run VDI desktops?

VDI needs Docker on the same host as rustguac, the rustguac user in the docker group, a [vdi] section in config.toml, and at least one pre-pulled image that runs xrdp on port 3389. The image either provisions its account from the VDI_USERNAME and VDI_PASSWORD environment variables or uses a baked-in account. A minimal Debian and xfce4 example is in contrib/vdi-test-image/. See VDI prerequisites.

### Can I embed rustguac sessions in my own application?

Yes, using the headless API. Your backend creates a session with an API key (POST /api/sessions), mints a single-use, 30-second WebSocket ticket (POST /api/ws-ticket), and sends the user's browser to client_url?ticket=…, so the API key never reaches the browser. You can also build your own client on the same WebSocket using the Guacamole protocol. rustguac pages refuse to be framed by other sites, so open the session URL as a page or window. See headless API integration.

### Can rustguac reach servers behind a bastion host?

Yes. SSH, RDP, VNC, web and Proxmox sessions can be routed through a chain of SSH jump hosts, each with its own username and password or private key. Configure the chain on a connection entry, or add jump hosts to an ad-hoc session. Jump host credentials are stored in Vault and never sent to the browser. See multi-hop SSH tunnels.

### Does rustguac work with NetBox?

Yes. rustguac adds one-click console links to NetBox device pages and can keep its Connections in sync through NetBox webhooks, using NetBox's built-in custom fields, custom links and event rules. No NetBox plugin is required. See the NetBox guide.