This release is a pre-release and may not be stable for production use.
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:7432only — 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
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file trustmux-7.14rc5.tar.gz.
File metadata
- Download URL: trustmux-7.14rc5.tar.gz
- Upload date:
- Size: 71.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
41d9274d4e26fb2dfdba602bf53b17e5efbffc2ba306d956da8a1298b3a0f6be
|
|
| MD5 |
c9d2643283a58c24eb99c25ed3aea37b
|
|
| BLAKE2b-256 |
1f186d8e3be90a9e15bf91977f3da8383a8879fa68a5e4918298b27ca7c6eb73
|
Provenance
The following attestation bundles were made for trustmux-7.14rc5.tar.gz:
Publisher:
pypi-publish.yml on dustinkirkland/byobu
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
trustmux-7.14rc5.tar.gz -
Subject digest:
41d9274d4e26fb2dfdba602bf53b17e5efbffc2ba306d956da8a1298b3a0f6be - Sigstore transparency entry: 1975694804
- Sigstore integration time:
-
Permalink:
dustinkirkland/byobu@7381700c4da979bc16d3878e9e088c2dfac000a7 -
Branch / Tag:
refs/tags/trustmux-v7.14rc5 - Owner: https://github.com/dustinkirkland
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
pypi-publish.yml@7381700c4da979bc16d3878e9e088c2dfac000a7 -
Trigger Event:
push
-
Statement type:
File details
Details for the file trustmux-7.14rc5-py3-none-any.whl.
File metadata
- Download URL: trustmux-7.14rc5-py3-none-any.whl
- Upload date:
- Size: 59.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
cc00202d71afbb88bf7cc1f52c4450a9864e5a3b341a898da3acc269778444f6
|
|
| MD5 |
630fabeae48d3107903a4548b6a001b9
|
|
| BLAKE2b-256 |
af3278d2635fc6ed8ac203c3d3fbd4c2e61b31692533f42b0097cf61c6d0d258
|
Provenance
The following attestation bundles were made for trustmux-7.14rc5-py3-none-any.whl:
Publisher:
pypi-publish.yml on dustinkirkland/byobu
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
trustmux-7.14rc5-py3-none-any.whl -
Subject digest:
cc00202d71afbb88bf7cc1f52c4450a9864e5a3b341a898da3acc269778444f6 - Sigstore transparency entry: 1975694985
- Sigstore integration time:
-
Permalink:
dustinkirkland/byobu@7381700c4da979bc16d3878e9e088c2dfac000a7 -
Branch / Tag:
refs/tags/trustmux-v7.14rc5 - Owner: https://github.com/dustinkirkland
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
pypi-publish.yml@7381700c4da979bc16d3878e9e088c2dfac000a7 -
Trigger Event:
push
-
Statement type:
