User Guide

Welcome to Vessel RDP! Select a section below to get your remote connections up and running on Linux securely and easily.

System Requirements

To ensure Vessel RDP runs smoothly and can display the Microsoft login windows for Azure AD, you need a few standard desktop libraries installed on your system. Most Linux distributions already have these, but if the app doesn't launch, configure or run the command for your distribution:

Linux Distribution Required Settings / Commands
Ubuntu / Debian sudo apt install libgtk-3-0 libwebkit2gtk-4.1-0 libfuse2
Fedora / RHEL sudo dnf install gtk3 webkit2gtk4.1 fuse
Arch Linux sudo pacman -S gtk3 webkit2gtk-4.1 fuse2
NixOS Add pkgs.gtk3, pkgs.webkit2gtk_4_1, and pkgs.fuse to environment packages.
ARM64 / Other architectures Ensure system webkit2gtk-4.1 and gtk3 library dependencies are aligned with your CPU architecture.

Note: If you only use standard RDP logins (no Azure AD), you do not need the WebKitGTK library.

Tip: If the app still won't start because FUSE isn't available, you can launch it without mounting by running it with the --appimage-extract-and-run flag: ./VesselRDP-x86_64.appimage --appimage-extract-and-run.

How to Use Vessel RDP

Adding a New Server

Connecting to a remote desktop is simple:

  1. Open Vessel RDP and look at the sidebar on the left.
  2. Click the Add Server button (+).
  3. Enter the server address (IP or hostname) and your username.
  4. (Optional) Organize your servers by dragging and dropping them into folders!

Connecting to Azure AD (Entra ID)

If your company uses Microsoft Azure AD for logins (including Multi-Factor Authentication):

  1. Select your server in the sidebar to open the Inspector panel.
  2. Change the Security Protocol dropdown from Auto to AAD.
  3. Ensure your username is your full email address (e.g., [email protected]). Note: Legacy formats like AzureAD\username are not supported.
  4. Click Connect. A secure Microsoft login window will pop up asking for your password and MFA code. Once approved, the desktop will load!

Core Features

  • Multi-Tab Sessions: You can connect to multiple servers at the same time. Each session opens in a new tab at the top of the screen.
  • Responsive Cursor: Your mouse cursor moves instantly and precisely, without waiting on the network. The hardware cursor rendering decouples pointer movement from RDP server frames, updating locally at native device refresh rates while syncing shape modifications (like resize bars, text input beams, or drag handlers) dynamically from the server.
  • Copy & Paste (Clipboard): You can seamlessly copy and paste text between your Linux machine and the remote Windows desktop, in both directions.
  • Remote Audio: Sound from the remote desktop plays through your local speakers. You can turn this on or off per server with the Audio toggle in the Inspector.
  • Adaptive Resolution: By default each session uses Adaptive resolution — resize the Vessel RDP window and the remote desktop adjusts to fit. You can also pick a fixed resolution (for example 1920×1080) from the Resolution dropdown.
  • Connection Quality: Choose a quality level (Poor, Medium, Good, or Best) per server to balance visual sharpness against responsiveness on slower networks.
  • Encrypted Passwords: We take your security seriously. If you save a password, it is safely stored in your Linux OS Keyring (like Secret Service or KWallet via DBus) and is never saved as plain text. The client features a Credential Storage Indicator settings badge showing active storage locations (OS Keyring vs. Local Fallback Database) and throws warning alerts if secure encryption channels fail.
  • Keyboard Accessible: The server list, session tabs, and toolbar are fully operable from the keyboard — Tab between them, Enter or Space to activate, and Delete or F2 on a focused server entry to delete or rename it.

Troubleshooting

Running into an issue? Here are the most common solutions:

Problem How to Fix It
Cannot Copy/Paste Select the server in the sidebar and ensure "Clipboard" is enabled before you connect.
No remote sound Select the server and make sure the Audio toggle is enabled before connecting.
Microsoft MFA window doesn't appear Your system is missing the web browser component. Install webkit2gtk-4.1 using the commands in the System Requirements section above.
Authentication Fails on a Corporate PC If the PC is joined to Azure AD/Entra, make sure you have changed the server's Security Protocol to AAD instead of standard TLS/NLA.
App says "could not open local database" This usually means Vessel RDP is already running in the background and locking the SQLite database. Close the existing window and try again. For concurrent multi-tab remote connections, ensure that you launch sessions within the same parent application instance to share access safely.
Path Warnings for Keys The security module displays absolute paths in permission warning dialogs. Audit permissions (e.g. chmod 600) on the specified absolute path to resolve credentials access blocks.
← Back to Home