Help

Getting started

Two computers, two roles
The computer you sit at connects; the computer you want to see accepts connections. A computer can do both.

On the computer you want to reach

1. Current computer > turn on Let paired computers connect.
2. If a Set up… button shows next to Desktop sharing, press it once.

On the computer you sit at

1. Connect tab > +. PairDesk lists the computers on your network that accept connections: pick one, or type its address (just the IP, e.g. 192.168.1.20) > Next.
2. If you can sign in to it with SSH, press Pair over SSH: no code needed. Otherwise type the code that pops up on the other computer.
3. Press Connect now.

Other computer not set up yet? If it accepts SSH logins, the + wizard offers Set it up over SSH: it installs PairDesk there if needed and turns remote access on. You type that computer's password once per session; PairDesk never saves it.

Nothing is installed or changed without asking first.

Pairing and unpairing

Pairing lets two computers trust each other. It uses a one-time code instead of a password.

Add a remote computer (the + on the computer you sit at): choose the computer or type its IP; PairDesk fills in the rest and asks it to show a code. Type the code, or press Pair over SSH: you sign in with that computer's password and PairDesk pairs by itself, with no code to type (best for a computer without a screen).
Pair a new computer (on the computer to reach): shows a code before anyone asks.
In a terminal: pairdesk scan lists computers, pairdesk pair 192.168.1.20 pairs, pairdesk pair 192.168.1.20 --ssh pairs over SSH without a code, and pairdesk pairing (on the other computer, e.g. over SSH) shows the code.

Codes have 16 characters, work once, for 10 minutes, with 3 tries, and only for the computer that asked for them. They're hidden until you press Show. Both computers prove they know the code, so nobody in between can take part. Each pairing attempt uses a new random key, like a one-time password; nothing is shared between installs.

Settings > Accept pairing requests only after I press "Pair a new computer": other computers can't make a code appear here by themselves. Pairing over SSH still works (the SSH password proves it's you).

Unpair: Current computer > Paired computers > Unpair. It removes the pairing on both computers. If the other one can't be reached, it removes it by itself the next time PairDesk starts there or tries to connect.

Connecting and sharing

Open Options on the Connect tab to choose what to share:

• Full desktop, Full screen, Use all current monitors
• Remote sound and Current microphone
• Shared clipboard: copy on one computer, paste on the other
• Share current folder / Open remote shared folder: each computer's "PairDesk Shared" folder appears on the other in ~/PairDesk/<name> (Settings changes which folder, or makes it read-only)
• Current printers on remote (with xrdp)
• Picture: Best for a wired network, Fast for weak Wi-Fi
• Direct desktop stream: faster on slow computers; uses the link automatically when not possible
• In app menu / Connect when I log in: one-click shortcuts

Wi-Fi drops are handled: PairDesk reconnects by itself and puts devices and folders back.

USB devices

USB devices (security keys like YubiKey, webcams, drives) can be used on the other computer, in both directions.

1. Once on each computer: Set up USB sharing (Settings, or the bar at the top). It needs your admin password once.
2. Connect tab > USB devices: flip the switch next to a device. Current computer → send to remote lends yours; Remote → use on current borrows theirs.

While lent, a device can't be used on its own computer. It comes back when you flip the switch off or disconnect. Devices plugged in later are sent automatically if their switch is on. PairDesk warns before you lend your own keyboard, mouse or touchscreen.

Desktop server problems

The computer you reach needs a desktop server. Current computer > Status > Desktop sharing > Set up… offers:

• GNOME Remote Login (Ubuntu/GNOME): you choose a user name and password for remote logins.
• xrdp (any desktop): log in with the normal user name and password. It makes its own desktop, so no monitor is needed.

"Error connecting to user session" or a grey screen with xrdp:

• xorgxrdp is missing: Set up… installs it, or run sudo apt install xorgxrdp there.
• The same user is signed in on that computer's screen: PairDesk offers to sign that session out after a 30-second notice there (anyone there can cancel).

Ubuntu 25.10 and later, GNOME 49 and later: GNOME runs only on Wayland, so xrdp can't start it ("Error connecting to user session"). Switch that computer to GNOME Remote Login with Set up…, or over SSH: pairdesk desktop gnome

Login failed: with GNOME Remote Login use the user name and password chosen there; with xrdp, the normal login.

Updating PairDesk

With the KnowReva apt repository, PairDesk updates with your normal system updates.

Between paired computers: when you connect and one computer has a newer PairDesk, PairDesk asks before signing in: Update first or Skip and connect.

• This computer is older: the newer version is copied from the remote computer and installed here.
• The remote computer is older: your version is sent there. If someone is signed in on its screen, it asks there; otherwise a terminal installs it over SSH (its password, then its admin password).

Nothing is installed without an administrator's password on the computer being updated.

Skipped the terminal? The update waits there. Install it later over SSH: pairdesk update --install
From a terminal: pairdesk update NAME

Both computers need PairDesk 2.7.0 or later. Update an older one once from its own screen, or with + > Set it up over SSH.

Check this computer

Help (?) > Check this computer… looks at everything PairDesk needs and says what to do about anything that's missing. It changes nothing by itself.

It checks the network, the viewer, whether paired computers answer, remote access, the desktop server, whether PairDesk keeps running when nobody is signed in, and USB sharing.

Copy report puts the result on the clipboard, handy when asking for help.
Over SSH: pairdesk doctor

Connection problems

"No PairDesk computer answers"

• Remote access is off there: Current computer > turn it on.
• A firewall blocks the port: sudo ufw allow 4722/tcp (or the port shown in Settings > Connection).
• Wrong address: use the one shown on that computer (Current computer > Address).

Computer is asleep: PairDesk sends Wake-on-LAN automatically. It needs Ethernet and Wake-on-LAN turned on in that computer's BIOS. While connected, the remote computer stays awake.

"Removed its pairing": the other computer unpaired. Pair again.

Still stuck? Help > Open log file, and look at the last lines.

The desktop window and its toolbar

The remote desktop opens in PairDesk's own window. Its toolbar has everything for the session:

• USB devices: send a device of this computer, or use one of the remote computer, also ones plugged in during the session.
• Camera: send a camera as video (see Cameras).
• Folders: open the remote computer's folder, or your shared folder.
• The PairDesk window, minimize, full screen on/off and Disconnect.

In full screen the toolbar drops down when the mouse touches the top edge of the screen.

Settings > Desktop window switches back to the viewer's own window (its bar: minimize, full screen, close; Ctrl+Alt+Enter leaves full screen). Several monitors also use the viewer's own window.

Closing the PairDesk main window while connected only minimizes it. The connection ends with Disconnect or when you close the desktop window.

Sound and microphone

Desktop toolbar > Sound:

• Sound of the remote computer: play it here (pick the speakers or headset), on the remote computer's own speakers, or off.
• Microphone sent to the remote computer: pick which microphone of this computer, e.g. your headset instead of the laptop's built-in one, or off.
• Reduce echo and room noise: cleans up the microphone (useful without a headset).

The same choices are under Connect > Options (Remote sound, Microphone sent). A change reopens the desktop view for a moment; the remote session itself stays. Choices are remembered for each computer.

Sounds hollow, like a big room? Pick your headset's microphone instead of the built-in one.

Cameras

A camera of this computer can be used on the remote computer, for video calls (Teams, Zoom, Meet in a browser) or camera apps. Toolbar > Camera > pick it.

It's sent as compressed video and shows up there as a camera called PairDesk camera (in the Camera app it can take a few seconds to appear): much smoother than sending it as a USB device, also over Wi-Fi.

The first time, PairDesk offers what's missing: ffmpeg here, and on the remote computer the virtual camera (v4l2loopback), installed over SSH. With Secure Boot on, the virtual camera driver may need to be allowed once (the message says how).

A camera sent as a USB device also works, but it needs a lot of bandwidth: on Wi-Fi the picture stutters or shows green bars.

Computers without a monitor

A computer without a monitor can accept connections. It just needs a one-time setup.

Help > Set up a computer without a monitor… does it from here over SSH. It opens a terminal that checks each step and asks before changing anything:
remote access on, keep running with nobody signed in, xrdp desktop server, automatic sign-in off, no sleeping at the sign-in screen, firewall, pairing.

PairDesk not installed there yet? + > type its IP > Next: when PairDesk doesn't answer but SSH does, Set it up over SSH copies PairDesk over and installs it first. Pairing then works without its screen: Pair over SSH, no code needed.

By hand, over SSH on that computer: pairdesk headless-setup

Uninstalling

Settings > Uninstall PairDesk… (or sudo pairdesk-uninstall):

• gives lent USB devices back and undoes setup,
• removes PairDesk and only the add-ons it installed,
• keeps packages you installed yourself or that other software uses,
• keeps the files in your shared folder.

Undo setup (Settings) only turns USB sharing and the network rule off and keeps PairDesk.