Handback

OAuth redirect to localhost on a remote server: why the login hangs, and how to finish it

Updated · Jere & CO

You run a login on a box you reached over SSH: an agent, a cloud CLI, an MCP server. A link appears, you open it on your laptop, you sign in, you approve. Then the browser lands on http://localhost:54213/callback?code=… and shows “This site can’t be reached”, while the terminal on the box keeps waiting.

Nothing is broken. The login did exactly what it was built to do, on the wrong machine.

Why the redirect goes to localhost

A command-line tool has no website to receive a sign-in on. So OAuth for native apps, written down in RFC 8252, uses a loopback redirect:

  1. The tool starts a small HTTP server on the box, on 127.0.0.1 and a port it picks.
  2. It opens the provider’s sign-in page with redirect_uri=http://localhost:PORT/callback (or 127.0.0.1).
  3. After you approve, the provider sends the browser to that address, with a one-time code in the URL.
  4. The tool’s little server reads the code and swaps it for a token.

Step 3 is where it breaks. The browser runs on your laptop, and localhost always means “the machine I’m on”. The laptop has nothing on that port, so the code never reaches the box.

You can’t fix it by editing the URL to point at the box. The provider compares the redirect URI with the one the app registered; Google, for one, answers with redirect_uri_mismatch. And the tool only listens on the box’s own loopback anyway.

1. Paste the final URL back on the box

The code is in the address bar of the page that failed. The listener on the box is still waiting for it. So deliver it there:

  1. Sign in on your laptop as usual and let the browser fail on localhost.
  2. Copy the whole URL from the address bar, code and state included.
  3. On the box, while the tool is still waiting, request it:
curl 'http://localhost:54213/callback?code=…&state=…'

The terminal carries on as if the browser had got there. Be quick: these listeners often give up after a minute or two, and the code is single use. Some tools build this in: Claude Code shows a code to paste, and gcloud has a two-machine --no-browser flow.

2. Use a device code, if the tool has one

The device authorization grant (RFC 8628) was made for exactly this: the tool shows a short code and a web address, you enter the code on any device, and the tool polls the provider until you have approved. No redirect, no localhost. gh auth login uses it, and codex login --device-auth offers it. Look for --device-auth, --device-code or similar in the tool’s --help.

3. Forward the port with ssh -L

If you know the port before you sign in, make your laptop’s localhost:PORT lead to the box:

  1. Find the port: in the sign-in URL, look at the redirect_uri parameter.
  2. From your laptop, open a second connection that forwards it:
ssh -N -L 54213:localhost:54213 you@your-box
  1. Open the sign-in link on the laptop. The redirect now goes through the tunnel to the box.

-L forwards a port on your machine to an address on the far side; -N runs no command, just the forward. The catch: many tools pick a new random port on every run, so you only learn it after the link is printed, and the forward has to be up before you approve. It works best when the port is fixed, like Codex’s 1455 or a Claude Code MCP server added with --callback-port. It also doesn’t help when the browser is on a phone.

4. Let the device in your hand take the callback

Each of the three fixes above asks you to be at a laptop with a terminal open, and to act within the timeout. If the login started while you were away from the box, or you’d rather finish it on your phone, you need something that catches the link on the box and carries the callback back on its own. That’s what Handback does.

Already stranded? The free Engine also has handback deliver '<callback URL>', which is the curl from fix 1 with the port parsed for you.

The permanent fix

Handback does the port forward for you, every time, without knowing the port in advance. The free Engine on the box catches the sign-in link the tool opens (through $BROWSER and xdg-open on Linux, or Engine mode in the Handback app on a Mac), reads the redirect_uri, and hands the link to the iPhone, iPad or Mac in your hand. The app binds that port on your device and tunnels the callback back to the box, so the login finishes where it started. Your machines talk directly, over Tailscale or a network you trust; there's no relay and no account. On an iPhone the app receives while it's on screen, and 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.