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, register the host with SSH only:
18
19```sh
20vev host add --transport ssh user@host
21```
22
23The transport is fixed when the host is added (`quic` by default). To switch, run `vev host rm user@host`, then add it again with the other `--transport`.
24
25## What survives a network problem
26
27- The remote session and its shells keep running while you are offline.
28- The client reconnects by itself after a network change, a VPN switch, or a laptop sleep, and keeps retrying for up to 15 minutes of outage before it returns to the picker. Press Ctrl-C or Esc while it reconnects to give up and return to the picker.
29- A stalled link does not block the client loop. Keys typed while the link stalls or reconnects are kept and sent in order once it recovers. Keys vev had not yet sent when the link dropped are replayed to the resumed session; keys already in flight at the drop may be lost.
30- If the reconnect window has expired but the session still exists, the client opens a fresh attachment to it.
31- Several clients can attach to the same session. Each keeps its own window, tab, focus, and copy mode.
32
33The command palette is rendered by the remote daemon, so opening it needs a working link. A client-owned session picker that is already open remains locally interactive during an outage.
34
35## Typing on a slow link
36
37On remote sessions vev shows what you type before the server answers, like mosh. When the round trip exceeds about 60 ms, typed characters and backspace appear at once on the cursor line, including in the command palette, rename prompts, and copy search. Above about 160 ms they are underlined until the server confirms them. A wrong guess, such as a password prompt that echoes nothing, is erased when the server answers. Set `echo.predict = always` or `never` to change this; see [configuration](configuration.md).
38
39## Connection states
40
41| What you see | Meaning |
42|---|---|
43| The session | The link works. |
44| `Connecting to session…` | vev is opening a session or reconnecting a dropped link, and keeps your keys. Switching to a running local session shows it only after 200 ms. |
45| The picker with an error | The session could not be reached again, or you cancelled. |
46
47vev does not yet report a slow (`degraded`) link separately. Connection notices never appear inside your shell output.
48
49## Hybrid mode: local and remote together
50
51Add a host once:
52
53```sh
54vev host add user@host
55```
56
57Then 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.
58
59- Selecting a session switches to it, local or remote. `BCK` goes back to the previous one; `JRS` jumps to a recent one.
60- Switching between sessions on the same daemon (two local sessions, or two sessions on the same host) reuses the live attachment, so there is no reconnect.
61- A remote session opened from the picker uses the remote host's environment and saved working directory.
62- `CNS` asks where to create the new session when several daemons are available.
63- 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.
64- Previews of remote sessions are cached in memory only, never written to disk.
65
66After you leave a remote, vev keeps its connection warm so going back is instant. See [warm remote transports](configuration.md#warm-remote-transports).
67
68## Timeouts
69
70| What | Limit |
71|---|---|
72| Connect to first screen | 15 s |
73| `vev cmd` result | 10 s |
74| A detached remote attachment waiting to resume | 15 min |
75
76## Upgrading
77
78Client and daemons must run the same protocol version. Upgrade vev on your machine and on every remote host together.
79
80## Debugging
81
82```sh
83VEV_LOG=debug vev attach user@host
84scripts/debug-remote-attach.sh user@host   # collects redacted connection health
85```
86
87Useful manual checks: block UDP, switch networks or VPN, suspend the laptop, then reattach to the same session. For isolated QUIC/SSH impairment and real Wayland terminal captures, see the [visual resilience harness](../scripts/remote-resilience-harness/README.md).
88
89Keep hostnames, usernames, and keys out of shared logs and screenshots.