trustmux - Man Page

trustmux COMMAND [options]

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.

setup --quiet

Suppress the "Next steps" output after a successful setup.

--port PORT

TCP port the daemon listens on (default: 7432). Accepted by setup, start, start-local, start-direct, stop, restart, status and enable.

Only the port changes; each mode binds the same address it always has. stop and status do not normally need the flag: they ask the running daemon over the admin socket which port it is on, so a daemon started on a non-default port is still found without repeating --port. The same answer gives pair the correct URL and QR code.

enable records the port in the login hook it writes, so a non-default port survives logout; re-running enable --port rewrites an existing hook rather than leaving the old port in place.

--advertise SOURCE

Address a phone should use, for when it is not the one this host can see. Accepted by start, start-local, start-direct, restart and enable. Repeatable.

Behind NAT — a cloud instance, most often — the daemon only ever sees an internal address, so both the URL pair prints and the names in the certificate start-direct generates describe a host nothing outside can route to. SOURCE overrides that. It does not change what the daemon binds; combine it with a firewall rule that admits the port.

SOURCE is one of:

HOST

or HOST:PORT A literal address or name. The daemon's own scheme and port fill in what is omitted, so --advertise 203.0.113.45 on a daemon serving HTTPS on 7432 advertises https://203.0.113.45:7432/.

URL

A full http:// or https:// URL, which overrides both scheme and port — for a reverse proxy terminating TLS on 443 in front of the daemon. A path, query or fragment is rejected: trustmux serves from the root, and the pairing code is carried in the fragment.

cmd:PROGRAM

Run PROGRAM and take one address per line of its standard output.

cmd: is how an address that changes stays correct. A cloud instance with an ephemeral public address gets a different one across a stop/start cycle, so a literal written down once would quietly go stale, while cmd: is re-run on every daemon start.

PROGRAM is split into arguments with shell-style quoting but is not run by a shell: no pipelines, no redirection, no $(...). Those characters are rejected rather than passed through to the program, so put a pipeline in a script and name the script. An absolute path is safest, a daemon's PATH being whatever started it.

Resolution is strict, and any failure stops the daemon rather than falling back to the address it would have guessed: a non-zero exit, no output, a blank line, a value that is not an address, or more than 5 seconds across all sources. This is deliberate. A shell wrapper whose curl fails typically prints an empty line and still exits 0, and treating that as "nothing to advertise" would hand out an unreachable URL and a certificate for the wrong host — neither of which a warning would fix.

Every resolved address is added to the certificate as a subject alternative name; the first supplies the URL that pair, status and start print. A browser rejects a certificate that omits the name in the URL bar outright, rather than offering the click-through a self-signed certificate gets, so advertising an address without certifying it would be worse than useless.

--no-advertise

Advertise nothing, ignoring any source in TRUSTMUX_ADVERTISE or the instance's configuration file. Accepted wherever --advertise is.

--name NAME

Act on the named instance instead of default. Accepted by every subcommand. Each instance keeps its own pid file, admin socket, log, session tokens and TLS certificate, so several daemons can run at once — on different ports, or on the same port at different bind addresses.

NAME must match `[A-Za-z0-9][A-Za-z0-9._-]{0,31}': it becomes a directory name and is written into the login hook, so separators, leading dots and shell metacharacters are rejected rather than sanitised.

Only the default instance can use tailscale serve mode. serve publishes on the tailnet's port 443, which just one daemon can own — a second would silently take over the mapping and leave the first running but unreachable. Named instances therefore use start-direct or start-local, and setup, start, restart and enable refuse them with a message pointing at those modes. Note that --port does not lift this restriction: it moves only the loopback backend that tailscale serve proxies to, not the tailnet-facing port.

--force

Accepted by rm. Remove the instance even though its daemon is running (it is stopped first), or even though it is the default instance.

TRUSTMUX_PORT

Default port when --port is not given, for users who always want a different port. An out-of-range or non-numeric value is an error, not a silent fallback.

TRUSTMUX_INSTANCE

Default instance when --name is not given. An invalid name is an error, not a silent fallback.

TRUSTMUX_ADVERTISE

Default advertise source when --advertise is not given. Holds a single source, not a list: no separator would be safe, since `:' collides with both URL schemes and the cmd: prefix while `,' can appear inside a command's arguments. A cmd: source already yields as many addresses as it likes, so nothing is out of reach.

TRUSTMUX_CONFIG_DIR

TRUSTMUX_STATE_DIR

Override the configuration and state base directories individually. Each takes precedence over the corresponding XDG variable. Pointing both at a scratch directory is the supported way to run a throwaway daemon — from a development tree, for instance — without touching the real one. start , stop , status and list act only on a daemon that this instance itself started, determined from its own admin socket and pid file rather than from who holds a port, so the isolation holds even when the scratch daemon shares a port with the real one.

Files live in the XDG base directories, with one subdirectory per instance: $XDG_CONFIG_HOME (default ~/.config) holds the one file the user writes by hand, and $XDG_STATE_HOME (default ~/.local/state) holds everything the daemon owns.

Below, INSTANCE is the --name name, or default when unset.

Typical first-time setup:

trustmux setup
trustmux enable
trustmux pair

Daily use:

trustmux status
trustmux restart
trustmux log

Run on a different port; later commands find it without the flag:

trustmux start-direct --port 3389
trustmux status
trustmux pair
trustmux stop

A second daemon alongside the first, with its own tokens and log:

trustmux start-direct --name work --port 3389
trustmux pair --name work
trustmux list
trustmux stop --name work

A throwaway daemon that touches none of the above:

export TRUSTMUX_CONFIG_DIR=$(mktemp -d)
export TRUSTMUX_STATE_DIR=$TRUSTMUX_CONFIG_DIR/state
trustmux start-local --port 3389

On a cloud instance whose public address the host itself cannot see. Write a program that prints it — here a one-liner against the metadata service, which unlike a shell pipeline reports its own failure:

$ cat /usr/local/bin/external-ip
#!/bin/sh
exec curl --fail --silent -H Metadata-Flavor:Google \
  http://metadata.google.internal/computeMetadata/v1/instance/\
network-interfaces/0/access-configs/0/external-ip

$ trustmux start-direct --advertise cmd:/usr/local/bin/external-ip
$ trustmux pair

To keep it across reboots, put the source in the instance's configuration file (see Files) rather than in the command line, and the address is looked up afresh each time:

mkdir -p ~/.config/trustmux/instances
echo '{"advertise": ["cmd:/usr/local/bin/external-ip"]}' \
  > ~/.config/trustmux/instances/default.json
chmod 600 ~/.config/trustmux/instances/default.json
trustmux start-direct

trustmuxd(1), tailscale(1), tmux(1), byobu(1)

Dustin Kirkland <kirkland@ubuntu.com>

trustmuxd(1).