ADBKit Wi-Fi Helper: Setup, Options and Troubleshooting
Technical reference for adbkit-bridge.mjs, the small helper that lets ADBKit reach Android over Wi-Fi: requirements, download, run, security model, API and fixes.
A web page cannot open a raw TCP connection, and an Android phone with ADB over Wi-Fi enabled listens on plain TCP (port 5555 by default). The ADBKit Wi-Fi helper (adbkit-bridge.mjs) closes that gap: a single JavaScript file that runs on your own computer and relays traffic between the ADBKit tab and the phone. This page is the reference for installing, running, securing and troubleshooting it.
How it works
ADBKit tab (browser)
│ WebSocket ws://127.0.0.1:8730/connect?host=<phone-ip>&port=5555
▼
adbkit-bridge.mjs (your computer, listening on 127.0.0.1 only)
│ plain TCP
▼
Android phone <phone-ip>:5555 (adbd)The helper does not understand ADB. It copies bytes in both directions, so the ADB handshake and the RSA key authorization still happen between ADBKit and the phone, and you still tap Allow on the phone. The helper also answers two plain HTTP requests: a health check and a network scan.
Requirements
| Item | Requirement |
|---|---|
| Computer | Any system that runs Node.js: Windows, macOS or Linux |
| Node.js | A current LTS release. The helper is developed and tested on Node.js 22 and uses only built-in modules, so there is nothing to npm install |
| Browser | Chrome or Edge on desktop, opened on the ADBKit workspace |
| Phone | ADB over TCP/IP enabled (see below), on the same Wi-Fi network as the computer |
| Network | The router must allow devices to talk to each other. "AP isolation" or "client isolation" blocks this |
Download and run
- Download the helper: adbkit-bridge.mjs. Save it anywhere, for example in your home folder.
- Open a terminal in that folder and start it:
node adbkit-bridge.mjs- You should see:
ADBKit bridge listening on ws://127.0.0.1:8730
Allowed pages: http://localhost:3000, http://127.0.0.1:3000, https://adbkit.com, https://www.adbkit.com
Leave this window open while you use Wi-Fi in ADBKit. Ctrl+C to stop.- Leave the window open. Press
Ctrl+Cto stop the helper. Nothing is installed on your computer; deleting the file removes it.
Check that it is running
Open http://127.0.0.1:8730/health in a browser tab, or run:
curl http://127.0.0.1:8730/healthThe reply is {"name":"adbkit-bridge","version":1}.
Turn on ADB over Wi-Fi on the phone
The helper reaches the phone only if the phone listens for ADB on the network.
- From ADBKit (recommended): connect the phone by USB, open the device menu, choose Add device over TCP/IP…, then press Turn on Wi-Fi debugging. ADBKit runs
adb tcpip 5555for you and shows the phone's Wi-Fi address. - With adb on a computer: run
adb tcpip 5555while the phone is connected by USB.
Classic TCP mode stays on until the phone restarts. To switch it off earlier, run adb usb with the phone connected.
Warning: while ADB over Wi-Fi is on, any device on the same network can try to reach the port. Android still asks you to approve each computer, but only use it on networks you trust and switch it off when you are done.
Connect from ADBKit
- Start the helper.
- In ADBKit, open the device menu and choose Add device over TCP/IP… to type the address (port 5555), or Scan network… to find phones automatically. On the start screen the same options are under Connect over Wi-Fi.
- Tap Allow on the phone if it asks to allow debugging from this computer.
Recent addresses are remembered in your browser so you can reconnect with one click.
Options
| Option | Effect |
|---|---|
--port <number> | Port the helper listens on. Default 8730. ADBKit currently looks for 8730, so change it only for your own development setup |
--origin <url> | Adds a web page origin that is allowed to use the helper, for example a self-hosted copy of ADBKit. Can be repeated |
ADBKIT_BRIDGE_ORIGINS | Environment variable with extra origins, separated by commas |
By default only http://localhost:3000, http://127.0.0.1:3000, https://adbkit.com and https://www.adbkit.com may use the helper.
Security model
- It listens on
127.0.0.1only, so other computers cannot reach it. - Every request must come from an allowed origin. Other web pages are refused with
403. - It connects only to loopback, private and link-local IPv4 addresses (
127.x,10.x,172.16–31.x,192.168.x,169.254.x). It cannot be used to reach the internet. - It stores nothing and writes no logs of the traffic it relays.
- ADB's own authorization is untouched: the phone still has to approve your computer's key.
How network scanning works
Scan network asks the helper to try the ADB port on every address of the /24 network of each private IPv4 interface of your computer (for example 192.168.1.1 to 192.168.1.254). It probes up to 128 addresses at a time, waits about half a second per address and returns the ones that accept a connection. The scan finds anything listening on that port, not only phones. A phone that has not turned on ADB over Wi-Fi will not appear.
Technical reference
| Endpoint | Purpose |
|---|---|
GET /health | Returns {"name":"adbkit-bridge","version":1}. Allowed from any origin |
GET /scan?port=5555 | Returns {"devices":[{"host":"192.168.1.42","port":5555}]}. Needs an allowed origin |
WebSocket /connect?host=<ip>&port=<port> | Opens a TCP connection to the phone and relays binary messages both ways |
Errors: 403 for an origin that is not allowed, 400 for a host that is not a private address or an invalid port, 502 when the phone does not accept the connection.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| "The ADBKit bridge isn't running on this computer" | The helper is not started, or something else uses port 8730 | Start node adbkit-bridge.mjs. If it prints an "address in use" error, close the other program |
| The browser asks to allow access to devices on your local network | Chrome protects the local network | Choose Allow for the ADBKit site |
| "The device didn't answer over Wi-Fi" | Different network, router client isolation, or ADB over Wi-Fi is off | Put both on the same Wi-Fi, switch off client isolation, run Turn on Wi-Fi debugging again |
| Scan finds nothing | The phone is not listening on 5555, or the computer is on a different subnet | Enable ADB over Wi-Fi; type the phone's address manually |
| It worked, then stopped after the phone restarted | Classic TCP mode resets on reboot | Turn Wi-Fi debugging on again over USB |
| "The device declined the authorization request" | The prompt on the phone was dismissed | Connect again and tap Allow |
| You need Android 11+ "Wireless debugging" with a pairing code | Not supported yet | Use the classic method above |
If the phone cannot be found at all, see Fix ADB "device busy", "unauthorized" and "no devices" errors. For the general background on ADB over Wi-Fi, read ADB over Wi-Fi: connect an Android device without a cable. When the helper is running, open the ADBKit workspace and choose Connect over Wi-Fi.