rustguac questions, answered

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.