{"id":50936447,"url":"https://github.com/markusbegerow/nextcloud-web-rdp","last_synced_at":"2026-06-17T09:32:15.816Z","repository":{"id":359839735,"uuid":"1247483710","full_name":"markusbegerow/nextcloud-web-rdp","owner":"markusbegerow","description":"Browser-based RDP access for Nextcloud using Apache Guacamole and guacamole-lite.","archived":false,"fork":false,"pushed_at":"2026-05-23T17:13:41.000Z","size":23,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-23T19:09:50.553Z","etag":null,"topics":["apache-guacamole","browser-rdp","guacamole","guacamole-lite","homelab","nextcloud","nextcloud-app","rdp","remote-desktop","self-hosted"],"latest_commit_sha":null,"homepage":"https://markus-begerow.de/linktree","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/markusbegerow.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":null,"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-05-23T11:30:53.000Z","updated_at":"2026-05-23T17:13:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/markusbegerow/nextcloud-web-rdp","commit_stats":null,"previous_names":["markusbegerow/nextcloud-web-rdp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/markusbegerow/nextcloud-web-rdp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markusbegerow%2Fnextcloud-web-rdp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markusbegerow%2Fnextcloud-web-rdp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markusbegerow%2Fnextcloud-web-rdp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markusbegerow%2Fnextcloud-web-rdp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markusbegerow","download_url":"https://codeload.github.com/markusbegerow/nextcloud-web-rdp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markusbegerow%2Fnextcloud-web-rdp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34443232,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["apache-guacamole","browser-rdp","guacamole","guacamole-lite","homelab","nextcloud","nextcloud-app","rdp","remote-desktop","self-hosted"],"created_at":"2026-06-17T09:32:15.577Z","updated_at":"2026-06-17T09:32:15.810Z","avatar_url":"https://github.com/markusbegerow.png","language":null,"funding_links":["https://paypal.me/MarkusBegerow"],"categories":[],"sub_categories":[],"readme":"# Web RDP for Nextcloud\n\n\u003cimg alt=\"nextcloud-web-rdp\" src=\"https://github.com/user-attachments/assets/9486f908-1543-4d74-8c39-da1ce1b1e2be\" /\u003e\n\nA Nextcloud app that lets users open RDP (Remote Desktop Protocol) sessions directly in the browser — no VPN client, no separate remote-desktop software needed. Connections are stored securely in Nextcloud and accessible to any logged-in user.\n\n---\n\n## Features\n\n- Create and manage multiple RDP connections from the Nextcloud sidebar\n- Live RDP sessions rendered in the browser via Apache Guacamole\n- Passwords stored encrypted in the Nextcloud database\n- Configurable resolution per connection (720p, 1080p, 1440p, or custom)\n- Fullscreen mode\n- Works in any modern browser; no plugins required\n\n---\n\n## Prerequisites\n\n| Requirement | Notes |\n|---|---|\n| Nextcloud ≥ 27 | Already installed and running |\n| Debian / Ubuntu server | Where Nextcloud runs; `apt` access required |\n| Node.js 18+ | For the guaclite WebSocket proxy |\n| An RDP-enabled target machine | Windows Remote Desktop or any RDP server on TCP 3389 |\n\n---\n\n## Quick Start\n\n### 1. Install guacd\n\n```bash\nsudo apt update\nsudo apt install guacd\nsudo systemctl enable --now guacd\n```\n\nVerify it is listening on port 4822:\n\n```bash\nsudo systemctl status guacd\n```\n\n### 2. Set the encryption secret\n\nChoose a random 32-character string. **It must be exactly 32 characters** — AES-256-CBC requires a 32-byte key.\n\n```bash\n# Generate one quickly\ncat /dev/urandom | tr -dc 'A-Za-z0-9' | head -c 32\n```\n\nCreate `/etc/guaclite.env` (readable only by root / the service user):\n\n```\nGUACD_HOST=127.0.0.1\nGUACD_PORT=4822\nGUAC_SECRET=change_me_to_exactly_32_chars!!!\n```\n\n```bash\nsudo chmod 600 /etc/guaclite.env\n```\n\n\u003e **Important:** This value must match the `guac_secret` you set later in the Nextcloud admin panel. If they differ, guaclite silently decrypts to garbage and all RDP connections will fail.\n\n### 3. Set up guacamole-lite\n\nguacamole-lite is a lightweight Node.js WebSocket proxy between the browser and guacd.\n\n```bash\nsudo mkdir /opt/guaclite\nsudo npm install --prefix /opt/guaclite guacamole-lite@1\nsudo cp guaclite-server.js /opt/guaclite/\n```\n\nCreate the systemd service at `/etc/systemd/system/guaclite.service`:\n\n```ini\n[Unit]\nDescription=guacamole-lite WebSocket proxy\nAfter=network.target guacd.service\nRequires=guacd.service\n\n[Service]\nType=simple\nWorkingDirectory=/opt/guaclite\nEnvironmentFile=/etc/guaclite.env\nExecStart=/usr/bin/node /opt/guaclite/guaclite-server.js\nRestart=on-failure\nUser=nobody\nGroup=nogroup\n\n[Install]\nWantedBy=multi-user.target\n```\n\nEnable and start it:\n\n```bash\nsudo systemctl daemon-reload\nsudo systemctl enable --now guaclite\nsudo systemctl status guaclite\n# Should show: [guaclite] listening on :8080\n```\n\n### 4. Install the web-rdp app\n\nCopy the app into your Nextcloud `custom_apps` directory and enable it:\n\n```bash\n# Adjust the target path to match your Nextcloud installation\nsudo cp -r web-rdp /var/www/nextcloud/custom_apps/\nsudo chown -R www-data:www-data /var/www/nextcloud/custom_apps/web-rdp\n\nsudo -u www-data php /var/www/nextcloud/occ app:enable web-rdp\n```\n\n### 5. Configure the admin settings\n\nIn Nextcloud: **Admin (top-right) → Administration settings → Connected Accounts → Web RDP**\n\n| Setting | Value |\n|---|---|\n| guaclite URL | `ws://localhost:8080` |\n| Secret key | The same 32-character string you put in `/etc/guaclite.env` as `GUAC_SECRET` |\n\nOr set via command line:\n\n```bash\nsudo -u www-data php /var/www/nextcloud/occ config:app:set web-rdp guaclite_url --value=\"ws://localhost:8080\"\nsudo -u www-data php /var/www/nextcloud/occ config:app:set web-rdp guac_secret --value=\"your_32_char_secret_here\"\n```\n\n### 6. Add your first RDP connection\n\n1. Open your Nextcloud and navigate to **Web RDP** in the app menu\n2. Click **+** in the left sidebar\n3. Fill in: **Name**, **Host** (IP or hostname of the target machine), **Username**, **Password**\n4. Click **Save**, then click **Connect**\n\nThe RDP session opens in the main area.\n\n---\n\n## Configuration reference\n\n### Nextcloud app settings (Admin → Connected Accounts → Web RDP)\n\n| Setting | Default | Description |\n|---|---|---|\n| `guaclite_url` | `ws://localhost:8080` | WebSocket URL of the guaclite service. Change if you run guaclite on a different host or port. |\n| `guac_secret` | *(set manually)* | Must match `GUAC_SECRET` in `/etc/guaclite.env`. Used to decrypt the encrypted token the browser sends to guaclite. |\n\n---\n\n## Troubleshooting\n\n### Black / blank screen after connecting\n\nThe RDP session connects but shows nothing. Most likely cause: the `guac_secret` in the Nextcloud admin settings does not match `GUAC_SECRET` in `/etc/guaclite.env`. guaclite silently decrypts to garbage, guacd gets an invalid connection config, and sends no display data.\n\nFix: make sure both values are identical, then reconnect.\n\n### `Failed to decrypt token: Unexpected token ... is not valid JSON`\n\nShown in guaclite logs. The secret is mismatched or the token format is wrong. Verify:\n1. `GUAC_SECRET` in `/etc/guaclite.env` equals the `guac_secret` in the Nextcloud admin panel\n2. The value is exactly 32 characters\n\n```bash\njournalctl -u guaclite --since \"5 minutes ago\"\n```\n\n### `Invalid key length` in guaclite logs\n\n`GUAC_SECRET` is not exactly 32 characters. AES-256-CBC requires a 32-byte key. Count the characters and adjust.\n\n### WebSocket connection blocked (browser console: `ERR_BLOCKED_BY_RESPONSE`)\n\nThe Nextcloud Content Security Policy is blocking the WebSocket. Make sure the `guaclite_url` in the admin settings exactly matches the URL the browser is trying to connect to (including `ws://` vs `wss://` and the port).\n\n### RDP connection refused (port 3389)\n\n- Confirm the target machine has Remote Desktop enabled\n- Confirm no firewall blocks TCP 3389\n- Test connectivity from the server: `nc -zv \u003chost\u003e 3389`\n\n### Checking logs\n\n```bash\n# guaclite — WebSocket / token errors\njournalctl -u guaclite -f\n\n# guacd — RDP-level errors (auth failures, display issues)\njournalctl -u guacd -f\n\n# Nextcloud PHP errors\nsudo tail -f /var/www/nextcloud/data/nextcloud.log\n```\n\n---\n\n## Development\n\nThe frontend is a Vue 3 SPA built with webpack. After editing files in `src/`, rebuild:\n\n```bash\ncd custom_apps/web-rdp\n\n# Install dependencies (first time only)\nnpm install\n\n# Watch mode — rebuilds automatically on file save\nnpm run dev\n\n# Production build\nnpm run build\n```\n\nOn Windows PowerShell (the npm scripts use `NODE_ENV=x` which fails in cmd/PowerShell):\n\n```powershell\n$env:NODE_ENV='production'; npx webpack --config webpack.config.js\n```\n\nThe compiled output goes to `js/web-rdp-main.js`, which is served by Nextcloud automatically — no restart needed after a rebuild.\n\n---\n\n## Architecture\n\n```\nBrowser (Vue 3 + guacamole-common-js)\n    ↕  AJAX/POST (JSON)\nNextcloud PHP  ·  ConnectionController  ·  TunnelController\n    ↕  AES-256-CBC encrypted token  (WebSocket)\nguacamole-lite  (ws://localhost:8080)\n    ↕  Guacamole protocol  (TCP 4822)\nguacd\n    ↕  RDP  (TCP 3389)\nTarget machine (Windows Remote Desktop / any RDP server)\n```\n\n---\n\n## License\n\n[GPL-3.0](https://www.gnu.org/licenses/gpl-3.0.html) © [Markus Begerow](https://markus-begerow.de/linktree)\n\n---\n\n## 🙋‍♂️ Get Involved\n\nIf you encounter any issues or have questions:\n- 🐛 [Report bugs](https://github.com/markusbegerow/nextcloud-web-rdp/issues)\n- 💡 [Request features](https://github.com/markusbegerow/nextcloud-web-rdp/issues)\n- ⭐ Star the repo if you find it useful!\n\n## ☕ Support the Project\n\nIf you like this project, support further development with a repost or coffee:\n\n\u003ca href=\"https://www.linkedin.com/sharing/share-offsite/?url=https://github.com/MarkusBegerow/nextcloud-web-rdp\" target=\"_blank\"\u003e \u003cimg src=\"https://img.shields.io/badge/💼-Share%20on%20LinkedIn-blue\" /\u003e \u003c/a\u003e\n\n[![Buy Me a Coffee](https://img.shields.io/badge/☕-Buy%20me%20a%20coffee-yellow)](https://paypal.me/MarkusBegerow)\n\n## 📬 Contact\n\n- 🧑‍💻 [Markus Begerow](https://linkedin.com/in/markusbegerow)\n- 💾 [GitHub](https://github.com/markusbegerow)\n- ✉️ [Twitter](https://x.com/markusbegerow)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkusbegerow%2Fnextcloud-web-rdp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkusbegerow%2Fnextcloud-web-rdp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkusbegerow%2Fnextcloud-web-rdp/lists"}