How to use ReTerm

ReTerm lets you run a terminal program on your own machine and then watch it or control it from a browser. You start the program with the reterm command. On your machine the program works exactly as usual. In the browser, at app.reterm.dev, you see the same screen, and you can take over the keyboard when you need to.

Setup has four steps, and you do the first three only once per machine:

Install the reterm command.
Sign in to the web app.
Connect your terminal to your account with reterm --login.
Start any program with reterm <program>. The program appears in the web app.

Install

On macOS or Linux:

curl -fsSL https://reterm.dev/install.sh | sh

On Windows (PowerShell):

irm https://reterm.dev/install.ps1 | iex

You can also download the binary for your platform from the Get started section.

Sign in to the web app

Open app.reterm.dev and click Sign in with SSO. You stay signed in until you choose Disconnect in the menu (the ☰ button in the top-right corner).

Connect your terminal

On the machine where your programs run, run:

reterm --login

The command prints a link and a code, for example:

to sign in, open https://app.reterm.dev/activate?code=WXYZ-4321
code WXYZ-4321 — waiting for approval…

Open the link in a browser where you are signed in to the web app. Check that the machine name is yours, then click Approve. The terminal prints signed in; credential cached and exits.

You do this once per machine. To sign the machine out, run reterm --logout.

Start a session

Put reterm in front of the command you want to run:

reterm bash
reterm vim notes.txt
reterm claude

The program starts in your terminal as usual. It also appears in the session list on the left of the web app, grouped by machine. Each session has a name in the form program@machine/id, for example vim@laptop/7k2p.

To see the name of a session in your terminal, press Ctrl-B, then i.

When the program exits, the session ends and leaves the list.

Useful options:

Option	What it does
`--name <name>`	Sets the session name instead of the generated one.
`--machine-name <name>`	Sets the machine part of the name.
`--pass`	Encrypts the session end to end. See below.

If ReTerm cannot be reached, the program still runs locally. reterm keeps trying to connect in the background.

Encrypted sessions

With --pass, reterm asks you for a password before the program starts. The server then sees only encrypted data. In the browser the session shows as locked: enter the same password and click Unlock to see it. The password is never saved, and share links are not available for an encrypted session.

Control a session from the browser

Click a session in the list to open it in a tab. You see the live screen, but you cannot type yet. The label on the session tells you who holds the keyboard:

Label	Meaning
HOST	Your machine's terminal has the keyboard. The browser only shows the screen.
LIVE	This browser tab has the keyboard and controls the program.
TAKEN	Another browser tab has the keyboard.
ENDED	The program has exited.

Take control: click Take control. The program resizes to the browser window. Your machine's terminal now only shows the screen, with a status line at the bottom: Remote controlled — press Esc Esc to recover.
Give control back from the browser: click Release control.
Take control back at your machine: press Esc twice, quickly, in the terminal. This always works, even if the browser or the network is gone.

If the browser or the network disconnects, control returns to your machine automatically. The program keeps running.

The toolbar also has buttons for fullscreen, zoom, Session details (program, machine, start directory, start time), and Who's watching.

The agent dot

When the session runs a coding agent (for example Claude Code or Codex), a small dot on the session shows the agent's state: working, needs you (it is waiting for your answer), or idle. Hover over the dot to read the state.

Share a session

You can let another person watch a session. Viewers see the screen but can never type.

Open the session and click Who's watching.
Under Links, enter a name for the link and click Create.
Click Copy link and send the link to the other person. The link is shown only once.
The other person opens the link (no account needed) and asks to watch. They can add a short message.
The request appears under Knocking. Click Accept or Reject.

People who are watching appear under Watching. To remove one, click Kick viewer. To stop a link from working, click Revoke link.

Troubleshooting

My session does not appear in the list. Check that you ran reterm --login on that machine and approved it with the same account you use in the web app. If reterm says you are not logged in, run reterm --login again.

I am locked out of my program at the terminal. The browser has control. Press Esc twice, quickly.

The web app asks me to sign in again. Your browser login expired. Sign in again; your sessions are still running.