TRUSTMUX(1)

NAME
trustmux - 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>