docs(remote): describe udp transport selection

commit: 7035bab52f4ec26fa7a0159faba2df51d73431bc
author: brice · 3mo ago · 2026-07-06 21:22 UTC
parent: 982eec1
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

2 files · +3 -10

M README.md +2 -9


@@ -120,16 +120,9 @@ vev attach user@host
120	120		vev attach user@host:session
121	121		```
122	122
123		-	Remote attach runs `ssh user@host vev _stdio ...` under the hood, so `vev` must be installed on the remote host and reachable through your normal SSH config. Omitting `:session` opens an ephemeral remote session.
	123	+	Remote attach uses SSH to bootstrap a UDP transport by default, so `vev` must be installed on the remote host and reachable through your normal SSH config. Omitting `:session` opens an ephemeral remote session. Named sessions can resume after temporary network disconnects, such as sleep or Wi-Fi changes.
124	124
125		-	For faster reconnects, enable OpenSSH connection reuse:
126		-
127		-	```sshconfig
128		-	Host *
129		-	ControlMaster auto
130		-	ControlPath ~/.ssh/cm-%r@%h:%p
131		-	ControlPersist 10m
132		-	```
	125	+	Set `VEV_REMOTE_TRANSPORT=stdio` to use SSH stdio compatibility mode on networks where UDP is blocked. Stdio mode can work through SSH-only paths, but it may not notice sleep or Wi-Fi loss promptly.
133	126
134	127		## Terminal color
135	128

 vev attach user@host:session
 ```
-Remote attach runs `ssh user@host vev _stdio ...` under the hood, so `vev` must be installed on the remote host and reachable through your normal SSH config. Omitting `:session` opens an ephemeral remote session.
+Remote attach uses SSH to bootstrap a UDP transport by default, so `vev` must be installed on the remote host and reachable through your normal SSH config. Omitting `:session` opens an ephemeral remote session. Named sessions can resume after temporary network disconnects, such as sleep or Wi-Fi changes.
-For faster reconnects, enable OpenSSH connection reuse:
+Set `VEV_REMOTE_TRANSPORT=stdio` to use SSH stdio compatibility mode on networks where UDP is blocked. Stdio mode can work through SSH-only paths, but it may not notice sleep or Wi-Fi loss promptly.
-```sshconfig
-Host *
-    ControlMaster auto
-    ControlPath ~/.ssh/cm-%r@%h:%p
-    ControlPersist 10m
-```
 ## Terminal color

M internal/adapters/dgram/transport.go +1 -1


@@ -127,7 +127,7 @@ func (t *Transport) Close() error {
127	127		func (t *Transport) Peer() net.Addr { t.mu.Lock(); defer t.mu.Unlock(); return t.peer }
128	128
129	129		// Probe sends an authenticated datagram and waits for the peer to authenticate a
130		-	// response or for ctx to expire. It is intended for UDP bootstrap/fallback checks.
	130	+	// response or for ctx to expire. It is intended for UDP bootstrap reachability checks.
131	131		func (t *Transport) Probe(ctx context.Context) error {
132	132		id, ch, err := t.registerProbe()
133	133		if err != nil {


@@ -127,7 +127,7 @@ func (t *Transport) Close() error {
127		func (t *Transport) Peer() net.Addr { t.mu.Lock(); defer t.mu.Unlock(); return t.peer }	127		func (t *Transport) Peer() net.Addr { t.mu.Lock(); defer t.mu.Unlock(); return t.peer }
128			128
129		// Probe sends an authenticated datagram and waits for the peer to authenticate a	129		// Probe sends an authenticated datagram and waits for the peer to authenticate a
130	-	// response or for ctx to expire. It is intended for UDP bootstrap/fallback checks.	130	+	// response or for ctx to expire. It is intended for UDP bootstrap reachability checks.
131		func (t *Transport) Probe(ctx context.Context) error {	131		func (t *Transport) Probe(ctx context.Context) error {
132		id, ch, err := t.registerProbe()	132		id, ch, err := t.registerProbe()
133		if err != nil {	133		if err != nil {