Skip to main content
WebMuxInstall WebMux

Security and deployment

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.

Security model

  • By default it listens on every interface at 0.0.0.0:7681. For local use set 127.0.0.1:7681; for remote use bind to a trusted VPN address and restrict reachable interfaces with a firewall.
  • The first start creates a 0600 configuration file and a persistent 256-bit token; show it with webmux status --json --reveal-token.
  • Every API and WebSocket requires authentication (when a token is set), compared in constant time; requests with an Origin must be same-origin or listed in allowed_origins.
  • The token never appears in request URLs: HTTP uses a Bearer header and WebSocket a subprotocol. Terminal input and output are never logged, and the configuration API never returns the token.
  • WebMux has no built-in TLS; for HTTPS use tailscale serve or a reverse proxy.
  • Registered Git repositories must be trusted: Git runs hooks and filters from repository config. Closing a session cleans up its process tree, but daemons that fully detach from the session may escape it.
  • Only the latest release receives security fixes.

Read the full security policy (Chinese)

Three recommended topologies

Lowest risk

Local only

Who it suits

You only use sessions on the machine running WebMux, in a browser or with webmux attach.

Listen on

127.0.0.1:7681

Token requirements

When listening on loopback only with no tunnel, an empty token means no authentication; we still recommend keeping the 256-bit token generated on first start.

Do not

  • Keep the default 0.0.0.0:7681 and assume only this machine can reach it.
  • Share the port with untrusted users on the same machine.

Step-by-step guide: Configuration (Chinese)

Recommended for remote use

Tailscale / WireGuard

Who it suits

You want to reach it from a phone, tablet or another computer, and every device can join the same trusted VPN.

Listen on

Tailscale / WireGuard address, or [tailscale] mode = "serve"

Token requirements

Use a random token; managed Serve requires a login token of at least 43 characters. The token is stored in the browser's localStorage, so log in only on trusted devices.

Do not

  • Let the firewall open the port on interfaces other than the VPN.
  • Share a tailnet-only entry with people outside the tailnet as if it were public.

Step-by-step guide: Phone access (Tailscale) (Chinese)

Public: the token is the only barrier

Cloudflare Named Tunnel or Tailscale Funnel

Who it suits

You truly cannot use a VPN, need access from any network, and accept the risk of a public shell.

Listen on

127.0.0.1, with HTTPS from a Named Tunnel or Funnel

Token requirements

The token is the only barrier: tunnels and Funnel require a WebMux login token of at least 43 characters; generate one with openssl rand -base64 32. Anyone holding the link and the token can run commands as the service user.

Do not

  • Expose the WebMux port directly to the internet, or forward it through a reverse proxy without authentication.
  • Rely on a Quick Tunnel long term: it has no Cloudflare Access or extra authentication, a random address and no SLA.
  • Let others read the journal or log files: links and QR codes containing #token= are written there.
  • Assume removing --tunnel turns public access off: the persisted setting returns on the next start; turn it off in the web UI, the tray or the local API.

Step-by-step guide: Cloudflare Named Tunnel guide (Chinese)

Reporting a vulnerability

Please do not report vulnerabilities in public issues. Use GitHub's private vulnerability reporting and include the affected version and platform, steps to reproduce or a proof of concept, and the possible impact. See security policy · reporting (Chinese).