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 your controller, usually within a few seconds on a local network. 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 persistent indicator naming who is connected, so the person there always knows control is in progress.

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 — close it from your controller, or the host user ends it from the indicator. 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).