trustmux - Man Page
manage the Trustmux daemon
Synopsis
trustmux COMMAND [options]
Description
trustmux is the single command-line interface for the Trustmux daemon — a lightweight server that lets you monitor and interact with your tmux/Byobu sessions from a phone browser over your Tailscale network.
All operations are subcommands of trustmux: initial setup, starting and stopping the daemon, login-hook management, and device pairing.
Commands
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.
Options
- setup --quiet
Suppress the "Next steps" output after a successful setup.
Files
- ~/.config/trustmux/trustmux.log
Daemon log file.
- ~/.config/trustmux/trustmux.pid
PID file written at daemon startup.
- ~/.config/trustmux/trustmux.sock
Admin Unix socket used by pair and unpair.
- ~/.config/trustmux/tokens.json
Paired device session tokens (mode 0600).
- ~/.config/trustmux/machines.json
Optional: sibling machine list for the in-app machine selector.
Examples
Typical first-time setup:
trustmux setup trustmux enable trustmux pair
Daily use:
trustmux status trustmux restart trustmux log
Security
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.
See Also
trustmuxd(1), tailscale(1), tmux(1), byobu(1)
Author
Dustin Kirkland <kirkland@ubuntu.com>