|
| 1 | +# Migration Guide |
| 2 | + |
| 3 | +InputFlow is a native Linux peer for PowerToys Mouse Without Borders (MWB). It is built to interoperate with the Windows PowerToys MWB implementation; it is not a generic Synergy-family protocol clone and should not be expected to join Barrier, Synergy, Input Leap, Deskflow, or Cursr groups directly. |
| 4 | + |
| 5 | +Use this guide when moving from another keyboard/mouse sharing setup, from Wine-based MWB experiments, or from an older InputFlow configuration. |
| 6 | + |
| 7 | +## Mental Model |
| 8 | + |
| 9 | +PowerToys MWB and InputFlow use a peer model. Each machine has a name, address, shared security key, and layout position. There is no permanent "server" machine that owns every other client in the way Synergy-family tools commonly describe the topology. |
| 10 | + |
| 11 | +In practice: |
| 12 | + |
| 13 | +- The Windows machine runs PowerToys Mouse Without Borders. |
| 14 | +- The Linux machine runs InputFlow. |
| 15 | +- Both sides must agree on the shared key, peer names, peer addresses, and layout. |
| 16 | +- InputFlow can export a Windows helper script that seeds the Linux peer into PowerToys MWB settings. |
| 17 | + |
| 18 | +For the guided pairing flow, see [Public Beta Workflow](beta-workflow.md#guided-pairing-and-export-helper). |
| 19 | + |
| 20 | +## Legacy Term Map |
| 21 | + |
| 22 | +| Legacy term | InputFlow / PowerToys MWB concept | |
| 23 | +| --- | --- | |
| 24 | +| Server | A peer that currently owns the local pointer and sends input to another peer. This role is situational, not a fixed machine type. | |
| 25 | +| Client | A peer receiving remote input. This role is also situational. | |
| 26 | +| Screen | A machine entry in the current MWB layout. Display-level topology is a separate opt-in contract. | |
| 27 | +| Screen name | `machine_name` / MWB peer name. Names must match what the other peer expects. | |
| 28 | +| Configuration file | `~/.config/mwb-client/config.ini` for InputFlow; PowerToys MWB settings on Windows. | |
| 29 | +| Shared secret / password | MWB security key. InputFlow can read it from an inline `key`, `key_file`, or Secret Service `key_secret_id`. | |
| 30 | +| Edge transition | MWB layout adjacency between peers. | |
| 31 | +| Clipboard sharing | InputFlow clipboard sync using local helper tools and MWB clipboard transport. | |
| 32 | +| Barrier / Synergy protocol | Not applicable. InputFlow targets PowerToys MWB compatibility instead. | |
| 33 | + |
| 34 | +This map is only a vocabulary bridge. It does not claim that the named projects are maintained, unmaintained, compatible, or incompatible beyond the protocol distinction above. |
| 35 | + |
| 36 | +## Migrating From Barrier, Synergy, Input Leap, Deskflow, Or Cursr |
| 37 | + |
| 38 | +Do not reuse old server/client topology files as-is. Convert the intent instead: |
| 39 | + |
| 40 | +1. Pick the Windows PowerToys MWB machine and Linux InputFlow machine names. |
| 41 | +2. Choose or copy the MWB security key into one InputFlow authentication source. |
| 42 | +3. Set the Windows host IP and InputFlow local machine name in `config.ini` or the desktop UI. |
| 43 | +4. Export the Windows pairing helper from InputFlow and run it on Windows. |
| 44 | +5. Verify the peer layout in PowerToys MWB before starting regular use. |
| 45 | + |
| 46 | +Common differences to expect: |
| 47 | + |
| 48 | +- InputFlow joins a PowerToys MWB peer group, not a Synergy-family server process. |
| 49 | +- Layout is expressed through MWB peer placement, not a separate Synergy-style screen graph. |
| 50 | +- Input injection on Linux depends on `/dev/uinput`; Wayland may also require compositor policy or user approval. |
| 51 | +- Clipboard support depends on installed local helpers. Install `wl-clipboard` for Wayland or `xclip`/`xsel` for X11 when needed. |
| 52 | + |
| 53 | +## Migrating From Wine Or Windows MWB Attempts |
| 54 | + |
| 55 | +Running Windows PowerToys MWB through Wine is not the intended Linux path. InputFlow replaces that approach with a native Linux peer that talks to PowerToys MWB on Windows. |
| 56 | + |
| 57 | +Before migrating: |
| 58 | + |
| 59 | +- Stop any Wine-hosted MWB process so it does not compete for ports or peer names. |
| 60 | +- Keep the PowerToys MWB security key if you want the same trusted group. |
| 61 | +- Recreate the Linux peer through InputFlow export rather than copying Wine registry or settings files. |
| 62 | +- Expect Linux input delivery to use `/dev/uinput`, not Windows input APIs. |
| 63 | + |
| 64 | +If a previous Wine setup used the same Linux machine name, remove stale duplicate peer entries from PowerToys MWB or overwrite them with the exported helper. |
| 65 | + |
| 66 | +## Authentication Sources |
| 67 | + |
| 68 | +Configure exactly one practical key source for normal use: |
| 69 | + |
| 70 | +- `key=` stores the MWB security key inline in `config.ini`; simple but easiest to expose. |
| 71 | +- `key_file=` reads the key from a local file; preferable for scripts and backups. |
| 72 | +- `key_secret_id=` reads from Secret Service through the desktop session keyring; preferable when a session bus and keyring are available. |
| 73 | + |
| 74 | +Avoid publishing configs, helper scripts, logs, or screenshots that expose keys, peer IPs, or Secret Service identifiers. |
| 75 | + |
| 76 | +## Topology Roadmap |
| 77 | + |
| 78 | +InputFlow defaults to MWB-compatible machine placement. Optional topology adds a cleaner machine/display split, explicit wrap policies, AAB/BAA/ABA layouts, stacked layouts, asymmetric layouts, and configured cross-machine edge handoff. |
| 79 | + |
| 80 | +Until the runtime topology feature gate is enabled and validated for your setup, treat topology as machine-level MWB placement and verify changes in PowerToys MWB after exporting. If you are testing the layout wizard or runtime topology branch, use the [Topology Config Contract](topology.md) and keep `wrap=none` with explicit links until validation output matches the intended handoff behavior. |
0 commit comments