Live view and human handoff

A live view link opens the phone's screen in a browser, where a person can watch it and control it without an account or a key. Use it to hand the phone to a person for a step your agent can't or shouldn't take alone, such as a sign-in with a code sent to their own phone, a payment, or a consent screen. Then take the phone back when they're done.

Create a linkCopy Anchor Link

{
  "expires_in": 900
}

curl https://phonebox.dev/v1/phones/ph_7kx2m6q4v3ta/live \
  -H "Authorization: Bearer $PHONEBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expires_in": 900}'

{
  "url": "https://phonebox.dev/live/u9rVPHtjr7pzfvGcJMUZKdT_8ARJufF_tVOk5dngZ0w",
  "expires_at": "2026-09-29T11:15:00.084Z"
}

expires_in is in seconds, from 60 to 86400, which is 24 hours. The default is 3600, one hour. The phone must be ready, and the key needs the phones:control scope. The CLI's phonebox live --expires 15m and the MCP tool live_view_url create the same links.

What the person can doCopy Anchor Link

The page shows the phone's name, how long until it parks, and a view of its screen that keeps updating. The person can:

• tap, and swipe by dragging across the screen;
• type text into the focused field;
• press Back, Home and Recents.

While the page is open, it keeps the phone from parking for being idle. The session's maximum length still applies, so start the phone again to renew it if a handoff runs long. When the phone parks, the page can't control it until the phone starts again.

Anyone with the link can control the phoneCopy Anchor Link

A live view link grants full control of the phone, and of every account signed in on it, until the link expires. Treat it like a password:

• Send it only to the person who needs it, over a private channel.
• Don't post it in issues, logs, shared chats or anywhere else others can read it.
• Choose the shortest expiry that works for the task. A link can't be revoked early, so it stays valid until expires_at, or until you delete the phone.

Phonebox stores only a hash of each link and never writes the link itself to activity.

A handoff, step by stepCopy Anchor Link

1. Your agent reaches a screen it shouldn't complete itself, such as a request for a code that was sent to your user.

2. It creates a link with a short expiry and sends the URL to your user.

3. It waits for the screen that comes after the step, with a wait_for of up to 30 seconds at a time:

   Copy Text

   {
     "actions": [
       { "type": "wait_for", "target": { "text": "Inbox" }, "timeout_ms": 30000 }
     ],
     "observe": "ui"
   }

   A wait_timeout means the person isn't done yet, so the agent sends the same request again, for as long as the link lasts. The stopped batch shows the screen, so when a different screen appears, such as an error or another check, the agent decides again instead of waiting. When the link expires and the person still hasn't finished, the agent stops waiting, parks the phone and tells your user. Each request counts as activity, so the phone doesn't park while your agent waits.

4. When the expected screen appears, your agent observes and carries on.