{"id":43945376,"url":"https://github.com/sol1/rustguac","last_synced_at":"2026-05-06T08:02:18.751Z","repository":{"id":336770028,"uuid":"1151051508","full_name":"sol1/rustguac","owner":"sol1","description":"Lightweight Rust replacement for Apache Guacamole — browser-based SSH, RDP, VNC, and web sessions via guacd with SSH jump hosts, Kerberos NLA, Vault address book, and OIDC SSO","archived":false,"fork":false,"pushed_at":"2026-03-31T23:33:50.000Z","size":1716,"stargazers_count":29,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-04-02T07:38:58.366Z","etag":null,"topics":["bastion","guacamole","guacd","rdp","remote-access","remote-desktop","rust","ssh","vnc","websocket"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sol1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-06T01:58:25.000Z","updated_at":"2026-03-31T23:33:54.000Z","dependencies_parsed_at":"2026-02-17T00:01:41.169Z","dependency_job_id":null,"html_url":"https://github.com/sol1/rustguac","commit_stats":null,"previous_names":["sol1/rustguac"],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/sol1/rustguac","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sol1%2Frustguac","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sol1%2Frustguac/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sol1%2Frustguac/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sol1%2Frustguac/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sol1","download_url":"https://codeload.github.com/sol1/rustguac/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sol1%2Frustguac/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31580507,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bastion","guacamole","guacd","rdp","remote-access","remote-desktop","rust","ssh","vnc","websocket"],"created_at":"2026-02-07T03:02:32.468Z","updated_at":"2026-05-06T08:02:18.721Z","avatar_url":"https://github.com/sol1.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# rustguac\n\n[![CI](https://github.com/sol1/rustguac/actions/workflows/ci.yml/badge.svg)](https://github.com/sol1/rustguac/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/sol1/rustguac)](https://github.com/sol1/rustguac/releases/latest)\n[![License](https://img.shields.io/github/license/sol1/rustguac)](LICENSE)\n[![Docker](https://img.shields.io/docker/pulls/sol1/rustguac)](https://hub.docker.com/r/sol1/rustguac)\n\nA lightweight Rust replacement for the Apache Guacamole Java webapp. Browser-based SSH, RDP, VNC, web browsing, and VDI desktop containers through [guacd](https://github.com/apache/guacamole-server).\n\nNo Java. No Tomcat. Single binary + guacd.\n\n## Architecture\n\n```\nBrowser (HTML/JS)\n    |\n    | WebSocket over HTTPS\n    v\nrustguac (Rust, axum)\n    |\n    | TLS (Guacamole protocol)\n    v\nguacd (C, from guacamole-server)\n    |\n    +---\u003e SSH server\n    +---\u003e RDP server\n    +---\u003e VNC server\n    +---\u003e Xvnc + Chromium (web browser sessions)\n    +---\u003e Docker container + xrdp (VDI desktop sessions)\n```\n\n## Features\n\n### Session types\n\n| Type | Description |\n|------|-------------|\n| **SSH** | Browser-based terminal with password, private key, or ephemeral keypair auth. SFTP file transfer. |\n| **RDP** | Windows/Linux RDP with auto-fit resize, Kerberos NLA, RemoteApp/RAIL, H.264 passthrough, GFX pipeline. |\n| **VNC** | Connect to any VNC server (KVM/IPMI consoles, remote desktops, VM displays). |\n| **Web** | Headless Chromium on Xvnc with native autofill, domain allowlisting, login script automation. |\n| **VDI** | Ephemeral Docker desktop containers per user. Persist after disconnect, auto-cleanup on idle. |\n\n### Security \u0026 authentication\n\n- **OIDC single sign-on** — Authentik, Google, Okta, Keycloak, or any OpenID Connect provider\n- **4-tier role system** — admin, poweruser, operator, viewer with OIDC group mapping\n- **API key auth** — SHA-256 hashed keys with IP allowlists and expiry\n- **Vault-backed connections** — credentials in HashiCorp Vault or OpenBao KV v2, never reach the browser (see [Requirements](#requirements))\n- **TLS everywhere** — HTTPS for clients, TLS between rustguac and guacd\n- **CIDR allowlists** — per-protocol network restrictions for session targets\n- **Per-entry clipboard control** — disable copy and/or paste for data loss prevention\n- **Rate limiting** — per-IP, per-endpoint via tower_governor\n- **Session recording** — Guacamole format with playback UI, disk rotation, per-entry limits\n\n### Connectivity\n\n- **Multi-hop SSH tunnels** — chain jump hosts/bastions to reach isolated networks (all session types)\n- **Session sharing** — share tokens for read-only or collaborative access\n- **Encrypted file transfer** — LUKS-encrypted per-session drive storage (RDP), SFTP (SSH)\n- **Credential variables** — shared credentials across connections entries\n\n### VDI desktop containers\n\n- **Docker-based** — one container per user, deterministic naming, BYO image\n- **Persist after disconnect** — reconnect to the same desktop within idle timeout\n- **Logout detection** — desktop logout stops the container, tab close preserves it\n- **Session thumbnails** — live preview in the connections, click to reconnect\n- **Persistent home directories** — bind-mounted user data survives container restarts\n- **Per-entry resource limits** — CPU, memory, idle timeout per connections entry\n- **VdiDriver trait** — extensible for downstream forks (Nomad, Proxmox, cloud)\n\n### UI\n\n- **Connections** with folder-based organisation and OIDC group access control\n- **Active Sessions** section with live thumbnail previews\n- **Session ended overlay** with Reconnect/Close buttons\n- **8 built-in themes** with CSS gradient backgrounds, or configure your own\n- **Reports page** with session analytics, history, and CSV export\n\n## Requirements\n\n| Component | Status | Notes |\n|-----------|--------|-------|\n| guacd | Bundled | Built from `apache/guacamole-server`, ships in the .deb and Docker image. No separate install. |\n| **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`](contrib/vault-quickstart.sh) for one-command setup (auto-detects `vault` or `bao`, supports `--dev` and `--local` modes). |\n| OIDC provider | Optional | For SSO. API-key auth works on its own. Authentik/Google/Okta/Keycloak/JumpCloud all tested. |\n| Docker | Optional | Only needed for VDI desktop containers. |\n\n## Quick start\n\n### Debian 13 (.deb)\n\nPre-built packages for amd64 and arm64 are available from [Releases](https://github.com/sol1/rustguac/releases):\n\n```bash\nsudo apt install ./rustguac_*.deb\n/opt/rustguac/bin/rustguac --config /opt/rustguac/config.toml add-admin --name admin\nsudo systemctl enable --now rustguac\n```\n\n### Docker\n\n```bash\ndocker pull sol1/rustguac:latest\ndocker run -d -p 8089:8089 sol1/rustguac:latest\n```\n\nFor VDI support, mount the Docker socket:\n\n```bash\ndocker run -d -p 8089:8089 \\\n  -v /var/run/docker.sock:/var/run/docker.sock \\\n  --group-add $(getent group docker | cut -d: -f3) \\\n  sol1/rustguac:latest\n```\n\n### Other distributions\n\nPre-built packages are provided for Debian 13. For other distributions, build from source:\n\n```bash\nsudo ./install.sh\n```\n\nSee the [Installation guide](docs/installation.md) for full details including Docker Compose, TLS setup, and development builds.\n\n### VDI setup\n\nVDI requires Docker on the host:\n\n```bash\ncurl -fsSL https://get.docker.com | sh\nsudo usermod -aG docker rustguac\nsudo systemctl restart rustguac\n```\n\nAdd `[vdi]` to your config and create a VDI entry in the connections. See [VDI Desktop Containers](docs/vdi.md) for image requirements and configuration.\n\n## Documentation\n\n### Getting started\n- [Installation](docs/installation.md) — Debian packages, Docker, bare-metal, development builds\n- [Configuration](docs/configuration.md) — TOML config reference with all sections\n- [Deployment Guide](docs/deployment-guide.md) — step-by-step production setup\n\n### Features\n- [Roles \u0026 Access Control](docs/roles-and-access-control.md) — OIDC, roles, group mappings, API tokens\n- [Web Browser Sessions](docs/web-sessions.md) — autofill, domain allowlisting, login scripts\n- [VDI Desktop Containers](docs/vdi.md) — Docker desktops, image requirements, persistent homes\n- [RDP Video Performance](docs/rdp-video-performance.md) — H.264 passthrough, GFX pipeline, xrdp tuning\n- [Credential Variables](docs/credential-variables.md) — shared credentials across entries\n- [Reports](docs/reports.md) — session analytics, history, CSV export\n\n### Integration \u0026 reference\n- [Integrations](docs/integrations.md) — Vault, LUKS drives, SSH tunnels, Kerberos, HAProxy, Knocknoc\n- [NetBox](docs/netbox.md) — connections sync via custom fields and webhooks\n- [Security](docs/security.md) — TLS, rate limiting, headers, audit logging, hardening\n- [API Reference](docs/api.md) — REST API endpoints\n- [Migration from Apache Guacamole](docs/migration.md) — MySQL/MariaDB to Vault\n\n## Commercial support\n\nCommercial support for rustguac is available from [Sol1](https://www.sol1.com.au).\n\n## License\n\nApache License 2.0 — see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsol1%2Frustguac","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsol1%2Frustguac","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsol1%2Frustguac/lists"}