dirien/tailscale-install

<!-- 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

1. Detects the platform (OS, distro, WSL2, container).
2. Checks for an existing Tailscale installation.
3. Installs Tailscale using the appropriate package manager.
4. Verifies the installation and daemon status.
5. 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:

1. Check for Windows host Tailscale:

   tailscale.exe version 2>/dev/null
   

2. If found — report version and verify with tailscale.exe status.

3. If not found — instruct the user to install on the Windows host using WinGet, Chocolatey, or MSI (see references/platform-install-commands.md).

4. 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 commands
• references/post-install-checklist.md — verification steps, auth key options, common flags, and first-run troubleshooting