Connect a coding agent

An agent uses a cloud phone through phone-harness: the same open-source harness that drives a phone on your desk, pointed at a phone in the cloud over ADB. There is no separate integration per agent, and the agent never needs your API key.

Set up the machine the agent runs on

Once per machine — a laptop, a CI runner, a sandbox image. Works on macOS, Linux and Windows.

pip install phone-harness                       # or: uv tool install phone-harness
# adb: brew install android-platform-tools | apt install adb | winget install Google.PlatformTools
phone-harness --doctor android

# let the agent find the helpers (Claude Code shown; Codex: $CODEX_HOME/skills/phone-harness)
mkdir -p ~/.claude/skills/phone-harness
phone-harness skill > ~/.claude/skills/phone-harness/SKILL.md

phone-harness cloud login

A code and a URL print and your browser opens. Sign in — or create an account; sign-up is open and new accounts start with $5 of credit — and approve. The machine is linked to your account from then on; nothing is pasted, and the agent never sees a key.

Let the agent start the phone

That is the whole setup. The agent starts, drives and stops your phone with three commands, which the skill already teaches it:

phone-harness cloud start      # your own Android, ready in about 15 seconds; opens the live view
phone-harness <<'PY'
open_app("Settings")
print([o["text"] for o in ocr()][:10])
PY
phone-harness cloud stop       # billing stops; the phone is saved for next time

cloud start connects the phone over ADB and unlocks it itself; every helper then drives it with nothing exported. It is the same phone each time: apps and logins are kept between sessions. phone-harness cloud shows what is running and how long is left, cloud watch reopens the read-only live view, and cloud open opens the dashboard when you want to take the controls yourself — to type a password, say.

Give the agent this prompt

Use phone-harness for everything on the phone. Read `phone-harness skill` first.
Run `phone-harness cloud start` if `phone-harness cloud` shows no phone
attached, then drive it with the helpers:

phone-harness <<'PY'
open_app("Settings")
print([o["text"] for o in ocr()][:10])
PY

Tell me what you are about to do before each script and what you saw after.
Take a screenshot and describe the screen before acting. Ask before sending,
posting, buying or changing settings. Run `phone-harness cloud stop` when
we are done, and tell me if the phone expires.

One phone per agent, programmatically

For an agent service, split the work in two. An orchestrator holds an API key and never touches phones:

export API=https://api.phone-harness.com KEY=pck_…
SID=$(curl -sS -X POST $API/sessions -H "Authorization: Bearer $KEY" \
        -H "Content-Type: application/json" -d '{"timeout_seconds": 900}' | jq -r .id)
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_…","expires_at":…}

Each agent sandbox gets only host, port and code, and runs the connection at startup — no account of its own:

adb connect live.phone-harness.com:22220
adb -s live.phone-harness.com:22220 shell unlock ph_…
export ANDROID_SERIAL=live.phone-harness.com:22220
export PHONE_HARNESS_PLATFORM=android          # only needed on a Mac

It cannot reach any other phone, spend credit, or end sessions. When the agent finishes — or misbehaves — the orchestrator resets the code or ends the session; the phone’s own timeout_seconds is the backstop. Reconnecting is safe to repeat: after a dropped connection, run adb connect and unlock again with the current code.

Notes

Serial, not identity. live.phone-harness.com:22220 belongs to a phone only while its session lives; the session id is the stable name.
Reconnects need unlock again. Every adb connect is a new connection; cloud start handles this for its own phone.
Plaintext. ADB over TCP is not encrypted; do not send secrets through adb shell you would not send in the clear.
Appium / uiautomator2 / scrcpy use the same host:port as their serial or udid after the unlock.

Get started

Guides

Endpoints

Use cases

Set up the machine the agent runs on

Let the agent start the phone

Give the agent this prompt

One phone per agent, programmatically

Notes

​Set up the machine the agent runs on

​Sign in once

​Let the agent start the phone

​Give the agent this prompt

​One phone per agent, programmatically

​Notes

Set up the machine the agent runs on

Sign in once

Let the agent start the phone

Give the agent this prompt

One phone per agent, programmatically

Notes