Frequently asked questions

On Linux or macOS, run curl -fsSL https://github.com/mzdluo123/webmux/releases/latest/download/install.sh | sh. The script detects your architecture, verifies the SHA-256 and installs to ~/.local/bin/webmux without root. deb / rpm packages, manual downloads, a Windows installer and source builds are also available; see download and install and install and upgrade (Chinese).

The recommended route: install Tailscale on the server and the phone, join the same tailnet, set [tailscale] mode = "serve" and open https://<node>.ts.net/ on the phone. Alternatively, listen on the server's Tailscale / WireGuard address and enter the token once. Your firewall should only allow the trusted VPN interface to reach the port. An HTTPS address can also be installed as an app and receive lock-screen notifications. See phone access (Chinese).

WebMux runs arbitrary commands as the user who started the service, which amounts to exposing a shell to the network. It is not a process sandbox and offers no multi-user isolation. Safety relies on network isolation: listen on 127.0.0.1:7681 for local use, bind to a trusted VPN such as Tailscale or WireGuard for remote use, and use a random token (the first start generates a 256-bit one). Do not expose it directly to the internet; if you must, use a controlled tunnel only, and accept that the token is then the only barrier. See security and deployment.

Yes, but the service does not run natively on Windows: it runs inside a WSL 2 distribution. You need Windows 10 22H2 or later or Windows 11, plus WSL 2 from the Microsoft Store. The tray app installs and upgrades WebMux, starts and monitors it and forwards remote access, without administrator rights; webmux.exe can run / attach WSL sessions from PowerShell or Windows Terminal. See Windows (WSL) deployment (Chinese).

WebMux is open source under the MIT license and free of charge; the source is on GitHub. It does not manage model keys: Claude Code, Codex and the other CLIs use the service user's own accounts, subscriptions and configuration, so any costs and terms are set by the agent vendors.

Sessions live only in memory; the state directory holds only explicitly registered JSON files (repository list, launch configurations, preferences, push, tunnel and Tailscale settings, hybrid-session records); see the persistence list (Chinese). Terminal input and output are never logged, and the configuration API never returns the token. A search of the source on 2026-11-03 found no telemetry or usage-analytics code; outbound connections happen only for features you enable, such as downloading cloudflared, tunnels and push notifications.

Not as a multi-user system. WebMux has a single shared token, every command runs as the user who started the service, and there is no multi-user isolation. Anyone holding the token has the same shell access as you; if you need isolation, give each person their own system user and their own WebMux instance.

Sessions, PTYs and buffers live only in memory, so restarting the service ends every session. This is a deliberate boundary: WebMux uses no database, does not detach into a separate daemon and does not interoperate with tmux. Only explicitly registered state files (repository list, launch configurations, preferences and so on; see the persistence list (Chinese)) survive a restart. The exception is hybrid sessions (Chinese): WebMux records which agent session they map to, so after a restart you can resume them from the “Resumable” group on the home screen; the agent itself keeps the conversation.

systemd and launchd do not load your interactive shell configuration. In a custom launch configuration, use bash -ic 'exec opencode "$@"' opencode to pick up the PATH and environment from ~/.bashrc, or add the program's directory to the service PATH. See agent PATH (Chinese).

Both share one PTY, but only the controlling device sets the terminal size: the first device to open the session controls it, later ones observe (showing the original grid, pannable). Type in the observer or click “Take control” to switch.

Plain HTTP is not a secure browser context, so the Clipboard API is unavailable. WebMux falls back to a text box for manual paste and copy; you can also serve HTTPS through tailscale serve or Caddy. See HTTPS (Chinese).

The buffer is a byte ring, so the oldest data can start in the middle of a multi-byte character or escape sequence. This is within the design's tolerance.

The token generated on first start is stored in the configuration file. Show it with webmux status --json --reveal-token, or find the file with webmux config path. See configuration (Chinese).

Upgrading restarts the service, and a restart ends every terminal session. Let your agents reach a stopping point first; see upgrade (Chinese).