Install and configure Tailscale across platforms. Detects OS, distro, and environment (including WSL2 and containers). Verifies existing installations, performs platform-appropriate install, and guides initial connection. Use when setting up Tailscale on a new machine, onboarding a server to a tailnet, or verifying an existing install.
Install Tailscale and connect a device to a tailnet. Handles platform detection, installation, verification, and initial authentication.
Detect the environment before selecting an install method. Check WSL2 first to avoid installing the Linux package inside a WSL2 instance.
1. Check WSL2 (but not containers running on WSL2)
├─ grep -qi microsoft /proc/version 2>/dev/null
├─ AND [ ! -f /.dockerenv ] (not a container)
├─ WSL2 → go to "WSL2 special case"
└─ Not WSL2 (or container) → continue
2. Check OS
├─ uname -s → Linux → detect distro
├─ uname -s → Darwin → macOS
└─ OS is Windows → PowerShell commands
3. Detect Linux distro
├─ . /etc/os-release && echo $ID
├─ debian, ubuntu → apt
├─ fedora, rhel, centos, amzn → dnf/yum
├─ arch, manjaro → pacman
├─ alpine → apk
├─ opensuse*, sles → zypper
└─ other → curl one-liner fallback
Before installing, check if Tailscale is already present:
tailscale version 2>/dev/null
If installed:
sudo systemctl status tailscaled (Linux).tailscale status.If not installed, proceed to installation.
WSL2 shares the Windows host network stack. Installing Tailscale inside WSL2 creates conflicting WireGuard tunnels. Do not install the Linux package in WSL2.
Detection (exclude containers running on WSL2 hosts):
grep -qi microsoft /proc/version 2>/dev/null && [ ! -f /.dockerenv ] && echo "WSL2 detected"
When WSL2 is detected:
Check for Windows host Tailscale:
tailscale.exe version 2>/dev/null
If found — report version and verify with tailscale.exe status.
If not found — instruct the user to install on the Windows host using
WinGet, Chocolatey, or MSI (see references/platform-install-commands.md).
Verify tailscale.exe is accessible from WSL2. If not, check that
appendWindowsPath = true in /etc/wsl.conf under [interop].
curl -fsSL https://tailscale.com/install.sh | sh
brew install --cask tailscale
winget install tailscale.tailscale
For distro-specific repo setup (apt, dnf, pacman, apk, zypper), Docker,
Chocolatey, and MSI, see references/platform-install-commands.md.
After installation, verify three things:
tailscale version
If not found, check PATH or restart the terminal session.
# Linux (systemd)
sudo systemctl enable --now tailscaled
sudo systemctl status tailscaled
# macOS — open Tailscale from Applications
# Windows — check: Get-Service Tailscale
tailscale status
If the device is not yet authenticated, proceed to initial connection.
sudo tailscale up
This prints an authentication URL. Open it in a browser to sign in.
Generate an auth key in the admin console (Settings > Keys), then:
sudo tailscale up --authkey=tskey-auth-<key>
For tags, subnet routes, exit nodes, and all tailscale up flags, see
references/post-install-checklist.md.
Do not silently skip a failed installation. Report the error with specific remediation steps.
sudo or run as administrator.curl
one-liner or add the repo manually (see references).sudo journalctl -u tailscaled --no-pager -n 50. Verify no other VPN
is bound to the same port.references/platform-install-commands.md — exhaustive per-platform
install commandsreferences/post-install-checklist.md — verification steps, auth key
options, common flags, and first-run troubleshooting