HTTP API to control an iPhone from code

  your script ──HTTPS, API token──> ghosthand.dev ──WebSocket the Mac opened──> ghosthand daemon ──USB──────> screenshots, OCR
  (any computer)  /macs/studio/v1/...                                                          └─Bluetooth─> taps, swipes, typing

12ghosthand tunnel url                          # https://ghosthand.dev/macs/studio
ghosthand tunnel url --new-token             # prints export GHOSTHAND_URL=... and export GHOSTHAND_TOKEN=...

# 1. take the iPhone
curl "$GHOSTHAND_URL/v1/leases" -H "Authorization: Bearer $GHOSTHAND_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"reason":"reply to Anna in Messages","label":"nightly-script"}'
# {"id":"studio:42","device":"7EF219AD-...","deviceName":"Tommy's iPhone",...}  (42 works too on this URL)

# 2. read the screen
curl "$GHOSTHAND_URL/v1/leases/42/text" -H "Authorization: Bearer $GHOSTHAND_TOKEN"
curl -o screen.png "$GHOSTHAND_URL/v1/leases/42/screenshot" -H "Authorization: Bearer $GHOSTHAND_TOKEN"

# 3. tap a button by its text, and get the new screen text in the same call
curl "$GHOSTHAND_URL/v1/leases/42/tap?screentext=true" -H "Authorization: Bearer $GHOSTHAND_TOKEN" \
  -H 'content-type: application/json' -d '{"text":"Messages"}'

# 4. give the iPhone back
curl -X DELETE "$GHOSTHAND_URL/v1/leases/42" -H "Authorization: Bearer $GHOSTHAND_TOKEN"

const url = process.env.GHOSTHAND_URL!
const headers = { authorization: `Bearer ${process.env.GHOSTHAND_TOKEN}`, 'content-type': 'application/json' }

const lease = await fetch(`${url}/v1/leases`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ reason: 'check the inbox', label: 'inbox-script' }),
}).then((r) => r.json())

try {
  const tap = await fetch(`${url}/v1/leases/${lease.id}/tap?screentext=true`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ text: 'Mail' }),
  }).then((r) => r.json())
  console.log(tap.screen)
} finally {
  await fetch(`${url}/v1/leases/${lease.id}`, { method: 'DELETE', headers })
}

12ghosthand tunnel url --new-token --name ci    # create; the id goes to stderr
ghosthand tunnel revoke <id>                  # scripts that use it get 401 at once

12curl https://ghosthand.dev/macs -H "Authorization: Bearer $GHOSTHAND_TOKEN"
# {"macs":[{"slug":"studio","name":"Studio","online":true},{"slug":"laptop","name":"Laptop","online":false}]}

  POST /v1/leases ──> { "id": "42" }
        │
        v
  /v1/leases/42/screenshot, /text, /tap, /type, ...   (each call resets the idle timer)
        │
        v
  DELETE /v1/leases/42      or 600 s without a call ──> iPhone free for the next client

12curl "$GHOSTHAND_URL/v1/leases/42/tap?waitText=About&screentext=true" \
  -H "Authorization: Bearer $GHOSTHAND_TOKEN" -H 'content-type: application/json' -d '{"text":"General"}'

123curl -N "$GHOSTHAND_URL/v1/leases/42/tap" -H "Authorization: Bearer $GHOSTHAND_TOKEN" \
  -H 'accept: text/event-stream' -H 'content-type: application/json' \
  -d '{"x":207,"y":448}'

12345event: log
data: {"message":"checking Bluetooth device 1A2B3C4D by moving its pointer"}

event: result
data: {"message":"tapped 207,448","logs":["checking Bluetooth device 1A2B3C4D by moving its pointer"]}

123456{
  "code": "device-locked",
  "title": "iPhone locked",
  "status": 409,
  "detail": "Tommy's iPhone is locked. Unlock it before tapping text"
}

1curl "$GHOSTHAND_URL/v1/openapi.yaml" -H "Authorization: Bearer $GHOSTHAND_TOKEN" > ghosthand.yaml