1# Remote resilience
2
3Remote attach starts with SSH bootstrap and then carries the vev session over authenticated UDP. The design is inspired by mosh's mobile-shell resilience, but vev uses its own protocol and is not compatible with mosh clients or servers.
4
5The raw UDP AEAD key is never persisted by vev; the proxy registry stores only its SHA-256 ownership fingerprint. During bootstrap, the key briefly exists in memory in the proxy, the `_udp-bootstrap` relay, the client, and associated SSH/readiness I/O and string buffers. vev promptly clears reachable key buffers after handoff on a best-effort basis. Builds made with Go 1.26 and `GOEXPERIMENT=runtimesecret` additionally protect key-handling call trees with `runtime/secret` on linux/amd64 and linux/arm64; on unsupported platforms, `runtime/secret` calls the function directly. These protections do not cover globals, goroutines started by protected calls, copies retained by I/O implementations, or key material retained in cipher state.
6
7## Operational model
8
9- SSH bootstrap starts or finds the remote UDP endpoint.
10- UDP carries normal session traffic after bootstrap. The remote proxy binds a port in a fixed range, `61000-61023` by default; `VEV_UDP_PORT_RANGE` overrides it (a range, a single port, or `0` for a random ephemeral port).
11- Named sessions remain recoverable across daemon restarts; ephemeral sessions remain recoverable only while the daemon retains them.
12- `VEV_REMOTE_TRANSPORT=stdio` keeps all traffic inside SSH when direct UDP is blocked.
13
14## Recovery states
15
16Resilience work uses these user-facing states:
17
18| State | Meaning |
19| --- | --- |
20| `connected` | a complete record or meaningful ACK progress is recent |
21| `degraded` | authenticated UDP packets still arrive, but complete-record or ACK progress is delayed |
22| `probing` | authenticated UDP packet contact is absent, so vev probes for path recovery |
23| `resuming` | a replacement transport is attaching to the same session |
24| `offline` | authenticated UDP contact remains absent; vev re-runs the SSH bootstrap and re-dials UDP with the resume token |
25| `expired` | the session or recovery window is no longer available |
26
27When a terminal is in raw mode, recovery messages appear as vev status text rather than as bytes written into the remote program's output stream.
28
29`VEV_REMOTE_TRANSPORT=stdio` is the SSH-stdio fallback: it keeps the session inside authenticated SSH when UDP is blocked or unavailable. It remains available while UDP recovery is attempted.
30
31## UDP transport health diagnostics
32
33At debug logging, UDP transport-health lines report only state, elapsed progress ages, and bounded transport counters; they do not include payloads, addresses, keys, or identities. For a real remote attempt, `scripts/debug-remote-attach.sh --udp-health user@host` stores redacted transport-health lines and Linux `ss -u -m` socket-memory counters, then prints the exact collected file paths.
34
35## Manual checks
36
37Useful scenarios for validating resilience behavior:
38
39- block and unblock the configured UDP port range;
40- move between networks or change VPN state;
41- suspend and resume the client machine;
42- retry `vev attach user@host:session` for the same named session;
43- compare logs for UDP silence, probing, SSH bootstrap failure, proxy expiry, and missing sessions.
44
45Keep hostnames, usernames, and local paths out of shared logs and screenshots.