Browser SSH stuck at "Joining Tailnet" with Headscale 0.29.1 — GET /ts2021 no longer allowed

[tomas1pit]

Description

Summary

Browser SSH hangs indefinitely at "Joining Tailnet…" when using Headscale 0.29.x. The WASM client attempts GET /ts2021?X-Tailscale-Handshake=… (WebSocket upgrade), but Headscale 0.29 returns 405 Method Not Allowed with Allow: POST.

Root Cause

In Headscale 0.28, /ts2021 accepted both methods:

router.HandleFunc(ts2021UpgradePath, h.NoiseUpgradeHandler).
    Methods(http.MethodPost, http.MethodGet)

In Headscale 0.29, it was changed to POST-only:

r.Post(ts2021UpgradePath, h.NoiseUpgradeHandler)

The browser WASM cannot use POST /ts2021 (TCP long-polling) — browsers can only establish persistent bidirectional connections via WebSocket, which requires GET + Upgrade: websocket. This makes browser SSH completely broken with Headscale 0.29+, and downgrade to 0.28 is not possible due to irreversible DB migrations.

Evidence

Nginx access log during SSH attempt:

GET /key?v=125 HTTP/2.0  →  200
GET /ts2021?X-Tailscale-Handshake=AH0BAG... HTTP/1.1  →  405
GET /key?v=125 HTTP/2.0  →  200
GET /ts2021?X-Tailscale-Handshake=AH0BAG... HTTP/1.1  →  405
(repeating indefinitely)

Direct test to Headscale port 8080:

curl -H 'Upgrade: websocket' -H 'Connection: Upgrade' \
     http://127.0.0.1:8080/ts2021?X-Tailscale-Handshake=AAAA
→ HTTP/1.1 405 Method Not Allowed
   Allow: POST

Environment

• Headplane: 0.7.0-beta.4
• Headscale: 0.29.1
• All other prerequisites met: OIDC auth, agent enabled, Tailscale SSH enabled on target node

Suggested Fix

Either:

1. Coordinate with Headscale to restore GET /ts2021 support (submit a PR to juanfont/headscale)
2. Document that browser SSH requires Headscale 0.28 specifically, not "0.28 or newer"
3. Explore routing the WebSocket control-plane connection through the Headplane agent as a proxy, avoiding the direct browser→Headscale constraint

Headplane Version

0.7.0-beta.4

Headscale Version

0.29.1

[pullfrog]

Plan: Address Browser SSH incompatibility with Headscale 0.29+

Root cause (confirmed)

Headplane's Browser SSH loads a WASM build of the Tailscale client (internal/hp_ipn/, compiled to hp_ssh.wasm). In browser builds, Tailscale's control client uses control/controlhttp/client_js.go, which opens the Noise control plane as a WebSocket to /ts2021?X-Tailscale-Handshake=....

Browsers can only initiate a WebSocket via an HTTP GET with Upgrade: websocket. Headscale 0.28 accepted both GET and POST on /ts2021; Headscale 0.29 changed the route to POST only. The result is the 405 Method Not Allowed loop reported in this issue.

Proposed changes

1. Update documentation (docs/features/ssh.md)

   • Change the prerequisite from "Headscale 0.28 or newer" to "Headscale 0.28 specifically".
   • Add a "Headscale 0.29+ incompatibility" troubleshooting section explaining the /ts2021 regression and linking to the upstream Headscale issue.

2. Add a runtime version guard

   • Add a capability in app/server/headscale/api/capabilities.ts, e.g. browserSSHSupported: gte(version, "0.28.0") && !gte(version, "0.29.0").
   • In app/routes/ssh/page.tsx, check the capability in the loader before creating the pre-auth key and throw a new error (sshErrors.headscale_version_unsupported) on Headscale 0.29+.
   • Add the error to app/routes/ssh/errors.tsx and a matching docs anchor in docs/features/ssh.md.

3. Pursue the upstream fix

   • Open or comment on a Headscale issue requesting that /ts2021 accept GET again for WebSocket upgrades. This is the correct fix because Tailscale's own browser client requires it; Headplane cannot change browser WebSocket semantics.

4. Long-term fallback (only if upstream declines)

   • Route the control-plane WebSocket through the Headplane Agent. The agent, running outside the browser, can use the normal POST /ts2021 path to Headscale, and the browser can WebSocket to the agent. This is a significant architecture change and should be tracked separately.

Out of scope

Patching the vendored Tailscale source to avoid GET /ts2021 is not possible — browsers have no other way to establish a bidirectional raw socket than WebSocket, which implies GET.

Task list (5/5 completed)

• Analyze issue Browser SSH stuck at "Joining Tailnet" with Headscale 0.29.1 — GET /ts2021 no longer allowed #573 and confirm root cause
• Inspect Browser SSH / WebSSH implementation for affected code paths
• Review existing docs and version requirements for Browser SSH
• Evaluate actionable fixes and create implementation plan
• Post plan or analysis via report_progress

  ^{｜ Implement plan ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

[linear-code]

HP-550

[tale]

This is fixed upstream: juanfont/headscale#3357