ADB KIT

GuidePublished: 7 min read

ADBKit Agent: Install, Run, Security and Troubleshooting

Reference for the ADBKit agent, the small program that lets the browser reach Android over Wi-Fi: one-line install, Node option, capabilities, security and fixes.

A web page cannot open a raw TCP socket, browse the local network with mDNS, or present a TLS client certificate. Android's Wi-Fi debugging needs all three. The ADBKit agent is a small program that runs on your own computer and does those things for the ADBKit tab. This page is the reference: how to start it, what each version can do, how it is secured and how to fix it when the tab cannot find it.

USB needs no agent. You only need it for ADB over Wi-Fi and Wireless debugging.

How it works

ADBKit tab (browser)
   │  HTTP + WebSocket  127.0.0.1:8730
   ▼
ADBKit agent  (your computer, loopback only)
   │  TCP / mDNS / TLS
   ▼
Android phone  <phone-ip>:<port>   (adbd)

The agent is a relay. It does not read, store or upload what passes through it, and the ADBKit service never sees your device data. For classic adb tcpip connections the browser still performs the ADB handshake itself and you tap Allow on the phone. For Wireless debugging the agent holds its own key, pairs it with the phone once and then connects over TLS on the browser's behalf.

Three ways to start the agent

macOS and Linux:

curl -fsSL https://adbkit.com/install.sh | sh

Windows (PowerShell):

irm https://adbkit.com/install.ps1 | iex

The script detects your system, downloads the matching binary from adbkit.com, verifies its SHA-256 checksum, saves it to ~/.adbkit/bin (on Windows %LOCALAPPDATA%\adbkit\bin) and runs it in the foreground. It needs no administrator rights, does not edit your PATH and sends no telemetry. Press Ctrl+C to stop the agent.

Useful settings:

SettingEffect
ADBKIT_NO_RUN=1Install only, do not start the agent
--port 8730Port to listen on: `curl -fsSL https://adbkit.com/install.sh \sh -s -- --port 8730`

If the binary cannot be downloaded and you have Node.js 18 or newer, the installer falls back to the Node edition (below) and tells you that pairing is not available. If you would rather read a script before running it, open install.sh or install.ps1 first. The header comment lists exactly what it does.

2. The Node edition

If you already have Node.js 18 or newer, download adbkit-bridge.mjs and run:

node adbkit-bridge.mjs

It uses only built-in Node modules, so nothing is installed. Run node adbkit-bridge.mjs --help for the options. This edition supports classic adb tcpip connections and finds Wireless debugging devices on the network, but it cannot pair them.

3. Download the binary yourself

Download adbkit-agent_<os>_<arch> (.exe on Windows) and checksums.txt from the download page, compare the SHA-256 of the file with the line in checksums.txt, make it executable (chmod +x) and run it. On macOS, if Gatekeeper blocks it, see the troubleshooting table.

What each version supports

CapabilityGo binary (installer)Node edition
tcpip: relay and scan for adb tcpip devices (port 5555)YesYes
mdns: find Wireless debugging devices on the networkYesYes
pair: pair with the 6-digit pairing code (Android 11+)YesNo
tls: connect to a paired Wireless debugging deviceYesNo
Needs a runtime installedNoNode.js 18+

In short: for the classic USB-then-Wi-Fi method either version works. For Android 11+ Wireless debugging with a pairing code, use the Go binary. The step-by-step guide is Connect Android with Wireless debugging from the browser. To choose between the two methods, read adb tcpip vs Wireless debugging.

How ADBKit detects the agent

When you open Connect over Wi-Fi, the page requests http://127.0.0.1:8730/health. The reply tells it three things: the agent's version, its runtime (go or node) and its capabilities. ADBKit then shows only the steps your agent can do, and says plainly when something is missing, for example "this agent cannot pair". If nothing answers, the page shows how to start the agent. If something answers but refuses the page's origin, it says the origin is blocked.

You can check by hand:

curl http://127.0.0.1:8730/health

Security model

  • It listens on 127.0.0.1 only, so other computers cannot reach it.
  • Only allowed web pages can use it: https://adbkit.com, https://www.adbkit.com, http://localhost:3000 and http://127.0.0.1:3000. Other pages get 403. Only the health check is open, so a page can tell "not running" from "blocked".
  • It connects only to loopback, private and link-local addresses (127.x, 10.x, 172.16-31.x, 192.168.x, 169.254.x, .local). It cannot be used to reach the internet.
  • The Go agent stores one thing on disk, in ~/.adbkit/: its own key used for Wireless debugging, plus the names of paired devices. Revoke it on the phone under Wireless debugging, Paired devices. The Node edition stores nothing.
  • Nothing is logged about the traffic it relays, and nothing is sent to ADBKit.

Ports, flags and environment

OptionEffect
--port <number>Listening port. Default 8730. ADBKit looks for 8730, so change it only for your own setup
--origin <url>Allow another web page origin, for example a self-hosted copy of ADBKit. Repeatable
ADBKIT_BRIDGE_ORIGINSExtra allowed origins, separated by commas
--helpPrint options and capabilities

Endpoints

EndpointPurpose
GET /healthName, version, protocol, runtime and capabilities. Open to any origin
GET /scan?port=5555Hosts on your local /24 networks that accept connections on that port
GET /discover?timeout=3000mDNS browse for _adb-tls-connect and _adb-tls-pairing services
POST /pairPair with a 6-digit code (Go binary only, the Node edition answers 501)
WebSocket /connect?host=&port=Relay to the phone, tls=1 for Wireless debugging (Go binary only)

Troubleshooting

SymptomLikely causeFix
ADBKit says the agent is not runningNothing is listening on port 8730Run the installer or node adbkit-bridge.mjs and keep the window open. If it prints "address in use", close the other program or pass --port
ADBKit says the agent blocked this pageYou opened ADBKit from an origin that is not allowed (a self-hosted copy, another port)Restart the agent with --origin https://your-site.example
Chrome asks to allow access to devices on your local networkChrome protects the local networkChoose Allow for the ADBKit site
The agent starts, then the browser still cannot reach itA firewall, VPN or security tool blocks loopback or the appAllow adbkit-agent through the firewall for private networks, or pause the VPN to test
Windows says "Windows protected your PC" or antivirus quarantines the fileAn unsigned new download is flaggedVerify the checksum, then choose More info, Run anyway, or add an exclusion for %LOCALAPPDATA%\adbkit\bin. If your antivirus deleted it, run the installer again
macOS says the app cannot be opened because the developer cannot be verifiedGatekeeper quarantine on a downloaded binaryThe installer clears it. For a manual download run xattr -d com.apple.quarantine adbkit-agent, or allow it under System Settings, Privacy & Security
The phone is not foundDifferent network, or AP/client isolation on the routerPut both on the same Wi-Fi, turn off "AP isolation" or "client isolation", avoid guest networks
Scan finds nothingThe phone is not listening on 5555Turn on Wi-Fi debugging over USB first, or type the address manually
Pairing is unavailableYou are running the Node editionInstall the Go binary with the one-line installer
It worked, then stopped after a rebootClassic TCP mode resets on rebootTurn it on again over USB, or switch to Wireless debugging

If the phone cannot be found even over USB, see Fix ADB "device busy", "unauthorized" and "no devices" errors. When the agent is running, open the ADBKit workspace and choose Connect over Wi-Fi.