A 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.
- Create and manage multiple RDP connections from the Nextcloud sidebar
- Live RDP sessions rendered in the browser via Apache Guacamole
- Passwords stored encrypted in the Nextcloud database
- Configurable resolution per connection (720p, 1080p, 1440p, or custom)
- Keyboard layout selectable per connection or as a default, with automatic detection
- Fullscreen mode
- Works in any modern browser; no plugins required
| Requirement | Notes |
|---|---|
| Nextcloud ≥ 27 | Already installed and running |
| Debian / Ubuntu server | Where Nextcloud runs; apt access required |
| Node.js 18+ | For the guaclite WebSocket proxy |
| An RDP-enabled target machine | Windows Remote Desktop or any RDP server on TCP 3389 |
sudo apt update
sudo apt install guacd
sudo systemctl enable --now guacdVerify it is listening on port 4822:
sudo systemctl status guacdChoose a random 32-character string. It must be exactly 32 characters — AES-256-CBC requires a 32-byte key.
# Generate one quickly
cat /dev/urandom | tr -dc 'A-Za-z0-9' | head -c 32Create /etc/guaclite.env (readable only by root / the service user):
GUACD_HOST=127.0.0.1
GUACD_PORT=4822
GUAC_SECRET=change_me_to_exactly_32_chars!!!
sudo chmod 600 /etc/guaclite.envImportant: This value must match the
guac_secretyou set later in the Nextcloud admin panel. If they differ, guaclite silently decrypts to garbage and all RDP connections will fail.
guacamole-lite is a lightweight Node.js WebSocket proxy between the browser and guacd.
sudo mkdir /opt/guaclite
sudo npm install --prefix /opt/guaclite guacamole-lite@1
sudo cp guaclite-server.js /opt/guaclite/Create the systemd service at /etc/systemd/system/guaclite.service:
[Unit]
Description=guacamole-lite WebSocket proxy
After=network.target guacd.service
Requires=guacd.service
[Service]
Type=simple
WorkingDirectory=/opt/guaclite
EnvironmentFile=/etc/guaclite.env
ExecStart=/usr/bin/node /opt/guaclite/guaclite-server.js
Restart=on-failure
User=nobody
Group=nogroup
[Install]
WantedBy=multi-user.targetEnable and start it:
sudo systemctl daemon-reload
sudo systemctl enable --now guaclite
sudo systemctl status guaclite
# Should show: [guaclite] listening on :8080Copy the app into your Nextcloud custom_apps directory and enable it:
# Adjust the target path to match your Nextcloud installation
sudo cp -r web-rdp /var/www/nextcloud/custom_apps/
sudo chown -R www-data:www-data /var/www/nextcloud/custom_apps/web-rdp
sudo -u www-data php /var/www/nextcloud/occ app:enable web-rdpIn Nextcloud: Admin (top-right) → Administration settings → Connected Accounts → Web RDP
| Setting | Value |
|---|---|
| guaclite URL | ws://localhost:8080 |
| Secret key | The same 32-character string you put in /etc/guaclite.env as GUAC_SECRET |
Or set via command line:
sudo -u www-data php /var/www/nextcloud/occ config:app:set web-rdp guaclite_url --value="ws://localhost:8080"
sudo -u www-data php /var/www/nextcloud/occ config:app:set web-rdp guac_secret --value="your_32_char_secret_here"- Open your Nextcloud and navigate to Web RDP in the app menu
- Click + in the left sidebar
- Fill in: Name, Host (IP or hostname of the target machine), Username, Password
- Click Save, then click Connect
The RDP session opens in the main area.
| Setting | Default | Description |
|---|---|---|
guaclite_url |
ws://localhost:8080 |
WebSocket URL of the guaclite service. Change if you run guaclite on a different host or port. |
guac_secret |
(set manually) | Must match GUAC_SECRET in /etc/guaclite.env. Used to decrypt the encrypted token the browser sends to guaclite. |
The RDP keyboard layout (server-layout) must match the keyboard layout of the remote Windows computer.
guacd translates keys into scancodes for that layout, so a mismatch swaps keys (typically z and y).
You can set it in two places:
- Settings dialog → Keyboard layout of the remote computer: the default for all your connections.
- Connection form → Keyboard layout of this computer: overrides the default for one connection.
If nothing is set, the layout is detected automatically. The first match wins:
- Layout saved on the connection
- Default from the settings dialog
- Layout detected in the browser (
navigator.keyboard.getLayoutMap(), Chromium only; otherwisenavigator.language) - Nextcloud language, then Nextcloud locale (
de→de-de-qwertz,en_GB→en-gb-qwerty, …) en-us-qwerty
Supported layouts:
| Value | Layout | Value | Layout |
|---|---|---|---|
de-de-qwertz |
Deutsch (DE) | sv-se-qwerty |
Svenska |
de-ch-qwertz |
Deutsch (CH) | da-dk-qwerty |
Dansk |
en-us-qwerty |
English (US) | no-no-qwerty |
Norsk |
en-gb-qwerty |
English (UK) | pl-pl-qwerty |
Polski |
fr-fr-azerty |
Français (FR) | hu-hu-qwertz |
Magyar |
fr-be-azerty |
Français (BE) | ro-ro-qwerty |
Română |
fr-ch-qwertz |
Français (CH) | tr-tr-qwerty |
Türkçe |
es-es-qwerty |
Español (ES) | ja-jp-qwerty |
日本語 |
es-latam-qwerty |
Español (LatAm) | pt-pt-qwerty |
Português (PT) |
it-it-qwerty |
Italiano | pt-br-qwerty |
Português (BR) |
Upgrading: this feature adds a
keyboard_layoutcolumn. Apply the migration withocc app:disable web-rdp && occ app:enable web-rdp.
The keyboard layout sent to the remote computer does not match its actual layout. Set the correct layout in the settings dialog or in the connection form (see Keyboard layout), then reconnect. An already running session keeps its old layout.
The 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.
Fix: make sure both values are identical, then reconnect.
Shown in guaclite logs. The secret is mismatched or the token format is wrong. Verify:
GUAC_SECRETin/etc/guaclite.envequals theguac_secretin the Nextcloud admin panel- The value is exactly 32 characters
journalctl -u guaclite --since "5 minutes ago"GUAC_SECRET is not exactly 32 characters. AES-256-CBC requires a 32-byte key. Count the characters and adjust.
The 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).
- Confirm the target machine has Remote Desktop enabled
- Confirm no firewall blocks TCP 3389
- Test connectivity from the server:
nc -zv <host> 3389
# guaclite — WebSocket / token errors
journalctl -u guaclite -f
# guacd — RDP-level errors (auth failures, display issues)
journalctl -u guacd -f
# Nextcloud PHP errors
sudo tail -f /var/www/nextcloud/data/nextcloud.logThe frontend is a Vue 3 SPA built with webpack. After editing files in src/, rebuild:
cd custom_apps/web-rdp
# Install dependencies (first time only)
npm install
# Watch mode — rebuilds automatically on file save
npm run dev
# Production build
npm run buildOn Windows PowerShell (the npm scripts use NODE_ENV=x which fails in cmd/PowerShell):
$env:NODE_ENV='production'; npx webpack --config webpack.config.jsThe compiled output goes to js/web-rdp-main.js, which is served by Nextcloud automatically — no restart needed after a rebuild.
Browser (Vue 3 + guacamole-common-js)
↕ AJAX/POST (JSON)
Nextcloud PHP · ConnectionController · TunnelController
↕ AES-256-CBC encrypted token (WebSocket)
guacamole-lite (ws://localhost:8080)
↕ Guacamole protocol (TCP 4822)
guacd
↕ RDP (TCP 3389)
Target machine (Windows Remote Desktop / any RDP server)
If you encounter any issues or have questions:
- 🐛 Report bugs
- 💡 Request features
- ⭐ Star the repo if you find it useful!
If you like this project, support further development with a repost or coffee:
- 🧑💻 Markus Begerow
- 💾 GitHub