# Tailscale Client

> Install, configure, and troubleshoot the official Tailscale client when

- **Type:** Skill
- **Install:** `agentstack add skill-magnus919-agent-skills-tailscale-client`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [magnus919](https://agentstack.voostack.com/s/magnus919)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [magnus919](https://github.com/magnus919)
- **Source:** https://github.com/magnus919/agent-skills/tree/main/bundles/tailscale/skills/tailscale-client

## Install

```sh
agentstack add skill-magnus919-agent-skills-tailscale-client
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# tailscale-client

## Overview

Tailscale is a WireGuard-based mesh VPN that connects devices into a secure
tailnet. When used with [Headscale](https://github.com/juanfont/headscale), a
self-hosted open-source control server, the official Tailscale client connects
via the `--login-server` flag instead of Tailscale's SaaS control plane.

This skill covers client-side installation, authentication, diagnostics, and
troubleshooting.

### Architecture

```
[Client A] ───── WireGuard ───── [Client B]
      │                               │
      └──────── Headscale URL ────────┘
                  (control/
                 coordination)
```

The Tailscale client (the `tailscaled` daemon) registers with the Headscale
control server, exchanges WireGuard keys, and establishes direct peer-to-peer
encrypted connections. When direct NAT traversal fails, traffic falls back
through DERP (Detour Encrypted Relay Protocol) relays.

## Installation

Install the official Tailscale client on the target device:

| Platform | Command |
|----------|---------|
| **Debian/Ubuntu** | `curl -fsSL https://pkgs.tailscale.com/stable/ubuntu/jammy.noarmor.gpg | sudo tee /usr/share/keyrings/tailscale-archive-keyring.gpg >/dev/null && curl -fsSL https://pkgs.tailscale.com/stable/ubuntu/jammy.tailscale-keyring.list | sudo tee /etc/apt/sources.list.d/tailscale.list && sudo apt-get update && sudo apt-get install tailscale` |
| **macOS** | `brew install tailscale` |
| **Windows** | `choco install tailscale` |
| **Fedora/RHEL** | `sudo dnf install dnf-plugins-core && sudo dnf config-manager --add-repo https://pkgs.tailscale.com/stable/fedora/tailscale.repo && sudo dnf install tailscale` |
| **Alpine** | `apk add tailscale` |

See `ts-install.sh` for automated detection and installation.

## Connection

After installation, authenticate with your Headscale server:

```bash
sudo tailscale up --login-server=https://headscale.example.com
```

This opens a browser for web-based authentication OR prints an auth URL at the
terminal. For non-interactive (scripted) setups, use a pre-authentication key:

```bash
sudo tailscale up \
  --login-server=https://headscale.example.com \
  --authkey=tskey-auth-xxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

See `ts-up.sh` for a wrapper with env-var defaults.

## Authentication

### Web Auth

The default `tailscale up` flow prints a URL (e.g. `https://headscale.example.com/register/nodekey:xxxxx`).
Visit this URL in a browser (or pass it to the Headscale admin to approve).

### Pre-Auth Keys

Generate on the Headscale server:

```bash
headscale preauthkeys create --user myuser
```

Use the key with `--authkey` as shown above. Keys can be tagged for
service/auth nodes that don't belong to a specific user:

```bash
headscale preauthkeys create --user myuser --tags tag:ci-runner,tag:monitoring
```

Then on the client:

```bash
sudo tailscale up \
  --login-server=https://headscale.example.com \
  --authkey=tskey-auth-xxxxx \
  --advertise-tags=tag:ci-runner
```

## Diagnostics

| Command | Purpose |
|---------|---------|
| `tailscale status --json` | List all peers and their connection state |
| `tailscale ping --verbose -c 3 ` | Test direct vs. relay path to a peer |
| `tailscale netcheck` | Check NAT type and DERP relay connectivity |
| `tailscale version` | Client and daemon version info |
| `tailscale debug` | Low-level debugging (derp-map, metrics, goroutines) |

Run `ts-diagnostics.sh` for a comprehensive connectivity bundle that collects
all of the above into a structured JSON output. Use
`ts-connectivity-report.py` to interpret the diagnostics and produce a
human-readable or structured report.

## Features

| Feature | Headscale Support | Notes |
|---------|-------------------|-------|
| **MagicDNS** | ✅ Supported | `--accept-dns` must be passed to `tailscale up` |
| **Taildrop / Taildrive** | ✅ Supported | File sharing between peers |
| **Tailscale SSH** | ✅ Supported | `--ssh` flag on `tailscale up` |
| **Serve** | ✅ Supported | Expose local services via tailnet |
| **Funnel** | ❌ Not supported | Funnel requires Tailscale's SaaS control plane |
| **Exit Nodes** | ✅ Supported | Advertise with `--advertise-exit-node`, use with `--exit-node` |

## Environment Variables

| Variable | Purpose |
|----------|---------|
| `HEADSCALE_URL` | Default `--login-server` URL for `ts-up.sh` |
| `TAILSCALE_AUTHKEY` | Default `--authkey` for `ts-up.sh` |

## Gotchas

- **Port conflicts (8080, 8443)**: Tailscale Serve often uses 8080 or 8443.
  Check for conflicts with `lsof -i :8080`.
- **Subnet overlap**: If the tailnet subnets overlap with local networks,
  routes may not work. Review advertised routes carefully.
- **DERP-only fallback**: When NAT traversal fails, peers connect via DERP
  relays only. Latency increases significantly. Check with
  `ts-diagnostics.sh` or `tailscale status --json` and look for
  `"relay":"..."` instead of `"txBytes"/"rxBytes"` on the direct path.
- **tailscaled not running**: The daemon must be started before `tailscale`
  CLI commands work. On systemd systems: `sudo systemctl start tailscaled`.
  On macOS: open the Tailscale GUI app or run `sudo tailscaled`.
- **DNS resolution**: MagicDNS requires `--accept-dns` on `tailscale up`.
  Without it, nodes are only reachable by their Tailscale IP (100.x.x.x).
- **Key expiry**: Node keys expire by default. Use `--force-reauth` or
  re-run `tailscale up` to re-authenticate. Pre-auth keys can be created
  with `--expiry=false` for non-expiring (long-lived) nodes.

## Trigger Conditions

This skill should be loaded when the user mentions any of the following:

- Installing or setting up Tailscale client on any platform
- Connecting a device to a Headscale server
- Tailscale authentication issues (auth key, web auth, node approval)
- Checking tailscale status, ping, or connectivity
- DERP relay problems or NAT traversal failures
- Tailscale SSH, Serve, MagicDNS, or Taildrop configuration
- Troubleshooting "tailscaled not running" or "no connection"
- Interpreting `tailscale status`, `tailscale ping`, or `tailscale netcheck` output

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [magnus919](https://github.com/magnus919)
- **Source:** [magnus919/agent-skills](https://github.com/magnus919/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-magnus919-agent-skills-tailscale-client
- Seller: https://agentstack.voostack.com/s/magnus919
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.