How a session works

A session is a live remote-control connection: you see another machine's screen and control its mouse and keyboard. This page explains what happens from the moment you connect to the moment the session ends.

If you only want to get a machine reachable, start with Getting started. This page is about using a connection.

1. Connect by code (or by device)

You start a session from your Partner controller in one of two ways:

• By code (no account). Enter the host machine's machine ID and its current connection code (the host owner runs partnerd status to read them). The code is short-lived and rotates after use, so ask for a fresh one if it has expired.
• From your device list (signed in). If you own the machine and have claimed it, just pick it from your list — no code needed.

2. The host approves you (consent)

The very first thing that happens is consent — Partner never shows your screen to anyone without permission:

• Someone is at the host: they see a prompt naming who is connecting, with Approve and Deny. No video or control happens until they approve. If they walk away, the request times out and is treated as a denial.
• It's your own pre-authorized machine: if you enabled unattended access for that device while signed in, it starts without a prompt — that's how you reach your own computers when no one is there. You can turn this off (revoke) at any time; the next connection then asks for consent again.

If you're neither approved at the host nor connecting to your own pre-authorized device, the session is refused. There is no silent control.

3. Control the desktop

Once approved, the host's screen appears in a window of its own, usually within a few seconds on a local network. Partner's main window stays as it is, so you can connect to more machines — or to the same machine again — and each connection gets its own window, which you can arrange however you like. A second window to the same machine is numbered, for example "Office PC (2)". Your mouse movements, clicks, scrolling, and keystrokes are sent to the host and applied there.

The connection is peer-to-peer and encrypted end-to-end: your screen data travels directly between the two machines whenever possible. If a firewall or NAT blocks the direct path, Partner automatically falls back to a relay so the session still works — you don't have to configure anything.

While a session is active, the host shows a connections panel at the right edge of its screen, listing who is connected, whether they can only view or also control, and for how long. Push it off the edge with its arrow and it leaves a small flap with the number of connections; click the flap to bring it back. The panel never appears in the picture the person connecting sees on Windows and macOS (on Linux it does).

GNOME on Wayland

GNOME does not let any app keep a window on top of the others there, so on that desktop the panel is Partner's icon in the top bar, with a red badge counting the connections. Its menu lists each connection with a Disconnect item.

4. Pick a display

If the host has more than one monitor, your controller lists the available displays. Pick one to view it; you can switch to another display during the session and the stream follows within a couple of seconds.

If a display can't be captured properly (for example it would show only black), Partner tells you the capture is unhealthy instead of streaming a black screen, so you know something's wrong rather than staring at nothing.

Wayland (Linux)

On Linux/Wayland the system asks the host user which screen to share through the desktop's own screen-sharing dialog. You can only switch among the displays they allowed — if you pick one that wasn't shared, Partner says so rather than showing black.

5. End the session

Either side can end the session at any time:

• From your controller: close the connection's window (or press End session). Only that connection ends; your other windows keep going. Closing Partner's main window while connections are open just hides it — the app quits once the last connection window is closed (or stays in the tray when unattended access is on).
• At the host: press ✕ next to a connection in the panel (or Disconnect in the top-bar menu on GNOME Wayland). Only that connection ends, at once, and the person connecting is told the host ended it. Closing the panel itself ends nothing.

If your network drops, the session ends cleanly on its own.

When a session ends, the host stops capturing immediately and releases mouse and keyboard control, returning to idle. Reconnecting starts a brand-new session (and asks for consent again, unless it's your own pre-authorized device).

Troubleshooting

• "Code expired" — the connection code rotates; ask the host owner to run partnerd status (or partnerd rotate) for a current one.
• Stuck connecting / "connectivity failed" — see Troubleshooting; the host may be offline or both networks may block direct and relay paths.
• Black screen / "capture unhealthy" — the selected display can't be captured; try another display, or check the host's screen-recording permission (macOS) or screen-share grant (Wayland).