Vite hot reload fails over SSH port forwarding
You run npm run dev on a server or a VM and forward a port to your laptop with ssh -L. The page loads, but edits never show up. Or the page loads without its styles and scripts. The browser console says [vite] failed to connect to websocket, or [vite] server connection lost. Polling for restart..., or the page is replaced by Blocked request. This host ("…") is not allowed.
The first two mean the browser is asking for an address the forward does not cover. Which address depends on whether Vite serves the page itself or sits beside a backend. The third means the forward works: the request reached Vite, and Vite refused the name you used, which server.allowedHosts fixes.
Why it happens
Section titled “Why it happens”Vite’s hot reload client opens a WebSocket to the host and port its own script came from, unless server.ws says otherwise (server.hmr in older Vite). So hot reload works wherever the scripts load, and fails wherever they do not. If your config sets a separate WebSocket port, such as server.ws.clientPort, forward that port too.
Vite serves the page
Section titled “Vite serves the page”A plain Vite app, or a framework built on it, serves the page, its scripts and the hot reload socket from one port. Forward that port and the browser reaches all three:
ssh -L 5173:localhost:5173 myserverOpen http://localhost:5173 and hot reload works. Two things still break it:
- Opening it by another name. Vite checks the
Hostheader and refuses names it does not know, the page included, withBlocked request. This host ("…") is not allowed.localhost,*.localhostnames and IP addresses are always allowed. For any other name, add it toserver.allowedHostsinvite.config.js. - The connection dropping. When
sshexits, so does the forward. The console saysserver connection lost, and nothing reloads until you runssh -Lagain.
Vite sits beside a backend
Section titled “Vite sits beside a backend”Laravel, Rails, Django and other backends render the HTML themselves, and the page loads its scripts from the Vite dev server on a second port, at an address such as http://localhost:5173. In Laravel, laravel-vite-plugin writes that address to public/hot when npm run dev starts, and every script tag on the page uses it.
Forwarding only the backend’s port loads the HTML, and then the scripts fail, because your browser asks for localhost:5173 on your laptop and nothing listens there. Forward the Vite port too, to the same port number on your laptop:
ssh -L 8000:localhost:8000 -L 5173:localhost:5173 myserverThe number has to match on both ends. -L 3000:localhost:5173 reaches Vite, but the page still asks for 5173. If you run several projects, each needs its own Vite port, because two forwards cannot share 5173 on your laptop.
Keeping it working with plain SSH
Section titled “Keeping it working with plain SSH”-
List the forwards in
~/.ssh/config, so onessh myserversets them all up:Host myserverLocalForward 8000 localhost:8000LocalForward 5173 localhost:5173ServerAliveInterval 15 -
Reconnect when it drops, with
autosshor a loop aroundssh -N. WithServerAliveInterval 15,sshnotices a dead connection after about 45 seconds instead of hanging. -
Add each new name to
server.allowedHostsif you open the app by a name other thanlocalhostor a*.localhostname.
How Nearhost handles it
Section titled “How Nearhost handles it”New to Nearhost? Install it and add a server first.
Nearhost serves the project at a name such as https://myapp.test, over one SSH connection per server that it reconnects by itself, putting every forward back.
- Vite serves the page. Give its port the
webrole. The proxy passes the hot reload WebSocket through on the same origin. Add the name toserver.allowedHostsonce; with thenearhost/vitepreset enabled, Nearhost shows the exact lines. - Vite sits beside a backend. Give the Vite port the
loopbackrole. Nearhost forwards it to the same port number on your laptop, so the page’shttp://localhost:5173reaches the remote dev server. Under Laravel Sail, discovery proposes this route for you. The page athttps://myapp.testnow loads its scripts from another origin, and Vite’s default CORS policy allows onlylocalhostpages.laravel-vite-pluginalso allows*.testnames and yourAPP_URL; with another integration, add the name toserver.cors.origin. - Several projects. Nearhost warns about two projects that want the same loopback port before they clash, and suggests a free one when the port comes from a variable.
A loopback forward answers on both 127.0.0.1 and [::1], so it also works when Vite listens on ::1 and public/hot says http://[::1]:5173. This needs Nearhost 0.7.0 or later and a laptop with the IPv6 loopback, which every Mac and almost every Linux machine has. Otherwise, see Vite on [::1].
For the details, see Dev servers and hot reload and Routes and roles.