trustmuxd - Man Page

trustmuxd [--host ADDR] [--port PORT] [--name NAME] [--https] [--self-signed] [--advertise SOURCE] [--no-advertise] [--version]

trustmuxd is a lightweight daemon that serves a mobile-optimised web interface for monitoring and interacting with tmux and Byobu sessions over your Tailscale private network.

The daemon serves a Progressive Web App (PWA) over HTTPS.  In the default mode it binds to the Tailscale interface and relies on tailscale serve for TLS termination.  In direct mode (--self-signed) it generates a self-signed ECDSA certificate and binds directly on the network interface.

Authentication uses 6-digit one-time pairing codes (generated with trustmux-pair(1)) and permanent per-device session tokens stored per instance (see Files).

In normal use, the daemon is managed via trustmux(1) rather than being invoked directly.

--host ADDR

Bind address (default: Tailscale IP, or 127.0.0.1 with --https).

--port PORT

TCP port to listen on (default: 7432).

--https

HTTPS mode: trust proxy headers and set Secure cookie flag. Use with tailscale serve.

--self-signed

Generate a self-signed ECDSA P-256 TLS certificate for direct HTTPS access without Tailscale.

--name NAME

Which instance's state and runtime files to use (default: default). Each instance has its own tokens, TLS keypair, log, admin socket and pid file, so several daemons can run side by side. trustmux (1) passes this through when it starts a daemon.

--advertise SOURCE

Address to publish and to name in the TLS certificate, for when it is not the one this host can see. Repeatable. SOURCE is a literal HOST, HOST:PORT, a full URL, or cmd:PROGRAM to run PROGRAM and read one address per line of its standard output.

Sources are resolved once, at startup, before the certificate is generated and before the admin socket is bound. Any failure to resolve one — a non-zero exit, no output, a blank line, a value that is not an address, or more than 5 seconds across all sources — stops the daemon, in the same way an unavailable TLS implementation does: an unreachable URL, or a certificate for the wrong host, is not something a warning would fix.

The resolved addresses are reported over the admin socket, which is how trustmux pair and trustmux status come to print exactly what the certificate attests.

When no --advertise or --no-advertise is given, the daemon reads TRUSTMUX_ADVERTISE and then the instance's configuration file itself. trustmux (1) always passes one or the other, so a daemon it starts uses only the sources it resolved. See trustmux(1) for the source syntax in full.

--no-advertise

Advertise nothing, ignoring TRUSTMUX_ADVERTISE and the instance's configuration file.

--version

Print version and exit.

Paths follow the XDG base directories, one subdirectory per instance; INSTANCE below is the --name name. trustmux (1) documents the full layout, the fallbacks and the TRUSTMUX_*_DIR overrides.

$XDG_CONFIG_HOME/trustmux/instances/INSTANCE.json

Optional, hand-written: advertise sources for this instance, read when neither --advertise nor --no-advertise was given. Refused if writable by group or other, since a source can name a program to run.

$XDG_STATE_HOME/trustmux/instances/INSTANCE/tokens.json

Persistent session tokens (mode 0600).

$XDG_STATE_HOME/trustmux/instances/INSTANCE/cert.pem

Self-signed TLS certificate (mode 0644), created on first --self-signed start.

$XDG_STATE_HOME/trustmux/instances/INSTANCE/key.pem

TLS private key (mode 0600).

$XDG_STATE_HOME/trustmux/instances/INSTANCE/trustmux.sock

Admin Unix socket (mode 0600) used by trustmux-pair(1) and trustmux-unpair(1).

trustmux(1), trustmux-pair(1), trustmux-unpair(1), trustmux-enable(1), trustmux-disable(1), byobu(1), tmux(1)

Dustin Kirkland <kirkland@ubuntu.com>

trustmux(1).