> For the complete documentation index, see [llms.txt](https://docs.gotempest.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gotempest.app/collaboration-and-handoff/handoff-live-collaboration.md).

# Handoff — Pick Up a Session Anywhere, or Share It

Pick up a terminal session from your desktop on your phone, or invite a colleague into the one you are working in — live, in the same terminal, and end-to-end encrypted.

A terminal session in Tempest is not tied to the window it was opened in. **Handoff** lists the sessions running in Tempest on your other devices and lets you step straight into one — the way `tmux attach` picks a session back up, except you don't have to be on that machine, and there is nothing to install on the server.

The same mechanism shares a session with someone else. Two people in one session see the same screen and the same output, and either can type — like two people in one document, except the document is a live shell.

## Pick up your own session on another device

1. Sign in to your Tempest account on both devices.
2. On the desktop, turn on **Settings → General → Collaboration → Auto-share with my other devices**. From then on, every terminal tab you open is available to your own devices.
3. On the phone, open the **Handoff** tab. The sessions running on your desktop are listed by name, with the machine they are on.
4. Tap one. You are in that terminal, at the line it is on.

The session keeps running where it started. Leaving it on the phone doesn't close it, and you can walk back to the desktop and carry on — nothing is copied over and nothing has to be retyped.

{% hint style="info" %}
Nobody else gets in this way. Auto-share makes a session reachable by *your own signed-in devices* only; a colleague needs the invite below.
{% endhint %}

## Invite a colleague into a session

For a dedicated guide to sharing modes, editing permissions and co-hosts, see [Collab — Share a Live Terminal with Your Team](/collaboration-and-handoff/collab-live-terminal-sharing.md).

Sharing starts on the desktop, from the session you are already working in:

1. Open the session's tab and click **Collaborate** (the people icon in the tab toolbar).
2. Choose how people get in:
   * **Invite by email** — the person signs in to Tempest with that address and the session appears in their Handoff tab.
   * **Invite link** — anyone holding the link can watch. Send the link exactly as it is copied; the part after `#` is what decrypts the session, and a chat app that trims it hands over a link that cannot open.
3. They join — from their **Handoff** tab, or by pasting the link into **+** in that tab's header.

Everyone in the session sees the same screen, including what the others type. There is a chat panel alongside the terminal for the sentence that doesn't belong in the shell.

## Watching, typing, and removing people

Tap the chevron on a session row to see who is in it.

* **View-only** — invite someone as a viewer, or make them one later. They see everything and can type nothing, which is the setting for a demo or a customer-facing walkthrough.
* **Take the keyboard** — anyone who can write may type at any time; Tempest shows who is typing so you are not fighting over the prompt.
* **Remove** — take someone out of the session. They lose the screen immediately.
* **Stop sharing** — select **Restricted — only me** in the desktop sharing dialog and the session is yours alone again, still running.

## Nobody needs access to the server

The people you invite never touch the machine you are working on. Their Tempest talks to the Tempest server, and the screen comes from your device — so a colleague with no VPN, no SSH key, no account on the box, and no firewall exception can still watch the session and type in it. The same goes for your own phone picking up a desktop session: it needs the internet and nothing else, not a route into the network the server sits behind.

## What everyone needs

* **A Tempest account, signed in on the same Tempest server.** The hosted service and each self-hosted Tempest server keep their own accounts, so everyone in one session — you, your other devices, the people you invite — has to be signed in to the *same* one. An account on a different server cannot see or join the session.
* **Tempest Pro on the sharing side.** Joining a session you were invited to does not require Pro.
* **The full invite link**, `#` fragment included, for link invites.

## End-to-end encryption

The session is encrypted on the device that hosts it and decrypted on the devices that joined it. What travels between them goes through a relay that only ever sees ciphertext — the key is handed to the people you invited and to your own devices, never to the server, so no Tempest server (hosted or self-hosted) can read what is on the screen.

The same is true of the chat that runs alongside the session, and of an invite link: the key rides in the `#` fragment, which browsers and apps never send to the server.

## Tips

* Start a long build on the desktop, turn on auto-share, and check on it from the phone on the train — the build is still running on the same machine, with the same environment, not restarted somewhere else.
* Pair on an incident: the person with the access shares the session, everyone else joins view-only, and the one who knows the fix is given the keyboard for a minute.
* Sessions listed in Handoff are live ones. A session that ended is gone from the list — use [Snippets](/ai-and-automation/snippets-scheduled-runs.md) for the commands you want to run again later.

## Use Handoff from the CLI

The `tempest` CLI joins the same collaboration rooms. Sign in to the same account/server and unlock the vault, then list and join an active session:

```bash
tempest login
tempest unlock
tempest collab list
tempest collab join ROOM_ID --read-only
```

Omit `--read-only` to send keyboard input if your room permissions allow it. To share a new local shell from the CLI, use `tempest collab host --title "Shared shell"`; it prints the room ID. The host must remain running. The CLI does not create invite links or email invitations, and some rooms shared from another account must be joined in the app.

See [Tempest CLI — Collaboration](/cli/tempest-cli.md#collaborate-from-the-terminal) for hosting, joining, ending rooms and current limits.

## See also

* [Tempest Push Notifications](/terminal-and-operations/tempest-push-notifications.md) — get told on your phone when a scheduled run fails
* [End-to-End Encryption (E2EE)](/accounts-vaults-and-privacy/end-to-end-encryption.md) — how Tempest wraps keys for your account
* [Self-Hosted Tempest Server](/self-hosting-and-web-mode/self-hosted-tempest-server.md) — running the server your team signs in to