trustmux 7.12rc1

Monitor and interact with tmux/Byobu sessions from your phone

Trustmux

A mobile companion for tmux / Byobu sessions. Run a lightweight daemon on your workstation; monitor and interact with your terminal sessions from your phone over your Tailscale network. No relay server — terminal data stays between your devices.

Works with plain tmux and with byobu. Byobu users get the live status bar chips; plain tmux users get everything else.

Two tiers:

• Free — PWA. Install one icon per machine directly from the browser.
• Paid — Native Flutter app with full ANSI colors, multi-machine management, and biometric auth.

---

Requirements

• tmux (byobu optional but recommended)
• Python 3.10+
• Tailscale installed, running, and connected

---

Install

Homebrew (macOS / Linux)

brew tap dustinkirkland/trustmux
brew install trustmux
trustmux enable    # configure tailscale serve + start daemon
trustmux pair      # generate pairing code; enter on phone

pip (PyPI)

pip install trustmux
trustmux enable
trustmux pair

Debian / Ubuntu (.deb)

Trustmux is bundled with byobu — installing byobu brings trustmux along:

sudo apt install byobu
trustmux enable
trustmux pair

Or with the PPA for the latest release:

sudo add-apt-repository ppa:dustinkirkland/byobu
sudo apt install byobu
trustmux enable
trustmux pair

---

Daily use

trustmux start      # start daemon
trustmux stop       # stop daemon
trustmux restart    # restart daemon
trustmux status     # show URL and running status
trustmux log        # tail the daemon log

trustmux pair           # generate a pairing code for a new device
trustmux unpair         # list paired devices and remove them

---

Setup from source

cd mobile/
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
trustmux enable
trustmux pair

---

Configuration

Path	Purpose
~/.config/trustmux/tokens.json	Paired device session tokens (mode 0600)
~/.config/trustmux/trustmux.sock	Admin Unix socket (mode 0600)
~/.config/trustmux/trustmux.log	Daemon log (mode 0600)
~/.config/trustmux/machines.json	Optional: sibling machines for the machine selector

Multiple machines

[
  { "name": "work",     "url": "https://work-machine.tail1234.ts.net" },
  { "name": "personal", "url": "https://personal.tail1234.ts.net" }
]

---

Security

• Daemon binds to 127.0.0.1:7432 only — not reachable from the network
• All traffic encrypted by Tailscale WireGuard; HTTPS via tailscale serve
• No relay server — terminal data never leaves your Tailscale mesh
• Pairing codes: 6-digit, 5-minute TTL, single-use, max 10 attempts
• Session tokens: 256-bit random, stored at mode 0600

---

Tests

cd mobile/
python3 -m unittest tests.test_daemon -v

---

Troubleshooting

502 Bad Gateway — tailscale serve is running but daemon isn't: trustmux start

"Serve not enabled" — visit the URL printed by tailscale serve --bg 7432

Phone can't reach URL — ensure Tailscale is active on the phone

Need to re-pair — run trustmux pair and enter the new code on the device