TRUSTMUXD(1)

📦 version 7.20, in nixpkgs unstable, ubuntu stonking

💖 TRUSTMUXD 💖

okay so real talk: this is the TRUSTMUXD(1) page, aka the glow-up doc for the Trustmux daemon, and I'm gonna walk you through it like we're texting at 2am. grab a boba, bestie, we're learning. 🧋

✨ NAME ✨

trustmuxd — the Trustmux daemon. think of it as the mobile companion app situation for your tmux / Byobu sessions. she's the one holding it down in the background so your sessions look cute on your phone. 💅

🌈 SYNOPSIS 🌈

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

🦋 DESCRIPTION 🦋

so basically trustmuxd is a lightweight little daemon — she's not doing the most, she's doing exactly enough — and what she does is serve up a mobile-optimised web interface so you can monitor and interact with your tmux and Byobu sessions over your Tailscale private network. no public internet nonsense, just you and your sessions in their own private group chat. 🫶

she serves a Progressive Web App (PWA) over HTTPS. iconic behavior.

now, the way she runs depends on the mode:

  • Default mode: she binds to the Tailscale interface and lets tailscale serve handle TLS termination for her. she's not doing her own crypto, she's outsourcing. queen of delegation. 👑
  • Direct mode (that's --self-signed): she generates her own self-signed ECDSA certificate and binds directly on the network interface. self-sufficient, independent, main character energy. ✨

Auth works like this: 6-digit one-time pairing codes (generated with trustmux-pair(1)) and permanent per-device session tokens stored per instance — the file deets are down in FILES, don't worry, we'll get there. 🔐

and lowkey the most important thing: in normal use, you don't even invoke the daemon by hand. she's managed via trustmux(1). so like, yes you can call her directly, but in practice your bestie trustmux(1) does the introducing. 😌

💅 OPTIONS 💅

the full menu, no skips, no "you get the idea," we're doing all of them fr fr:

  • --host ADDR — the bind address. default is your Tailscale IP, or 127.0.0.1 when you're running with --https. 🏠
  • --port PORT — which TCP port she's listening on. default: 7432. 🔢
  • --https — HTTPS mode, bestie! trusts proxy headers and sets the Secure cookie flag. use this one with tailscale serve. (this is the "let tailscale do the TLS, I'll just look pretty" setting.) 🎀
  • --self-signed — generates a self-signed ECDSA P-256 TLS certificate so you get direct HTTPS access without Tailscale. she made it herself, no cap. 🔏
  • --name NAME — which instance's state and runtime files to use. default: default. every instance gets its own tokens, TLS keypair, log, admin socket and pid file, which means you can run several daemons side by side and they won't fight over anything. sibling energy, not rivalry energy. trustmux (1) passes this through when it starts a daemon. 👯
  • --advertise SOURCE — the address to publish and to name in the TLS certificate, for when it's not the one this host can see. Repeatable — stack 'em up. SOURCE can be:
    • a literal HOST
    • a HOST:PORT
    • a full URL
    • or cmd:PROGRAM, which runs PROGRAM and reads one address per line off its standard output. 🖥️

sources get resolved once, at startup — before the certificate is generated and before the admin socket is bound. and if any of them fail to resolve? the daemon stops. like, no warning, no "eh it's probably fine," she's done. what counts as a failure:

  • a non-zero exit
  • no output
  • a blank line
  • a value that isn't an address
  • or more than 5 seconds across all sources

this is the same way she handles an unavailable TLS implementation. because a broken URL or a certificate for the wrong host isn't something a lil warning is gonna fix, babes. 😭💀

the resolved addresses get reported over the admin socket, and that's how trustmux pair and trustmux status print exactly what the certificate attests. receipts, literally. 🧾

when you give neither --advertise nor --no-advertise, the daemon reads TRUSTMUX_ADVERTISE and then the instance's own configuration file. trustmux (1) always passes one or the other, so a daemon it starts uses only the sources it resolved. see trustmux(1) for the full source syntax. 📖

  • --no-advertise — advertise nothing. ignores TRUSTMUX_ADVERTISE and the instance's configuration file entirely. she's off the grid, she's mysterious, she's not telling anyone her address. 🙈
  • --version — prints the version and exits. short and sweet. ⭐

🎀 FILES 🎀

paths follow the XDG base directories, with one subdirectory per instance. wherever you see INSTANCE below, that's the --name name. trustmux (1) documents the full layout, the fallbacks, and the TRUSTMUX_*_DIR overrides — so go there if you need the deep lore.

  • $XDG_CONFIG_HOME/trustmux/instances/INSTANCE.json — optional, hand-written: the advertise sources for this instance, read when neither --advertise nor --no-advertise was given. refused if it's writable by group or other — because a source can name a program to run, and that's a whole security vibe we're not playing with. 🚫
  • $XDG_STATE_HOME/trustmux/instances/INSTANCE/tokens.json — the persistent session tokens (mode 0600). 🔐
  • $XDG_STATE_HOME/trustmux/instances/INSTANCE/cert.pem — the self-signed TLS certificate (mode 0644), created on the first --self-signed start. 🪪
  • $XDG_STATE_HOME/trustmux/instances/INSTANCE/key.pem — the TLS private key (mode 0600). guard this one with your life, bestie. 🔑
  • $XDG_STATE_HOME/trustmux/instances/INSTANCE/trustmux.sock — the admin Unix socket (mode 0600), used by trustmux-pair(1) and trustmux-unpair(1). 🧦

🔥 SEE ALSO 🔥

go read these too, they're all part of the friend group:

💜 AUTHOR 💜

Dustin Kirkland <kirkland@ubuntu.com> — the actual legend who made all of this happen. put some respect on the name. 👑

and that's the whole page, bestie!! shoutout to the trustmux package, this edition dated 2026-05-28. now go pair your phone and monitor some sessions, you've got this. slay, periodt, and remember: your sessions deserve main character energy too. 💖✨🌈🦋🌸🎀💅🫶👑⭐

📦 where this page comes from