Daemon lifecycle¶

setup

One-time setup: verify Tailscale is installed and connected, then configure tailscale serve for HTTPS on port 7432.

start

Start the daemon in HTTPS mode via tailscale serve (default, recommended).

start-local

Start the daemon bound to 127.0.0.1 only, for access via an SSH port-forward. No TLS certificate is generated; the tunnel provides encryption.

start-direct

Start the daemon with a self-signed TLS certificate, binding on all interfaces for LAN/direct access without Tailscale.

stop

Send SIGTERM to the running daemon. Tailscale serve configuration is left in place.

restart

Stop then start the daemon in HTTPS mode.

status

Show whether the daemon is running and the URL to connect to.

log

Tail the daemon log at ~/.config/trustmux/trustmux.log.

Login hook¶

enable

Run first-time setup if needed, start the daemon, and install a hook in the user's shell login file (~/.profile, ~/.bash_profile, or ~/.zprofile) so the daemon starts automatically on each login.

disable

Stop the running daemon and remove the login hook so the daemon no longer starts automatically. Paired device tokens are preserved.

Device pairing¶

pair

Ask the running daemon to generate a one-time 6-digit pairing code (valid for 3 minutes) and display it along with the URL your phone should open. If qrencode(1) is installed, a QR code is printed for one-scan pairing. The screen is cleared on the next keypress to keep the pairing URL out of the terminal scroll-back.

unpair

List all currently paired devices (IP address, browser label, and pairing time) and offer an interactive menu to remove one or all of them.

Pairing code¶

The one-time pairing code is a 6-digit decimal value drawn from secrets.randbelow(1,000,000), giving 1,000,000 possible values. The code is valid for 3 minutes. After three incorrect guesses the code is immediately invalidated and a new one must be generated with trustmux pair. The hard 3-attempt lockout makes brute-force infeasible: an attacker has a 0.0003% chance of success per pairing window, and each new window requires the machine owner to run trustmux pair again. An incorrect guess also incurs a 0.5-second artificial delay.

Session tokens¶

After a successful pairing the daemon issues a 256-bit URL-safe session token (secrets.token_urlsafe(32)) stored in ~/.config/trustmux/tokens.json (mode 0600) and delivered to the browser as an httponly, SameSite=Strict cookie. Tokens are validated with a constant-time comparison to prevent timing attacks. Sessions expire after 90 days of inactivity and can be revoked at any time with trustmux unpair.

Network exposure¶

In the default start mode the daemon binds only to the Tailscale IP (100.x.x.x), so the pairing endpoint is unreachable from the public internet or from other local-network devices. In start-direct mode the daemon binds on all interfaces; the pairing-code and session-token protections above remain in force, but the network attack surface is broader. In start-local mode the daemon binds to 127.0.0.1 only and is accessible solely through an explicit SSH port-forward.