Connect with ADB

Every ready phone comes with an ADB endpoint and an unlock code. Connect with stock Android Platform Tools, unlock once, and it behaves like any Android device — adb shell, adb install, Appium, uiautomator2, scrcpy. No tunnel, no key setup. Anyone you give the two lines to can use the phone.

The whole workflow

export API=https://api.phone-harness.com
export KEY=YOUR_API_KEY

# 1. Provision a phone for 15 minutes. 202 = accepted; it boots in about 80 seconds.
curl -sS -X POST $API/sessions \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"timeout_seconds": 900}'
# → {"id":"abc123def456","state":"provisioning","watch_url":"https://…","expires_at":…}
export SID=abc123def456

# 2. Wait for ready. The ADB block arrives with it.
until [ "$(curl -sS $API/sessions/$SID -H "Authorization: Bearer $KEY" | jq -r .state)" = ready ]; do sleep 5; done
curl -sS $API/sessions/$SID -H "Authorization: Bearer $KEY" | jq .adb
# → {"host":"live.phone-harness.com","port":22220,"code":"ph_mfwcc5nknqaod034nwojzw0lzq","expires_at":…}

# 3. Connect and unlock.
adb connect live.phone-harness.com:22220
adb -s live.phone-harness.com:22220 shell unlock ph_mfwcc5nknqaod034nwojzw0lzq
# → unlocked

# 4. It is a phone now. phone-harness (pip install phone-harness) is the way in:
export ANDROID_SERIAL=live.phone-harness.com:22220
phone-harness <<'PY'
open_app("Settings")
tap_text("Network & internet")
print([o["text"] for o in ocr()][:10])
PY
#    …and anything else that speaks ADB works unchanged:
adb install ./myapp.apk
adb exec-out screencap -p > screen.png

# 5. End the session. ADB closes and billing stops.
curl -sS -X DELETE $API/sessions/$SID -H "Authorization: Bearer $KEY"

The 15 minutes include boot. watch_url is a live, view-only look at the same phone. Open it to watch your commands land.

Details

Locked until unlock. Before unlock, adb devices lists the phone but every command answers locked (shells) or is refused (push, pull, port forwarding). Five wrong codes drop the connection. Every adb connect is a new connection: reconnect and run unlock again. Sharing. The code is the credential. Paste the two lines to a teammate, into a coding agent’s prompt, or into CI — nothing else is needed on their side. It works until the session ends. Reset the code when it has gone further than you meant. Existing connections are closed; host and port stay the same:

curl -sS -X POST $API/sessions/$SID/adb/reset -H "Authorization: Bearer $KEY"

Turn ADB off without ending the phone, and back on:

curl -sS -X DELETE $API/sessions/$SID/adb -H "Authorization: Bearer $KEY"
curl -sS -X POST   $API/sessions/$SID/adb -H "Authorization: Bearer $KEY"

Appium and anything else that takes a serial: use live.phone-harness.com:22220 (for Appium, appium:udid) after the unlock. Plaintext. ADB over TCP is not encrypted. Do not pass secrets through adb shell that you would not send in the clear. Serial reuse. A port belongs to a phone only while its session lives; the session id is the stable identity, not the address.

Get started

Guides

Endpoints

Use cases

The whole workflow

Details

​The whole workflow

​Details

The whole workflow

Details