SSH relay: prebuilt node-pty (#1693), and a spike on removing the remote native install

[nwparker]

Two related ideas about how the SSH relay reaches remote hosts, written up after an evidence-gathering pass. No code changes proposed here — filing for discussion.

Context: I went looking at whether we should bump the relay's Node floor (it targets node18, which is EOL), and the investigation turned up something more useful — the runtime version probably isn't our real problem.

---

Background: what the relay depends on today

config/scripts/build-relay.mjs esbuild-bundles four CJS artifacts at target: 'node18', we SCP them to the host, and launch them with the host's own node. Measured from out/relay/:

Artifact	Size
relay.js	419 KB
managed-hook-runtime.js	306 KB
relay-watcher.js	4 KB
per platform	~740 KB
all 7 platform dirs	4.4 MB

But two dependencies are not bundled — they're npm installed on the remote host and compiled against its ABI/OS:

• node-pty 1.1.0
• @parcel/watcher 2.5.6

---

Idea 1 — Ship CI-prebuilt node-pty tarballs (#1693)

This is already a TODO in the tree, and I think it's underrated. The code names it plainly:

// Why: node-pty@1.1.0 ships no Linux prebuild, so the remote npm install falls back to node-gyp rebuild and needs a C/C++ toolchain. A missing toolchain is the dominant first-connect failure on Linux relays (#1693); node-gyp surfaces it as an opaque "not found: make".
— src/main/ssh/ssh-relay-build-toolchain.ts:5

I confirmed the premise against node_modules/node-pty/prebuilds/:

darwin-arm64  darwin-x64  win32-arm64  win32-x64

No Linux prebuild. So every Linux host — the majority of SSH targets — needs make, gcc, g++, and Python before it can connect. We already probe for those tools just to turn not found: make into an actionable message, which is a workaround for the real issue.

The idea: build node-pty (and @parcel/watcher) in CI for each supported platform/arch, ship the prebuilt binding alongside the relay bundle, and skip the remote npm install entirely.

Why it's worth doing:

• Removes the failure our own code calls dominant on Linux
• Removes the C/C++ toolchain requirement — a real blocker on minimal containers, locked-down enterprise hosts, and anything where the user isn't root
• Makes first connect faster and deterministic (no compile step)

What needs thought:

• N-API version compatibility across host Node majors (this is what makes it tractable — N-API is ABI-stable, so one binding covers many Node versions)
• glibc floor for the Linux prebuilds (AGENTS.md documents 2.31 for bundled native binaries) and a musl/Alpine variant
• Which platform/arch matrix to cover, and the fallback when a host is outside it (presumably: compile as today)
• Verifying the binding actually loads before declaring success — ssh-relay-deploy.ts already does this for ConPTY on Windows

---

Idea 2 — Time-boxed spike: eliminate the remote native install entirely

The bigger prize. Two candidates, worth comparing head-to-head rather than adopting either on instinct.

(a) Bun.Terminal instead of node-pty

Bun shipped Bun.Terminal in v1.3.5 (Dec 2025), with Windows ConPTY support in v1.3.14 (May 2026). If it can replace node-pty, the remote native-addon install goes away completely — which would make Idea 1 unnecessary for the PTY half.

Worth being clear about what Bun does and doesn't solve. The intuitive pitch is "compile to a single executable, so it runs anywhere." That part is weaker than it sounds:

• It removes "does the host have Node?" but not "can the host compile node-pty?" — so on its own it leaves the dominant failure intact
• Binary size is ~64–99 MB per target vs the 740 KB we ship today — roughly 130× more bytes over an SSH channel we don't compress, and ~760 MB of per-release artifacts riding in the Electron app as extraResources
• Adds musl-vs-glibc detection, an x64 AVX2 baseline caveat, noexec $HOME, and macOS/Windows binary signing

So the case for Bun is Bun.Terminal, not packaging. That's the thing to evaluate.

The cost is real: src/relay/pty-handler.ts is ~1,613 lines, and swapping the PTY layer means requalifying spawn, resize, backpressure, signals, exit races, the reconnect/grace-period path that keeps PTYs alive across disconnects, and the Windows console-list patch. This is a project, not a build-flag change.

One genuine advantage worth noting: Bun publishes official linux-x64-musl / linux-arm64-musl compile targets, which covers the Alpine gap that bundling official Node binaries would regress.

(b) Bundle a Node runtime, VS Code Remote-SSH style

Ship our own Node to the host instead of requiring one. Removes the version-floor question permanently, and it's the closest precedent to what we're doing.

Tradeoff: larger deploy than today (though far smaller than Bun), and it does not remove the native-addon compile — so it pairs naturally with Idea 1 rather than replacing it.

---

The floor bump, and why I'm not proposing it yet

The immediate trigger was that node18 is EOL (Apr 2025) — and Node 20 is EOL too (Apr 2026), so the floor does need to move eventually. Sketch of what that would touch, if useful later:

• MIN_NODE_MAJOR in src/main/ssh/ssh-remote-node-toolchain-probe.ts — the actual connection gate
• 4 × target: 'node18' in build-relay.mjs, plus 2 in src/relay/subprocess.test.ts
• User-facing install guidance, duplicated in ssh-remote-node-install-guidance.ts and ssh-remote-node-resolution.ts (both must change or Windows users see stale text)
• A separate >= 18 probe in the WSL agent-hook path (wsl-hook-relay-launch.ts:88, plus wsl-hook-relay-manager.ts / wsl-hook-relay-deps.ts)
• The toReversed workaround in pty-handler.ts:153 and the two tests that exist solely to enforce it. (The node:sqlite requireOptional guard in external-automations-handler.ts should stay — it's a real availability guard, not a Node-18 artifact.)

On which version, if we do bump: evidence favours 22 over 24 on availability — Ubuntu 26.04 LTS ships nodejs 22.22.1 in universe, Alpine 3.21/3.22 ship 22 (24 only in 3.23), and RHEL 9's supported AppStream is 22 while 24 is still Technology Preview. Node 22 hits EOL 2027-04-30, so it's a bridge, not a resting place.

Who it would break: hosts on Node 18.x/20.x — Debian 12 (18.20.4), Ubuntu 24.04 (18.19.1), Debian 13 (20.19.2). One mitigating detail: official Node 18 binaries already require glibc 2.28, the same floor as 22 — so nobody needs an OS upgrade, just a Node install, and the failure is loud rather than silent.

But if Idea 1 or Idea 2 lands, the floor question gets easier or disappears — which is why it seems worth discussing these first rather than bumping now and again in nine months.

---

Open questions

1. Is SSH relay: pre-bundle node-pty per platform (VS Code-style) to eliminate npm install on remote #1693 worth prioritising on its own? It's the smallest change with the clearest payoff.
2. Is the Bun.Terminal spike worth a time-box, given it could remove the native-addon problem entirely — or is that too much churn in the PTY path for the benefit?
3. If we bump the floor in the meantime, is 22 the right bridge, or should we wait and go straight to a bundled runtime?

[farfromexact]

The evidence supports prioritizing the prebuilt native dependencies, especially node-pty, but the artifact key is not just operating system and CPU architecture.

Because the relay launches with the host's Node, a prebuilt binding must match the host runtime ABI as well as Linux/macOS/Windows, x64/arm64, and glibc versus musl where applicable. The artifact naming should therefore include the Node ABI or use a genuinely stable N-API target if both dependencies support it. @parcel/watcher needs the same treatment.

A practical rollout would be:

1. Build each native dependency in CI for the supported OS/arch/runtime matrix.
2. Package the native binding with the relay artifact, including a manifest of versions and hashes.
3. Select the artifact on the remote host using a strict platform/ABI check.
4. Keep the current remote npm install as a fallback for unsupported combinations.
5. Emit a clear diagnostic when no prebuilt artifact matches.

The fallback should not be removed until the matrix has been tested on minimal Linux hosts, containers, non-root users, and hosts with older glibc. Also test upgrades and rollback: a relay update must not leave an old native binding paired with a new JS bundle.

This would remove the dominant first-connect failure without hiding the underlying compatibility boundary. Shipping signed or hash-verified artifacts and recording the selected platform/runtime in the relay log would make support cases much easier to reproduce.