// docs

Two minutes to your first mobile session.

No account, no daemon config, no reverse proxy. If tmux runs, mtmux attaches.

install quickstart agents.toml cli reference self-hosting troubleshooting

Install

npm · any platform

$ npm i -g mtmux

macOS / Linux · script

$ curl -fsSL mtmux.com/i | sh

Debian / Ubuntu

$ apt install mtmux

From source · Rust 1.78+

$ cargo install mtmux

Requires Node 20+ for the npm install, and tmux 3.3a or newer. Works on macOS 13+, any glibc/musl Linux, and WSL2. The client needs a browser with WebSocket and (for push) service worker support — iOS 16.4+, Android Chrome 108+.

Quickstart

Start the daemon next to your tmux server

$ mtmux up # add --detach to run in the background

Open the printed URL on your phone and enter the pair code

open https://m.mtmux.com/9F4-2KD # or scan the QR in the terminal

Add to home screen, allow notifications, watch your agents

$ mtmux watch --agents # auto-detects claude, codex, gemini, aider

note — Run mtmux up --lan to skip the relay entirely and serve on your local network at https://<host>.local:7442, with a self-signed cert you pin once.

agents.toml

Presets live in ~/.mtmux/agents.toml. Override any field, or add your own block for a tool mtmux hasn't met.

~/.mtmux/agents.toml

# global defaults

[notify]

channels = ["push", "slack"]

quiet_hours = "23:00-07:30"

dedupe = "60s"

[agent.claude]

match = "claude" # process or pane title

done_when = "idle_prompt" # idle_prompt | exit_code | regex

block_when = ["approve?", "(y/n)", "Allow"]

stall_after = "5m" # silence threshold

include_tail = 20 # lines attached to the push

actions = ["y", "n", "open"]

[agent.terraform]

match = "terraform"

block_when = ["Enter a value", "Do you want to perform"]

on_block = "push:high"

CLI reference

COMMAND

WHAT IT DOES

mtmux up [--detach --lan]

Start the daemon, discover tmux servers, print a pair code.

mtmux down

Stop the daemon. tmux sessions keep running.

mtmux pair <code>

Approve a device from the terminal instead of the browser.

mtmux devices [ls|revoke]

List paired devices, last seen, and revoke by name.

mtmux sessions

Sessions, windows, panes and detected agents as a table or JSON.

mtmux watch [--agents|--pane]

Attach watchers for done / blocked / stalled / failed events.

mtmux run -- <cmd>

Run a command in a watched pane and notify on completion.

mtmux notify --level <lvl>

Emit an event yourself: ok, blocked, stalled, failed.

mtmux share <pane> --ttl 1h

Mint a read-only link to one pane.

mtmux doctor

Check tmux version, socket permissions, relay reachability, push registration.

Self-hosting the relay

The relay is a dumb pipe: it forwards sealed frames between daemon and device. Run your own if you'd rather not depend on ours.

docker-compose.yml

services:

relay:

image: ghcr.io/mtmux/relay:0.9.4

ports: ["7443:7443"]

environment:

MTMUX_ALLOW_FINGERPRINTS: "/etc/mtmux/allow.txt"

# then, on each machine

$ mtmux up --relay wss://relay.internal:7443

Troubleshooting

No sessions listed

The daemon must run as the user that owns the tmux socket. Check with mtmux doctor; on shared boxes pass --socket /tmp/tmux-1001/default.

Notifications never arrive on iOS

iOS only allows web push from an installed PWA. Add to Home Screen, open from the icon, then allow notifications.

Colors look wrong

Set set -g default-terminal "tmux-256color" and set -as terminal-features ",*:RGB" in your tmux.conf.

Agent never reports done

Its prompt probably doesn't match the preset. Run mtmux watch --pane work:1 --explain to see what mtmux sees, then adjust done_when.

Still stuck? GitHub Discussions or [email protected].