Introducing Trustmux: Your Terminal, In Your Pocket

I've spent almost 3 decades thinking about terminals. Byobu has been my home for shell multiplexing for almost two decades now — a text window manager wrapped around tmux (or screen, if that's still your thing), giving you persistent sessions, status bars, and the kind of muscle memory that makes a terminal feel like an extension of your hands.

But there's always been a gap for me: what happens when I walk away from my desk?

The Problem

I run long-lived shell sessions on my workstation. Background jobs, monitoring dashboards, and — more recently — long-running Claude sessions working through code while I step away. I wanted to check in on all of it from my phone. Not babysit it constantly, just glance at it, run a command if something needed attention, and get on with my day.

The traditional answer here is SSH, or its more mobile-friendly cousin, Mosh. SSH from a machine with a full sized monitor and keyboard and low network latency is of course awesome, with its fully synchronous connection.  But from a phone or tablet — every network hiccup, every WiFi-to-cellular handoff, shows up as lag or a dropped session. Mosh improves on this slightly, but it's still fundamentally built around maintaining that live connection state. On a phone, where networks come and go constantly, that model just doesn't hold up well.

I also tried Claude Mobile, which is excellent for what it does — but it only talks to Claude. I needed something that didn't care what was running in my terminal. Sometimes it's a Claude session, sometimes it's htop, sometimes it's a deploy script or huge rsync job I want to glance at, or even a different code assistant not named Claude. I needed access to the shell, not to a specific tool.

What I actually wanted was something asynchronous: connect when I need to, see the current state instantly, type a command if I need to, and disconnect without worrying about whether the connection survived. Mobile-native, not desktop-terminal-stretched-onto-a-small-screen.

So I built it.

Trustmux

Trustmux is a lightweight daemon that runs alongside your existing tmux or Byobu setup and exposes your sessions as a secure Progressive Web App (PWA) — installable on your phone or tablet, no App Store required.

A few design principles drove this:

Security first. Every connection is encrypted with real TLS certificates. There are two ways to get there:

• Tailscale (recommended): Trustmux binds to your Tailscale IP and uses tailscale serve for automatic certificate provisioning. Zero-trust networking, no port forwarding, no exposed surface area. Pairing your phone takes one command and a 6-digit code.
• Self-managed certificates: If you'd rather not run Tailscale, bring your own certificate — a self-signed cert works fine for personal use.
• Direct networking: If Tailscale is not your thing, and you just want to connect directly, and handle your port forwards, that works just fine too, as a fall back.

Asynchronous by design. This is the core insight. Trustmux doesn't try to maintain a persistent, fragile connection the way SSH does. It talks to tmux directly via libtmux, and streams terminal state to your device over a WebSocket connection that's resilient to network changes. Open the app, see exactly where your session left off, do what you need, close the app. No babysitting required.

A real PWA, not a wrapper. Trustmux installs like a native app — tap "Add to Home Screen" and you get a full-screen icon, an offline-capable UI shell, and silent background updates.

Tool-agnostic. Whatever's running in your tmux panes is what you'll see and interact with — shell commands, Claude sessions, log tails, whatever. Trustmux doesn't care; it just gives you the pane.

Installation

Trustmux is available on Ubuntu (ppa, stonking), Debian, and Fedora development repositories, as well as pip, Homebrew, and the Byobu PPA:

pip install trustmux
# or
brew tap dustinkirkland/trustmux
brew install trustmux
# or via PPA
sudo add-apt-repository ppa:byobu/ppa
sudo apt install trustmux

It's part of the Byobu project, so if you've already got Byobu (7+) installed, you're most of the way there.

Getting Started

Setup is three commands:

trustmux enable    # start at login (optional)
trustmux start     # fire up the daemon
trustmux pair      # generate a pairing URL and 6-digit code

Open the pairing URL on your phone, enter the code, tap "Add to Home Screen," and you're in.

On Security

I take this part seriously, given what's at stake — direct shell access to a workstation. This is exactly the kind of tool that deserves continued, public scrutiny, and I'd genuinely welcome additional expert eyes on it — particularly from people who think about authentication, certificate handling, and network exposure for a living.

Why I Built This

There's a part of this that's just personal. I like staying close to my shell — that's basically the whole premise of Byobu. As more of my work has started to involve long-running AI coding sessions, the gap between "what's happening on my workstation" and "what I can see on my phone" started to bother me. Trustmux closes that gap, on my terms, with a security model I trust.

If you run tmux or Byobu and have ever wanted to check on a session from the couch, the train, or the airport, I think you'll like this.

Try It

• Website: trustmux.dev
• Source: github.com/dustinkirkland/byobu (Trustmux is part of the Byobu project)
• Install: pip install trustmux, brew install trustmux, or via ppa:byobu/ppa

I'd love to hear what you think — what's missing, what's broken, what you'd want next. Feedback, issues, and pull requests are all welcome.

:-Dustin

Anyone interested in Byobu profiles for Tmux?

Last week, my friend and colleague Gustavo Niemeyer introduced me to tmux, modern alternative to GNU Screen.  While I had heard of tmux before, I had never used it.  I spent a few hours this week getting familiar with a handful of how-to tutorials, testimonials of people who have switched from screen to tmux, and of course, the manpage itself.

The short of it is -- I'm really damn impressed!  It seems like a feature-filled terminal multiplexer, with an vibrant community, active developer base, and regular releases.

To get my feet wet this weekend, I started by duplicating many of Byobu's keybindings in my ~/.tmux.conf.  I had to learn a bit about tmux to accomplish that (and even write one trivial patch against tmux to get it working better with gnome-terminal).  You can find my Byobu-like ~/.tmux.conf here, which I've committed to the Byobu source tree and installing from the Byobu PPA packages in /usr/share/byobu/profiles/tmux.  While I have most of the keybindings working, I have not ported over any of the byobu-status scripts yet.  (I'm still thinking about the best way to go about doing that so that they could work with both screen and tmux.)

So I'm curious...

1. Any Ubuntu/tmux users out there?
2. Anyone interested in being able to use Byobu's goodness (keybindings, live status information) with tmux (in addition to screen)?

:-Dustin

The Hardest Bug I've Ever Solved...

EDIT: In fact, I did not solve that bug in the first run.  As the comments note below, there was a flaw in my first solution.  However, with the help of some excellent readers, I've just released a better, more suitable solution.  This post has been updated accordingly, in order to provide accurate documentation of the functionality as released.

I'm oh-so-pleased to announce that I have solved the single bug I have thought longer and harder about than any other.  Ever.  Period.  The solution actually consists of some gorgeous, unprintable ASCII art...

(Skip to the recap at the bottom if you're not interested in perhaps the best blog post I've ever written while in the awesome nation of Hungary...)

From the very earliest days of the screen-profiles package, the first and foremost objection we encountered from traditional system administrators with the proposition that we (Ubuntu) might automatically drop you into a GNU Screen managed shell was, that eats your ctrl-a, which perhaps you have been using to go to the beginning of the line since the dawn of time.

Boy, have I struggled with that.  I mean, I have literally spent many, many nights awake, hacking away at screen-profiles, and then byobu trying desperately to satisfy two diametrically opposite camps -- one class of awesome sysadmins who are emacs-mode fiends and are forever-bound to pressing ctrl-a and moving their cursor to the beginning of the line, and a second class of equally awesome sysadmins who use the HOME key to go to the beginning of a line and totally rock their world using ctrl-a as the GNU Screen escape character.

How, oh how, do we ever make two camps of equally passionate, equally awesome people happy?  Talk about a proverbial Clash of the Titans...

But for the first time ever, I think Byobu 4.0 will actually solve this problem :-)  Please, hear me out...

The irony here is perhaps that 3+ years into my Ubuntu development career, I have circled all the way back to where I began, with the very first tool I wrote for Ubuntu, to scratch a very particular itch of mine.

In Ubuntu 8.04 (and older), the nano editor was the default editor used by various utilities (crontab, dch, etc).  This always bugged me about Ubuntu.  I mean, I knew why Ubuntu needed to default to nano, but I hated being treated like a Linux/UNIX newbie when I used Ubuntu.  So I wrote the Ubuntu utility select-editor.  And from 8.10 on, the first time you encounter a situation where you're required to interact with an editor, you're prompted to choose your preferred editor first.  I dare say that this has improved my life and preserved my sanity as an advanced Ubuntu command line user.

And here we are, back to byobu, screen, and the key that some of us love to hate, and the rest of us hate to love -- ctrl-a.

As of Byobu 4.0, it will now prompt you, the first time you press ctrl-a, and ask:

Configure Byobu's ctrl-a behavior...

When you press ctrl-a in Byobu, do you want it to operate in:
    (1) Emacs mode  (go to beginning of line)
    (2) Screen mode (screen's default escape sequence)
Note that:
  - F12 also operates as Screen escape in Byobu
  - You can press F9 and choose your escape character
  - You can run 'byobu-ctrl-a' at any time to change your selection

Select [1 or 2]: 

If you select (1), from this point forward, ctrl-a will behave in Emacs mode.  And if you enter (2), well you're off and running with ctrl-a in GNU Screen mode.

Sweet!!!  So now, perhaps you Emacs experts out there ask, "what is the Byobu/Screen escape character then, if I do select (1)"?

Helluva question, my friend.  Here's where we get into super techie fun...  :-)


As of Byobu 4.0, the universal escape character is now ctrl-^.  If you choose for ctrl-a to operate in GNU Screen mode, then, ctrl-a will actually throw a ctrl-^ into your Screen session, which actually triggers the escape mode (behaving exactly as before!)  Additionally, F12 has been remapped from it's previous binding to lock-your-terminal (sorry please use ctrl-a-x or ctrl-^-x now for screen locking...) to Byobu's and Screen's escape key.  And as always, you're oh-so-welcome to choose your own escape character at any time using F9 (byobu-config).

Wow.  How about that?  Okay, so to recap:

1. Byobu 4.0+ users will be prompted the first time they press ctrl-a to select its behavior (and they can interactively reconfigure at any time by running byobu-ctrl-a)
2. Byobu 4.0+ uses ctrl-^ (and optionally ctrl-a) as the escape sequence, which is always bound to F12, and may optionally be bound to ctrl-a or some other user configurable escape sequence.

Finally, a huge thanks to Clint Byrum (and so many others) for the final kick in the butt that pushed me over the edge to go and fix this once, and for all ;-)

:-Dustin