faq
Everything people ask before installing.
If your question isn't here, email us — we answer, and the good ones end up on this page.
Basics
Does mtmux replace tmux?
No. It attaches to the tmux server you already run, the same way tmux attach does — with the same sharp edges around resizing. Remove mtmux and every session keeps running, untouched.
Do I need to install an app?
No — the client is a web app. Add it to your home screen if you want fullscreen keyboard handling, but a normal browser tab works. Any current browser with WebSocket support is fine.
Do I need an account?
No. Without one you get the CLI, local mode and the encrypted tunnel. mtmux login is optional and buys a dashboard and more than one registered server.
What does it need to run?
Node 22 or newer and tmux. macOS, Linux with glibc or musl, and WSL2 are all supported — installing tmux covers every package manager. mtmux doctor checks the rest and tells you what is missing.
Does it work on a tablet?
Yes, and it is arguably the best surface for it — real splits fit, and a Bluetooth keyboard passes chords through unmodified, prefix key included.
What about screen or zellij?
tmux only. mtmux talks to the tmux server directly, so screen and zellij are not supported and there is no flag that enables them. If you are still deciding, the tmux command reference is the fastest way to judge whether tmux is the one you want.
Using it on a phone
Can I really type in vim on a phone?
For edits, yes. The modifier row keeps esc, ctrl, alt, tab and the arrows reachable, and modifiers latch so chords are two taps. Writing a new module on a phone is still a bad idea — what typing on a phone actually feels like is the unvarnished version.
My layout is unreadable on a small screen.
Turn on reflow: panes restack vertically and the focused one goes full width, without resizing the tmux window your desktop is attached to.
Does it survive the subway?
The client reconnects and reattaches on its own when the network comes back, and the tmux session was never at risk — it kept running on your machine the whole time.
Do I have to enter the code every time?
No. Pairing happens exactly once per browser: after that the browser holds a device key and reconnecting is a signed challenge. mtmux devices lists what is trusted, and revoke removes it.
Coding agents
Does mtmux notify me when Claude Code finishes?
No. There is no push, no email, no Slack routing and no agent detection of any kind. mtmux gives you a session you can open from a phone in seconds and read — it is pull, not push, and we would rather say so than imply otherwise.
Then what does it do for agent runs?
It removes the reason you had to be at your desk. The agent runs in a normal tmux session; you open the same pane from wherever you are, read what it printed, answer the prompt and start the next task.
Which agents does it support?
All of them, because it does not know what an agent is. Claude Code, Codex CLI, Gemini CLI, aider or a shell script — if it runs in tmux, mtmux serves it, with no preset and no configuration.
Can I answer an approval prompt from my phone?
Yes. It is an ordinary keystroke to an ordinary pane, so y, n, ctrl-c and your prefix key are all one tap on the modifier row.
I really do want to be paged. What should I use?
Something built for it — a tmux hook that curls ntfy, or your agent's own hook support if it has any. Paging yourself from tmux is the full recipe. That composes with mtmux perfectly well: get paged by one thing, then open the session with the other.
Security & ops
Can the relay read my session?
No. The session keys come out of a PAKE run between your machine and your browser, so the broker forwards sealed frames and holds no key. Details in the threat model.
Does the broker learn my pairing code?
Only the first two digits. The code splits into a two-digit routing slot, which the broker assigns, and a four-digit secret generated in your browser that is never transmitted — not even as a hash. It is the password for the PAKE.
What stops someone guessing the secret?
One wrong guess destroys the pairing. Both sides prove they derived the same key before anything else happens, and a failed confirmation ends it, so an attacker gets a single attempt at a million rather than an offline search. Guessing also costs the machine a visible warning and a slower replacement code, so a sweep is loud as well as futile.
Do I have to open a port?
Nothing has to be forwarded or exposed to the internet. The CLI dials out, so there is no firewall hole, no VPN and no sshd facing the world. On a LAN it does listen locally so other devices in the house can reach it.
What if I lose my phone?
mtmux devices lists the device ids this machine trusts and revoke forgets one, so that browser cannot reconnect. No password reset, and nothing left behind.
Can I run it fully self-hosted?
Yes, at two levels. mtmux start --local serves your LAN and loopback and contacts no broker at all. If you want the tunnel too, run the broker yourself and point the CLI at it with MTMUX_API_URL. Other ways to put tmux in a browser covers the ttyd and wetty routes if you would rather not run ours.
Has the cryptography been audited?
Not independently, and we will say so until it has been. The CPace implementation is checked against the draft's published test vectors, which proves the group maths — it does not prove the surrounding protocol. The source is MIT and readable.
Money
Is it free?
Free forever on one registered server with three trusted devices, and the encrypted tunnel is included rather than held back — 5 GB of relayed traffic a month. Anything on your own network is unmetered. Pro is $10/month or $100/year.
What happens if I hit the 5 GB?
The relayed path stops until the month rolls over. Local and LAN access are unaffected, because that traffic never went through us in the first place.
Is it open source?
The CLI and the browser client are MIT licensed. The pairing broker is in the same repository, so you can read it and run your own.
Who handles payments?
Dodo Payments. Card details never reach our servers, and what Dodo shows at checkout is the authoritative price.