Agent Terminal
← Blog

· By Edward, from the Agent Terminal team · 2 min read

Why do I need a desktop companion app?

Your phone is the screen and the keyboard. The terminals run on your computer, and the desktop app is what keeps them there and lets your phone in.

In short

  • On a Mac: install the desktop app and pair your phone. That is all it needs.
  • On Windows: the same, plus one setting. Windows cannot move a terminal that is already running into another app, so turn on Set as default terminal app and new terminals open in Agent Terminal, where your phone can reach them.

What the desktop app does

Agent Terminal on your phone does not run commands. Every shell runs on your Windows PC or Mac, and the desktop app is the part that:

  • Keeps your terminals running in a host process, so closing the app, or your phone losing signal, does not end them.
  • Pairs your phone by QR code.
  • Lets your phone in. Every connection is strictly funneled through, and guarded by, a single SSH gateway in the desktop app that accepts public keys only.
  • Reaches your phone away from home, as well as on a private network.

On macOS

Install the desktop app, pair your phone, and open terminals from either one. With Start the host when you log in on in Settings, your phone can reach your terminals without the app open, and the host comes back if it stops unexpectedly.

A Mac can also move a shell that is already open. Turn on Move shells from your terminal app to Agent Terminal, then press Ctrl+\ then s in a Terminal, iTerm2 or Ghostty window opened after that, and its shell moves to Agent Terminal, where your phone can reach it.

On Windows

Windows does not let one app hand a running terminal over to another: a console stays with the window it started in until it ends. Windows hands a console to a terminal app only as it starts.

So we recommend one setting. In the desktop app, open Settings → General and press Apply next to Set as default terminal app. From then on, the Command Prompt and PowerShell windows you open from the Start menu, a shortcut or the Run box open in Agent Terminal instead, and your phone can reach them. Press Undo on the same row to go back.

If you leave it off:

  • Terminals you opened outside Agent Terminal cannot be reached from your phone.
  • Terminals you open in Agent Terminal, on the PC or from your phone, can.

Either way, terminals that were already open before you turn it on stay where they are.