Orchard Connect
LAN device pairing and playback handoff, including the approval flow, hashed device tokens, and network requirements.
Orchard Connect lets an approved device on your local network control Orchard desktop, and lets Orchard Mobile hand playback back and forth with the desktop.
Orchard Connect is the one part of Orchard that deliberately listens on the local network. Everything about its design follows from that.
What you can pair
- Orchard Mobile for Android, which can send playback to the desktop and take it back. See Orchard Mobile.
- A web controller, served by Orchard itself to any browser on the same network.
Pairing
On the desktop, open Settings → Orchard Connect. Orchard shows a pairing QR code and an
orchard-connect://pair link.
From the phone, open the device picker in Now Playing or Profile → Connected devices, then scan the QR code or paste the link. From a browser, open the URL shown on the desktop.
The desktop then shows a pending request. Approve it there. Nothing gets access until you do.
Both devices must be on the same network.
Security model
The design assumes the LAN is not trustworthy.
Pairing tokens authorize first contact only. They are short-lived and are consumed by the approval step.
Device tokens are stored only as hashes. The desktop keeps a SHA-256 hash of each paired device’s token, never the token itself. A stolen copy of the device file does not yield working credentials. Stored entries are validated against a strict 64-hex-character shape on import, so a malformed or tampered file is rejected rather than trusted.
Approval is explicit and per-device. A pairing request appears in the desktop UI and waits. There is no automatic acceptance.
On the phone side, the pairing token is encrypted with AES/GCM under an AndroidKeyStore-backed key, bound to the remembered host, and excluded from Android backups.
Devices are revocable. Remove a paired device from the desktop settings and its token hash goes with it.
Network details
| Item | Value |
|---|---|
| Preferred port | 32145 |
| Protocol version | 3 |
| Transport | HTTP plus WebSocket over the LAN |
| Address | First non-internal IPv4 interface, falling back to 127.0.0.1 |
Version negotiation clamps a client’s declared version to the desktop’s maximum. A newer client talking to an older desktop is treated as speaking the older protocol rather than being refused.
Paired devices are stored in a JSON file inside Orchard’s per-user data directory, holding device id, token hash, display name, pairing time, and last-seen time.
What a connected device can do
An approved controller can drive transport (play, pause, next, previous, seek), see and modify the queue, and read now-playing state including artwork. Orchard Mobile additionally supports handing a playing session between the phone and the desktop.
If pairing fails
- Confirm both devices are on the same subnet, and that client isolation (common on guest Wi-Fi) is not blocking device-to-device traffic.
- Confirm your firewall allows inbound TCP on port 32145 to Orchard.
- Under Flatpak, the sandbox must permit network access, which the published manifest does.
- Regenerate the pairing code from the desktop if the QR code has been on screen a long time.
More in Troubleshooting.
Source map
| Path | Role |
|---|---|
electron/connect/orchardConnectServer.js | LAN server, pairing, device tokens |
electron/connect/orchardConnectPage.js | Served web controller |
src/app/platform/connectActions.js | Renderer actions |
mobile/android/ | Android client |