Unstuck Docs GitHub

Unstuck docs

Unstuck is human takeover for AI browser agents. When your agent hits a CAPTCHA, a login wall, a 2FA prompt or a page it can't make sense of, Unstuck pauses it, sends a person a link, lets them work the live browser from their phone, and hands control back.

How a takeover works

  1. Your agent asks for help with one call: takeover(page, { reason }) in code, or the request_human_takeover MCP tool.
  2. A person gets a link. You decide how it reaches them: print it, message it, email it.
  3. They solve it live in the real browser: tap, type, scroll. Your agent waits.
  4. Your agent carries on. The call returns resolved, cancelled (they tapped Can't solve), timed_out or failed.
How a takeover works: 1. your agent hits a CAPTCHA and calls takeover; 2. a person gets a link on their phone; 3. they solve it in the live browser and tap Done; 4. your agent carries on in the same page and session.

Pick your stack

Requirements: supported systems, Node.js and Python versions, and browsers.

Local or Cloud

Where the link works What you set
Local (default) on your own machine nothing
Unstuck Cloud any phone, from anywhere UNSTUCK_API_KEY=uk_live_… from your dashboard
Your own relay any phone, through your server UNSTUCK_RELAY_URL and UNSTUCK_AGENT_KEY: see Self-host the relay

With Unstuck Cloud, the first 100 takeovers each month are free. A self-hosted relay is free to run, without Cloud's phone alerts and dashboard.

Private by design

Each link carries a single-use token and a fresh encryption key in the part of the URL that never reaches a server. The screen, taps and typing are encrypted end to end between your agent and the person; Unstuck Cloud only relays data it can't read. One person at a time can hold a takeover, and the audit log records states, never what was typed. The page connects only when the person taps Start takeover, so a chat app's link preview or an email scanner that opens the link never uses it up, never sees the screen and is never charged.

The person can only use the page you hand them: the tab can't leave that page's site, so your browser's other logins stay out of reach. With Unstuck Cloud, the page they open comes from its own address, view.unstuck.sh, not from the relay. It is the open-source viewer, pinned to your engine's version, and its published checksums let anyone confirm it matches the source.