Skip to main content
WebMuxInstall WebMux

Run WebMux on Windows with WSL 2

WebMux does not run natively on Windows; it runs inside a WSL 2 distribution. On the Windows side, the tray app installs, starts, monitors and stops it, and the console client lets you start agents and attach to sessions from PowerShell or Windows Terminal. Phones and browsers reach the same sessions through WebMux as usual. The installer and tray menus are in Chinese, so menu items below are quoted as they appear, with an English gloss.

Prerequisites

  • Windows 10 22H2 or later, or Windows 11 (amd64 / arm64). No administrator rights needed.
  • WSL 2 from the Microsoft Store: the tray relies on wsl.exe --version, --exec, --cd and WSL_UTF8, which the older built-in WSL lacks. Run wsl --update in PowerShell to upgrade.
  • At least one installed distribution. Without one, the tray status line shows “未检测到 WSL 发行版” (no WSL distribution detected).

Downloads

These files come from v0.10.2. Pick amd64 or arm64 to match your Windows architecture.

  • webmux-setup-windows-amd64.exe

    Windows installer · x86-64 · 16.2 MiB

    Download

  • webmux-setup-windows-arm64.exe

    Windows installer · ARM64 · 15.0 MiB

    Download

  • webmux-tray-windows-amd64.exe

    Windows tray · x86-64 · 7.7 MiB

    Download

  • webmux-tray-windows-arm64.exe

    Windows tray · ARM64 · 7.0 MiB

    Download

  • webmux-windows-amd64.exe

    Console client · x86-64 · 6.6 MiB

    Download

  • webmux-windows-arm64.exe

    Console client · ARM64 · 6.0 MiB

    Download

All downloads with SHA-256

What the installer and tray do

Installer

Installs for the current user
No administrator rights. Default folder %LOCALAPPDATA%\Programs\WebMux\, with a “WebMux” Start menu entry and an uninstall entry in Apps & features.
Starts the tray when you sign in
“开机后自动启动 WebMux” (start WebMux at sign-in) is checked by default and writes the same startup entry as the tray's “登录时自动启动” (start at login) option.
Bundles the matching server
The installer places the Linux server for your architecture in the tray's download cache. It never touches WSL itself; on first use, choose “安装 WSL 中的 webmux” (install webmux in WSL) in the tray menu.
Unsigned
Windows SmartScreen may block it; choose “More info → Run anyway”. On an architecture mismatch the installer names the right package and exits without writing any files.

Tray

Installs or upgrades webmux in WSL
Fetches the Linux binary matching the tray version and the distribution's architecture, and uses it only if its SHA-256 matches the digest built into the tray. Falls back to the ghfast.top and gh-proxy.com mirrors when GitHub does not respond. It never installs in the background.
Start, stop and restart
Either tray-managed (running webmux serve in the distribution) or as a systemd user service, chosen automatically by default. Unexpected exits trigger a notification and a back-off restart.
Status and diagnostics
The menu status line shows whether WebMux is running, version mismatches and localhost forwarding problems. Instances you start by hand inside WSL appear as external, and the tray never stops them.
Remote access
In the default NAT networking mode, the “远程访问” (remote access) submenu can forward a Windows host address (Tailscale addresses first) to WebMux. Forwarding needs a healthy service with a token and stops when the tray exits.
Public tunnel (Cloudflare)
Turns on or off without a restart and without touching sessions. Each time, the tray asks you to confirm the risk and requires a WebMux token of at least 43 characters.
Copy token and links
The token is read from WSL only when you click. Copies stay out of Windows clipboard history and cloud clipboard, and are cleared after 60 seconds if unchanged.

Console client

webmux-windows-<arch>.exe brings run, attach, ls, open, status and version to PowerShell and Windows Terminal; the sessions run in WebMux inside WSL. Put it on your PATH and rename it to webmux.exe:

webmux run -- claude        # create a session here and attach; Ctrl+] detaches
webmux ls                   # list sessions
webmux attach <ID>          # rejoin the same running process
webmux open <ID> --browser  # open the session link (no token in it)
  • Each connection goes through wsl.exe --exec webmux bridge to the local API, so no token is needed and WSL localhost forwarding or networking mode does not matter.
  • The service must already be running in WSL (tray or webmux serve); the client does not start it.
  • Without --cwd, the current directory is translated to a WSL path (C:\work → /mnt/c/work). For paths that cannot be translated, such as network shares, pass --cwd.
  • While attached, Ctrl+C goes to the session and Ctrl+] detaches. Windows Terminal is recommended.
  • Windows environment variables are not copied into WSL; only variables you list with --env are sent. PowerShell re-parses quotes, so use single quotes to pass $, ; and similar characters literally.

Console client reference (Chinese)

Upgrade and uninstall

  • Upgrade the tray: run the new installer. It asks the running tray to quit as with “仅退出托盘” (quit tray only), so WebMux and its sessions keep running, then replaces the files and starts the new tray.
  • Upgrade webmux in WSL: choose “安装 / 升级 WSL 中的 webmux” (install / upgrade webmux in WSL) in the tray menu. The running process keeps the old version until it restarts, and restarting ends every terminal session, so let your agents finish first.
  • Uninstall: remove WebMux in Apps & features. This closes the tray and deletes the program, shortcuts and bundled server, but keeps tray settings (%APPDATA%\WebMux), tray logs (%LOCALAPPDATA%\WebMux) and webmux inside WSL. A running WebMux is not stopped; run webmux stop in WSL if needed.

Silent install and uninstall use /S (default options, including start at sign-in):

webmux-setup-windows-amd64.exe /S
"%LOCALAPPDATA%\Programs\WebMux\uninstall.exe" /S