https://github.com/ddv1982/tailmux
Access tmux sessions on your Tailscale devices from anywhere.
https://github.com/ddv1982/tailmux
bash cli devtools homelab linux macos remote-access ssh tailscale tailscale-ssh tmux
Last synced: 7 days ago
JSON representation
Access tmux sessions on your Tailscale devices from anywhere.
- Host: GitHub
- URL: https://github.com/ddv1982/tailmux
- Owner: ddv1982
- License: mit
- Created: 2026-01-28T22:11:31.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-03-31T23:02:46.000Z (3 months ago)
- Last Synced: 2026-04-01T01:40:42.047Z (3 months ago)
- Topics: bash, cli, devtools, homelab, linux, macos, remote-access, ssh, tailscale, tailscale-ssh, tmux
- Language: Shell
- Homepage:
- Size: 110 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# tailmux
Access tmux sessions on your Tailscale devices from anywhere.
```bash
tailmux macbook-pro # connect by device name
tailmux 100.101.102.103 # connect by Tailscale IP
```
## Contents
- [Prerequisites](#prerequisites)
- [Quick Start](#quick-start)
- [Setup Commands](#setup-commands)
- [Usage](#usage)
- [File Sharing (Taildrive)](#file-sharing-taildrive)
- [Supported Platforms](#supported-platforms)
- [Uninstall](#uninstall)
- [Notes](#notes)
- [Development](#development)
- [License](#license)
## Prerequisites
- bash and curl
- A [Tailscale](https://tailscale.com) account
- Tailscale SSH enabled on the destination: `sudo tailscale up --ssh`
## Quick Start
```bash
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](#file-sharing-taildrive) shell functions
## Setup Commands
```bash
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
```bash
tailmux # connect and attach/create tmux session
tailmux doctor # 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:**
```bash
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 (`.local`) when `TAILMUX_LAN_FALLBACK=1`
6. System DNS lookup
### Alias File
- Path: `~/.config/tailmux/hosts` (override with `TAILMUX_HOSTS_FILE`)
- Format: ` `
- Example:
```text
home 100.64.0.10
mini mini.example-tailnet.ts.net
```
## File Sharing (Taildrive)
Share directories between devices using [Taildrive](https://tailscale.com/docs/features/taildrive):
```bash
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](docs/taildrive.md).
For troubleshooting connection issues, Tailscale on macOS, and Linux mounts, see [docs/troubleshooting.md](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
bash <(curl -fsSL https://raw.githubusercontent.com/ddv1982/tailmux/main/setup.sh) uninstall
```
## Notes
- All connections use [Tailscale SSH](https://tailscale.com/kb/1193/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](https://login.tailscale.com/admin/machines) 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
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:
```bash
TAILMUX_USE_LOCAL_MODULES=1 bash setup.sh install
```
## License
Released under the [MIT License](LICENSE).