How it works

The host

gudo-hostd runs your shells and agents. It keeps the state of every pane, so it always knows exactly what is on screen. When the app goes away, nothing stops.

On a Mac, the app includes it. On Linux, it is one static binary that runs as your user, installed with one command or from the app over SSH. It is open source, like the app.

Pairing

Pair a Phone or iPad in the Mac app, or gudo pair in any terminal, shows a QR code and a one-time ticket that expires after 10 minutes. Scan it with Gudo. Your device makes its own key, and the host adds it to its list of paired devices. From then on the host only lets in keys on that list. You can rename or remove a device at any time, in the app or with gudo devices.

The connection

Your device dials the host by its public key, over QUIC with TLS 1.3. It tries a direct path first: the same network, Tailscale, or a path punched through NAT. When none works, a relay carries the encrypted packets over HTTPS.

A relay can't read or change what it carries. It does see both ends' addresses, and when and how much data passes. You can run your own relay, or turn relays off and connect only directly. The host needs no open ports either way.

Coming back

When you open the app, it shows the last screen of each pane right away, dimmed, while it reconnects. The host then sends whatever changed, focused pane first. If you were away for long, it sends a fresh snapshot instead of replaying everything.

Agents

Start Claude Code or Codex from Gudo and they report their state: working, done, or waiting for you. Gudo does this through the agents' own hooks and settings for that run, without editing your config.

When an agent needs you, you get a notification. Approve or deny from the lock screen: your device signs the decision and the host checks it before anything runs. The host encrypts each notification for your device before it leaves, so the push service only relays it.

Just SSH

Any SSH server works without the host program. Type user@host and you are in. Sessions then last as long as the connection, like any SSH client. When you want them to keep running, choose Install Helper.

Sharing a session

You can invite someone into a session with a link. The link carries a signed grant: what they may do, for how long, and how many times it can be used. The secret part of the link sits after the #, so it never reaches a web server.