1# Remote sessions
2
3```sh
4vev attach user@host[:session]
5```
6
7vev must be installed on the remote host. The remote daemon owns the session: it runs the shells, renders the screen, and sends only small diffs to your client. Nothing is proxied through your local daemon.
8
9## How the connection works
10
111. vev opens SSH to the host and starts a short-lived QUIC server there.
122. SSH hands back a one-time token and the server's certificate fingerprint.
133. Your client connects directly over QUIC (UDP), checks the fingerprint, and uses the token once.
14
15Terminal traffic then goes over QUIC, not SSH. The token and keys stay in memory only.
16
17If UDP is blocked, use SSH only:
18
19```sh
20VEV_REMOTE_TRANSPORT=stdio vev attach user@host
21```
22
23## What survives a network problem
24
25- The remote session and its shells keep running while you are offline.
26- The client reconnects by itself after a network change, a VPN switch, or a laptop sleep.
27- If the reconnect window has expired but the session still exists, the client opens a fresh attachment to it.
28- Several clients can attach to the same session. Each keeps its own window, tab, focus, and copy mode.
29
30## Connection states
31
32| State | Meaning |
33|---|---|
34| `connected` | Everything works. |
35| `degraded` | Packets arrive, but updates are slow. |
36| `probing` | No contact; vev is looking for a working path. |
37| `offline` | No contact for a while; vev is reconnecting. |
38| `dead` | The connection is gone for good. |
39
40States appear in the vev status bar, never inside your shell output.
41
42## Hybrid mode: local and remote together
43
44Add a host once:
45
46```sh
47vev host add user@host
48```
49
50Then the session picker (`SSP`) shows local and remote sessions in one list. Remote sessions appear as `session@host`, with tags like `down` or `broken` when they can't be opened.
51
52- Selecting a session switches to it, local or remote. `BCK` goes back to the previous one; `JRS` jumps to a recent one.
53- A remote session opened from the picker uses the remote host's environment and saved working directory.
54- `CNS` asks where to create the new session when several daemons are available.
55- Session history and the last selected tab in each session are per client and kept only while that client runs. Switching back restores that tab; choosing a specific tab overrides it. If the remembered tab was closed, vev falls back to the first tab.
56- Previews of remote sessions are cached in memory only, never written to disk.
57
58After you leave a remote, vev keeps its connection warm so going back is instant. See [warm remote transports](configuration.md#warm-remote-transports).
59
60## Timeouts
61
62| What | Limit |
63|---|---|
64| Connect to first screen | 15 s |
65| `vev cmd` result | 10 s |
66| A detached remote attachment waiting to resume | 15 min |
67
68## Upgrading
69
70Client and daemons must run the same protocol version. Upgrade vev on your machine and on every remote host together.
71
72## Debugging
73
74```sh
75VEV_LOG=debug vev attach user@host
76scripts/debug-remote-attach.sh user@host   # collects redacted connection health
77```
78
79Useful manual checks: block UDP, switch networks or VPN, suspend the laptop, then reattach to the same session.
80
81Keep hostnames, usernames, and keys out of shared logs and screenshots.