Remote access with iroh: integration plan and feature naming #376

Decision (2026-09-20, maintainer-confirmed)

This issue is the plan of record for remote access. It supersedes every earlier direction recorded below, including the "no relay service" statement from #329 — that sentence was a scoping note to keep one iteration small, not a project principle. The governing text is CONTRIBUTING.md › Principles › 5.

Transport

• iroh is the only transport for native clients. It replaces the current plain HTTP/WebSocket stack rather than running beside it: the hand-rolled HTTP/1.1 reader, the plaintext WebSocket path and the parts of pairing that are bound to that transport retire once iroh carries the existing application protocol. The LAN case also goes through iroh (direct connections with local discovery); two parallel transports would mean two security models to maintain forever.
• End-to-end encrypted by construction. The "a LAN capturer can read the device token" limitation goes away with the plaintext transport.
• The browser client uses iroh's browser support, which is relay-only today (docs). Tcode adopts it as it is — experimental status is not a reason to wait (Principle 9). Superseded 2026-09-21: the browser client is direct access only and does not use iroh; remote access uses the native client. The headless HTTP entry that serves the browser bundle remains only until the browser transport lands, then retires. Superseded 2026-09-21: the browser client stays a direct-access-only HTTP/WS entry; see the implementation plan below.
• Adapt iroh streams at the existing unified host entry (RemoteServer::admit, prepared in Prepare unified native remote establishment and trusted stream admission #384). Pairing, the main stream and Preview keep one connection owner; one logical entry does not require one physical socket.

Traverse: the official discovery and relay service

Tcode will operate a service, branded Traverse, providing iroh discovery (finding a paired machine without a shared LAN) and relay fallback when hole punching fails.

• No accounts. Pairing stays a one-time code exchanged for a device token; the service never learns who a user is.
• On by default, switchable in Settings to a self-hosted instance or off.
• Never required. On a LAN or overlay, direct iroh connections give the full product without the service. Traverse only introduces devices to each other and relays ciphertext.
• Sees only ciphertext. This replaces the README's former "no cloud service" claim.
• Abuse limits without accounts: the relay only carries traffic between peers that hold each other's node id; discovery queries, pairing handshakes and relay bandwidth are rate-limited per node id and per IP, degrading to direct-only rather than refusing service; a pairing code is invalidated after five failures on the service, as locally; no SLA is promised, and a rate-limited user can switch to a self-hosted instance at any time. No traffic content is logged, no geo-blocking, and abuse is never solved by introducing accounts.
• Thresholds are implementation decisions.

Naming

Traverse is the chosen name for the service and the user-facing remote capability. "Connect", "Farfold" and "Handspan" are retired. Technical configuration stays descriptive (endpoint, relay, discovery), and the UI reports actual direct/relayed state independently of the name.

Sequence

1. iroh endpoint ownership, host identity and routing, and admission adapters at the unified entry; native clients over iroh on a LAN, direct only.
2. Discovery and relay via Traverse; self-host option; settings.
3. Browser client over iroh's browser transport; retire the headless HTTP entry. Superseded 2026-09-21: browser listener reduced to direct access; see plan.
4. Remove the plaintext transport and its tests; rewrite docs/remote.md for the new model.

Preparation is merged in #384. No iroh dependency, relay deployment or Traverse infrastructure exists yet.

Implementation plan (2026-09-21)

Code survey and iroh research are complete; no code has changed yet. Facts below were verified against iroh 1.2.0 (2026-09-09) and the current crates/remote code. The maintainer has confirmed that a full rewrite of the local implementation and UI is acceptable; no compatibility with the HTTP/WS transport, hosts.json, remote.json or existing pairings is kept. How the official Traverse instance is operated is not part of this issue.

Facts that shape the design

• crates/remote runs on smol; iroh requires tokio. The transport crate is rewritten on tokio (one runtime thread owns the Endpoint, async_channel to GPUI). crates/protocol, mux.rs, and all of crates/client (Transport, outbox, recovery, heartbeat) are transport-agnostic and stay.
• iroh 1.2.0: MSRV 1.91, MIT/Apache. TLS is raw public keys only; Connection::remote_id() is the authenticated peer identity. Hole punching is QAD-only (relay UDP 7842); STUN is gone. Connection::paths() / path_events() report direct vs relayed. The relay protocol is WebSocket over HTTPS at /relay; the relay forwards by destination EndpointId only, has no per-pair policy hook, and its rate limit is a per-connection rx token bucket. AccessControl::on_connect sees the authenticated EndpointId, URI and HTTP headers, not the peer address.
• DNS-based lookup (DnsAddressLookup) needs an authoritative DNS zone per instance and mainline DHT is off by default upstream; Traverse uses pkarr over HTTP only, which also keeps every client on one discovery path.

Identity, pairing, connection

1. Machine identity = iroh EndpointId; the existing identity_seed becomes the iroh SecretKey. host_id UUID is dropped.
2. Device identity = the device's own EndpointId (desktop and phone; persisted in the device data directory).
3. Pairing = presenting the invitation's single-use secret over ALPN tcode/pair/1 to join the machine's allow list. Maintainer decision 2026-09-21: there is no six-digit code. Since first contact is always by scanning or pasting the invitation, the link carries a 128-bit random secret instead; five-minute lifetime, single use, a new invitation replaces the previous one, all enforced on the machine only. Traverse never sees an invitation. Afterwards the device connects with ALPN tcode/1 and EndpointHooks::after_handshake rejects any EndpointId not in the list. Revocation removes the entry and closes live connections. Bearer tokens, token hashes and the /identity challenge are removed.
4. One QUIC connection per device attachment. Streams: the main NDJSON stream (protocol version 5, hello without token); one bi stream per Preview target with a CONNECT host:port / HTTP host:port first line, replacing the HTTP forward proxy and Basic auth. macOS port mapping and the Windows/Android loopback bridge translate local connections into streams.
5. Invite QR/link: tcode://pair?v=2&id=<endpoint id>&secret=<base64url>&name=<name>&traverse=<base url>&relay=<url>&addr=<ip:port>.... The UI shows the QR and a copy-link action only.

Discovery

Maintainer decision 2026-09-21: no automatic discovery. First pairing is always by invitation: scan the QR or paste the same tcode://pair?… link. The invite carries the machine id, its relay and its current direct addresses (MemoryLookup), so LAN connections work without any service; afterwards iroh keeps learning direct addresses through the relay path. Cross-network lookup via pkarr HTTP publish/resolve against every pkarr URL in the Traverse manifest, publishing relay URLs only. Update 2026-09-22: a device still needs to find a machine it is already paired with on a LAN without internet or Traverse, and recover from address changes. This is implemented on iroh's AddressLookup extension point, resolving paired ids only and with no UI: the machine advertises standard DNS-SD _tcode._udp (via mdns-sd, with PTR records and normal TTLs so system browsers see it) and binds a fixed UDP port (47420 by default, headless --port); the device tries the last successful address, then every other saved address for that machine, then a DNS-SD browse filtered to the paired id (iOS through the system NWBrowser, no multicast entitlement). Nothing else: no subnet probing, no other fallback. iroh's own mDNS crate is not used (its advertisements carry no PTR and TTL 0, invisible to DNS-SD browsers). No DNS lookup of our own, no DHT.

Traverse as a product

Traverse is one server binary, tcode-traverse (new crate crates/traverse-server, released with the existing workflow as archives and a Docker image): an embedded iroh-relay server with QAD and ACME/manual/reloading TLS, a built-in pkarr store (Ed25519 verification, 1072-byte cap, 409 on stale timestamp, per-IP rate limit, eviction of unrefreshed records), a self-describing GET /relays.json manifest, /healthz, Prometheus metrics on a private address, and an optional region lock (AccessControl implementation that reads RTT/client-IP headers only when a trusted reverse proxy is configured, and bounds far clients by a quota). Denial reasons are logged, not shown by the client. The official instance runs this same binary; there is no official-only code path.

Manifest:

{ "v": 1,
  "relays": [ { "url": "https://relay.example/", "quic_port": 7842, "region": "…" } ],
  "pkarr":  [ "https://traverse.example/pkarr/" ] }

Official instance, first release (maintainer decision 2026-09-21): the official Traverse manifest lists n0's public relays and https://dns.iroh.link/pkarr, which n0's documentation allows for production use when performance is acceptable (DNS address lookup docs). No Tcode-operated infrastructure is required for the first release. The manifest is a JSON file in the repository (crates/traverse/src/traverse_manifest.json), bundled into the client and re-fetched from the repository's raw URL with the same cache/TTL/fallback rules as the Claude model manifest (crates/agent/src/claude_manifest.rs); official and self-hosted manifests share one fetcher and one construction path. Self-hosting is supported from the same release. Because a dialer connects to whatever relay the callee's address record names, only the machine's home relay matters; any open self-hosted relay is reachable by every device without configuration on the device.

Clients fetch <base>/relays.json, build RelayMode::Custom(RelayMap) from it and one PkarrPublisher/PkarrResolver per pkarr URL (pkarr over HTTPS is the only wide-area lookup; no DNS lookup); iroh picks the home relay by measured latency. Review follow-up 2026-09-22: home_rtt_max_ms is not advertised in the manifest (the region lock is a server-side setting only). Fetch failure falls back to the cached manifest for that source; the official source additionally has the built-in copy. A self-hosted source with nothing cached starts the machine relay-less (LAN only) and applies the manifest live once it loads; it never falls back to the official manifest.

Settings: the machine has one field traverse = official | <base url> | off (tcode-headless serve --traverse …); off disables relay and pkarr, leaving mDNS and QR addresses. Devices store the Traverse URL per machine, taken from the invitation, so one phone can use an official-Traverse machine and a self-hosted one at once. Minimum self-host requirements: public TCP 443 and UDP 7842, a domain and certificate; without UDP the manifest marks the relay as relay-only.

Three wording corrections to Principle 5 follow: the relay cannot restrict forwarding to paired pairs (it forwards by destination id; unpaired peers are rejected by the endpoint after one handshake); pairing-code failures are counted on the machine, not on the service; and the browser client does not use iroh's browser support over a relay but is a direct-access-only HTTP/WS entry.

Upstream requests to n0 (Principle 9): peer address/RTT in ClientRequest, per-client limits from Access::Allow, or a per-pair forwarding hook.

Browser client (direct access only)

Maintainer decision: the browser client is for direct access only (same machine or same LAN) and does not use Traverse; remote access to a headless machine is done with the native Tcode client over iroh. The browser does not adopt iroh's wasm support. tcode-headless keeps a reduced HTTP/WS listener for the browser: static bundle, password login, /ws into the same HostMux; native pairing, /identity and the forward proxy are removed from it. It binds 127.0.0.1:47420 by default; a LAN bind is explicit and requires a password. It is plain HTTP; tunnelling it elsewhere is the user's own setup. This listener is reimplemented inside the tokio-based transport crate.

Sequence and acceptance

Release note: every device must pair again; older clients and new machines are mutually incompatible.

Status (2026-09-22): implemented in #498 (branch traverse/transport)

All phases are implemented on the branch and pass cargo fmt --check, cargo clippy --workspace --all-targets -D warnings, cargo nextest run --workspace (907 tests), cargo-machete, and the web/iOS/Android target checks:

• crates/traverse (tokio + iroh 1.2): machine/device identities, invitation-only pairing with a single-use link secret, allow list and live revocation, one QUIC connection per attachment with hello + NDJSON and Preview connect tunnels, bundled + fetched Traverse manifest (official / self-hosted / off, live relay and lookup updates), native client host and Preview adapters (native), and the browser listener on loopback by default (browser, protocol 5, password login). crates/remote is deleted.
• crates/traverse-server (tcode-traverse): self-hostable instance with relay + QAD, pkarr store, /relays.json, TLS modes, optional region lock behind a reverse proxy, metrics; release archives added to the workflow.
• Desktop hosting and Machines pages, phone/browser hosted page, connection banner with Direct/Relay; Android network-change and iOS foreground hooks; no automatic discovery.
• docs/remote.md, README and Principle 5 rewritten for this model.

2026-09-22: LAN lookup for paired machines landed (DNS-SD advertisement visible to Apple's mDNSResponder, saved addresses, fixed UDP 47420). Remaining before release: on-device Android/iOS runs (including the iOS system browser path), a relayed (off-LAN) end-to-end test, and the maintainer's decisions listed below.

Maintainer decisions still open

1. Default bind of the browser listener (loopback proposed; LAN explicit and password-protected).
2. Region-lock defaults shipped in tcode-traverse (home_rtt_max_ms, far-client quota).