Controller setup guide
Use an Android phone as a gamepad, keyboard, and mouse over Wi-Fi. Repo ↗
Install the host
Grab the build for your OS from the Releases page: installer for Windows, AppImage or deb for Linux, dmg for macOS.
Windows may ask firewall permission on first launch. Linux asks for the root password once to configure uinput for the virtual Xbox controller.
Connect the phone
Join the same Wi-Fi on phone and computer. Open the address the host shows (port 8080) in the phone browser and enter the PIN for first pairing.
Inputs travel over a WebSocket on port 8081 with low enough latency for real games. Rearrange the pad in the layout editor and switch themes without reconnecting.
Note: Phone and computer must stay on the same network. Guest or client-isolated Wi-Fi networks block the connection.
Per-OS behavior
Linux and Windows expose a full virtual Xbox 360 controller through uinput and ViGEmBus, so games detect a real gamepad.
macOS blocks virtual gamepads, so the phone maps to keyboard and mouse instead. Configure the game for keyboard controls and everything still plays.
Gyro aiming, haptics, and the fast-forward key work on all three platforms.
Latency tips
Use 5 GHz Wi-Fi with both devices in the same room. Most perceived lag is the router, not the app.
Close background downloads and streams on both devices while playing. A saturated uplink delays every input packet equally.
Troubleshooting
Phone cannot reach the host: confirm both are on the same network and the firewall allowed the app. Retry the address shown in the host window exactly, including the port.
No inputs register on Linux: the uinput setup from first launch did not complete. Re-run with root once, then restart the app.
Buttons do nothing on macOS: the game is listening for a gamepad. Switch it to keyboard controls and map the phone buttons to keys.