Troupe Docs
Browser and phone

Share your desktop app

Open your live desktop sessions on a phone with a QR code.

This works in the desktop app only.

The desktop app can share your live chats and terminals with a phone or another browser. You turn sharing on from the tool strip at the right edge of the window, then scan a QR code. The link works on any network, so your phone doesn't need to be on the same Wi-Fi as your computer.

A shared link is view-only unless you choose otherwise. On the other device you can watch your chats and terminals as they run. You can't send prompts, answer approvals, open terminals or change files from it.

To do those things from the other device too, turn on Allow full control before you start sharing. See Give the other device full control. You can also run troupe-server instead.

Before you start

Sharing uses cloudflared, a free program from Cloudflare. It creates a temporary public HTTPS address that forwards to Troupe on your computer. You don't need a Cloudflare account for this.

Troupe doesn't install cloudflared for you. Install it yourself, then make sure Troupe can find it. Troupe looks for it in this order:

  1. The path in the TROUPE_CLOUDFLARED_PATH environment variable (or the older TERMUL_CLOUDFLARED_PATH), if you set it.
  2. A cloudflared program in the same folder as the Troupe app.
  3. cloudflared in /opt/homebrew/bin and then in /usr/local/bin, where Homebrew and many manual installs put it. Troupe finds it there even when you open the app from the Dock, Finder, or an app menu, which don't pass on the PATH of your shell.
  4. cloudflared on your PATH.

Start sharing

  1. At the bottom of the tool strip on the right edge of the window, click the monitor icon (Remote terminal access). The Remote Agent Access popover opens.
  2. Optional: turn on Allow full control to let the other device prompt agents, run commands and edit files. Leave it off for a view-only link.
  3. Turn on Enable remote access.
  4. Wait a few seconds. The popover shows Starting tunnel… while cloudflared starts. Then a QR code appears.
  5. On your phone, scan the QR code with the camera. Troupe opens in the phone's browser.

To send the link to another device instead, click Copy link and paste it there.

While sharing is on, the monitor icon in the tool strip is highlighted.

Give the other device full control

With Allow full control on, anyone who opens the link can do everything you can do in the desktop app: send prompts, answer approvals, open terminals and run commands, and change files on your computer.

You choose this before you turn sharing on. While sharing is on, the switch is locked and shows the current level. To change it, turn off Enable remote access, change Allow full control, and turn sharing on again. The new link has a new address.

The link has two parts:

  • The address, for example https://<random-words>.trycloudflare.com. It is random and changes each time you turn sharing off and on.
  • An access token after #token= at the end. The token is what lets a device in.

Anyone who has the full link can watch your sessions. With Allow full control on, they can also control your computer. Share it only with your own devices.

The token stays the same each time you turn sharing on. Troupe saves it in a file named web-auth-token in the app's data folder (com.termul-manager.app). To make old links stop working, turn sharing off, delete that file, and turn sharing on again. Troupe then creates a new token.

On the phone, the browser remembers the token after the first visit. Troupe also removes it from the address bar.

Stop sharing

Open the popover again and turn off Enable remote access. Troupe stops cloudflared and the link stops working right away.

Your agents keep running in the desktop app. Turning sharing off doesn't stop any chat or terminal.

Phones that were open on the link show Host offline. See Connection status.

If the QR code doesn't appear

  • An error mentions cloudflared binary not found. Troupe can't find cloudflared. Install it, or set TROUPE_CLOUDFLARED_PATH to its full path, then restart Troupe.
  • The error says the tunnel URL was not received. cloudflared started but didn't get an address within 25 seconds. Check your internet connection and try again.
  • The popover says Tunnel disconnected. cloudflared stopped after it started. Turn Enable remote access off and on to get a new link.
  • The phone says the site can't be reached. A new address can take a few seconds to work everywhere. Wait a moment, then scan again.

On this page