<!-- Copyright 2025-2026 Richard Shade. Licensed under Apache-2.0. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->
Tailscale Install
Install Tailscale and connect a device to a tailnet. Handles platform
detection, installation, verification, and initial authentication.
What this skill does
- Detects the platform (OS, distro, WSL2, container).
- Checks for an existing Tailscale installation.
- Installs Tailscale using the appropriate package manager.
- Verifies the installation and daemon status.
- Guides initial connection to the tailnet.
Platform detection
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
Existing install check
Before installing, check if Tailscale is already present:
tailscale version 2>/dev/null
If installed:
- Report the current version.
- Check daemon status:
sudo systemctl status tailscaled (Linux).
- Check connection:
tailscale status.
- Stop here unless the user requests a reinstall or upgrade.
If not installed, proceed to installation.
WSL2 special case
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].
Installation
Linux (most distros)
curl -fsSL https://tailscale.com/install.sh | sh
macOS
brew install --cask tailscale
Windows
winget install tailscale.tailscale
For distro-specific repo setup (apt, dnf, pacman, apk, zypper), Docker,
Chocolatey, and MSI, see references/platform-install-commands.md.
Post-install verification
After installation, verify three things:
1. Binary is available
tailscale version
If not found, check PATH or restart the terminal session.
2. Daemon is running
# Linux (systemd)
sudo systemctl enable --now tailscaled
sudo systemctl status tailscaled
# macOS — open Tailscale from Applications
# Windows — check: Get-Service Tailscale
3. Connection status
tailscale status
If the device is not yet authenticated, proceed to initial connection.
Initial connection
Interactive (desktop/laptop)
sudo tailscale up
This prints an authentication URL. Open it in a browser to sign in.
Headless (server)
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.
Error handling
Do not silently skip a failed installation. Report the error with
specific remediation steps.
- Permission denied — prefix with
sudo or run as administrator.
- Package not found — Tailscale repo not configured. Use the
curl
one-liner or add the repo manually (see references).
- Network error — check internet connectivity and DNS resolution.
- Daemon not starting — check logs with
sudo journalctl -u tailscaled --no-pager -n 50. Verify no other VPN
is bound to the same port.
- Auth failure — expired auth key (regenerate in admin console), SSO
misconfiguration, or device limit reached.
References
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