tailmux

Access tmux sessions on your Tailscale devices from anywhere.

tailmux macbook-pro       # connect by device name
tailmux 100.101.102.103   # connect by Tailscale IP

Contents

• Prerequisites
• Quick Start
• Setup Commands
• Usage
• File Sharing (Taildrive)
• Supported Platforms
• Uninstall
• Notes
• Development

Prerequisites

• bash and curl
• A Tailscale account
• Tailscale SSH enabled on the destination: sudo tailscale up --ssh

Quick Start

bash <(curl -fsSL https://raw.githubusercontent.com/ddv1982/tailmux/main/setup.sh)

This will:

• Install Tailscale and tmux (Homebrew on macOS, system package manager on Linux)
• Add the tailmux shell function
• Configure Tailscale operator access (Linux) and enable Tailscale SSH
• Optionally install Taildrive shell functions

Setup Commands

bash setup.sh install    # install/configure everything
bash setup.sh uninstall  # remove shell functions and optionally Tailscale state
bash setup.sh update     # check for and apply package updates
bash setup.sh --help     # show all options

All managed packages (tailscale, tmux, davfs2) track the latest stable version. Set TAILMUX_TAILSCALE_TRACK=unstable to follow the unstable channel.

Usage

tailmux <host>            # connect and attach/create tmux session
tailmux doctor <host>     # run resolver diagnostics
tailmux --help            # show usage
tailmux --version         # show version

Tip: Use tailscale status to list all devices with their hostnames and IPs.

Examples:

tailmux macbook-pro       # connect by device name
tailmux 100.101.102.103   # connect by Tailscale IP
tailmux doctor home       # diagnose resolution for "home"

Host Resolution Order

tailmux resolves hosts in this order to handle cases where short-name DNS is unreliable:

1. Direct IP input
2. User alias file (~/.config/tailmux/hosts)
3. tailscale status --json (device hostname / short name / FQDN)
4. tailscale dns query against your tailnet suffix
5. Optional LAN fallback (<host>.local) when TAILMUX_LAN_FALLBACK=1
6. System DNS lookup

Alias File

• Path: ~/.config/tailmux/hosts (override with TAILMUX_HOSTS_FILE)
• Format: <alias> <target>
• Example:

  home 100.64.0.10
  mini mini.example-tailnet.ts.net
  

File Sharing (Taildrive)

Share directories between devices using Taildrive:

tailshare myproject ~/projects/myapp     # share a directory
tailmount linux-laptop myproject         # mount on another machine

For ACL setup, commands reference, and macOS CLI details, see docs/taildrive.md.

For troubleshooting connection issues, Tailscale on macOS, and Linux mounts, see docs/troubleshooting.md.

Supported Platforms

OS	Package Manager	Remote Access Mode
macOS	Homebrew	Tailscale SSH
Debian/Ubuntu	apt	Tailscale SSH
Fedora	dnf	Tailscale SSH
RHEL/CentOS	yum	Tailscale SSH
Arch Linux	pacman	Tailscale SSH
Windows	-	Use WSL

Uninstall

bash <(curl -fsSL https://raw.githubusercontent.com/ddv1982/tailmux/main/setup.sh) uninstall

Notes

• All connections use Tailscale SSH — no exposed port 22 or system SSH daemon required on any platform
• Your tailnet ACLs must allow Tailscale SSH access (all platforms use Tailscale SSH policy)
• You can set simpler machine names in the Tailscale admin console by clicking on a device and editing its name

Development

setup.sh loads modules from scripts/lib/: constants.sh, dependency_policy.sh, ui.sh, platform.sh, taildrive_templates.sh, rc_blocks.sh, managed_blocks.sh, package_manager.sh, tailscale_macos.sh, packages.sh, update.sh, install.sh, uninstall.sh, cli.sh.

Run tests:

bash scripts/tests/run.sh lint    # syntax + shellcheck
bash scripts/tests/run.sh quick   # required core regression suites
bash scripts/tests/run.sh full    # core + extended regression suites
bash scripts/tests/smoke.sh       # compatibility wrapper (runs full)

CI uses required checks (lint, core-linux, core-macos) and advisory extended checks (extended-linux, extended-macos).

For local module development:

TAILMUX_USE_LOCAL_MODULES=1 bash setup.sh install