Handback

Open a link from an SSH session on your phone

Updated · Jere & CO

You’re in an SSH session, or an agent is running on a box for you, and something wants you to open a link: a sign-in, a dashboard, a pull request, a “click here to authorize”. It tries to open a browser, and you see nothing. The browser it reached for is on the box.

Command-line tools don’t know where you are. They ask the machine they run on to open the URL, usually one of three ways:

  • $BROWSER. A long-standing convention: if the variable is set, run it with the URL. Python’s webbrowser module tries it first; the GitHub CLI reads GH_BROWSER, then BROWSER.
  • xdg-open on Linux. It opens the URL in the user’s preferred browser, and its manual says it’s for use inside a desktop session only. On a headless server there isn’t one.
  • open on macOS. SSH into a Mac and run open https://example.com: it opens on that Mac’s screen, not yours.

When none of those finds a graphical browser, results vary. Some tools just print the URL. Python’s webbrowser may fall back to a text-mode browser like lynx or w3m, and then, per its docs, the calling process blocks until you quit that browser, which looks a lot like a hung login.

1. Copy it by hand

The plainest route: find the URL in the terminal output, select it, paste it into your phone. Long sign-in URLs wrap across lines and break when clicked; widen the terminal until the URL fits on one line, or look for a “print the URL” flag in the tool (--no-launch-browser in gcloud, claude auth login in Claude Code). Getting it from a laptop terminal onto a phone is the annoying part.

Your phone’s camera reads QR codes, and qrencode can draw one in the terminal. Make a tiny “browser” that does that:

  1. Install qrencode from your distribution’s packages.
  2. Save this as ~/bin/qr-browser and make it executable (chmod +x ~/bin/qr-browser):
#!/bin/sh
# A $BROWSER for a machine you can't see: print the link and a QR code.
printf '%s\n' "$1"
qrencode -t ansiutf8 -o - "$1"
  1. Point tools at it, in your shell profile on the box:
export BROWSER="$HOME/bin/qr-browser"
  1. Next time a tool opens a link, a QR code appears in the terminal. Scan it.

Two limits. The QR only shows if the tool’s output reaches your terminal, so it’s no help for an agent running in the background. And if the link is a sign-in that redirects to localhost, the phone signs in and then tries to reach localhost on the phone; the login on the box never hears about it. OAuth redirect to localhost on a remote server explains that one.

3. Use the tool’s no-browser mode

Many CLIs have a flow made for this: a device code you enter on any device (gh auth login, codex login --device-auth), or a code to paste back (Claude Code). Those work from a phone without any of the above. The guides for gh, Codex, Claude Code and gcloud list them.

What a real fix needs

A QR script gets you most of the way for plain links. What it can’t do is reach you when you’re not watching the terminal, keep a record of what the box opened, or complete a sign-in whose callback lives on the box.

The permanent fix

Handback is that $BROWSER script, finished. The free Engine on the box installs a $BROWSER shim (and, on Linux, an xdg-open entry; on a headless Mac, a default-browser helper), catches every link a terminal or agent opens, and hands it to the Handback app on your iPhone, iPad or Mac. You get the link with the machine and the time, a history of everything the box opened, and for sign-ins that redirect to localhost, a tunnel from your device back to the box, so the login completes on the phone. On a Mac you work on, Engine mode in the app does it without the command-line Engine. The iPhone app receives while it's on screen; links that arrive meanwhile wait on the box for 24 hours.

$7.99 / €7.99 · Mac, iPhone & iPad, one purchase

Sources

Every flag above was checked against these on 15 October 2026.