# Tailscale

> This skill should be used when managing Tailscale mesh VPN networks. Use when the user asks to "check tailscale status", "list tailscale devices", "ping a device", "send file via tailscale", "tailscale funnel", "tailscale serve", "create auth key", "check who's online", "tailscale exit node", "Magic DNS", or mentions Tailscale network management, tailnet operations, or VPN connectivity.

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

## Install

```sh
agentstack add skill-jmagar-claude-homelab-tailscale
```

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

## About

# Tailscale Skill

**⚠️ MANDATORY SKILL INVOCATION ⚠️**

**YOU MUST invoke this skill (NOT optional) when the user mentions ANY of these triggers:**
- "Tailscale status", "tailnet devices", "VPN status"
- "Tailscale peers", "who's connected", "exit nodes"
- "check Tailscale", "tailnet monitoring", "Tailscale"
- Any mention of Tailscale or VPN network management

**Failure to invoke this skill when triggers occur violates your operational requirements.**

## Purpose

Hybrid skill using both the Tailscale CLI (local machine operations) and the Tailscale API (tailnet-wide management). **Read-Write (Safe)** — no destructive operations; writes include creating auth keys and toggling network features.

| Operation type | Method | Requires API key |
|----------------|--------|-----------------|
| Status, ping, netcheck, whois | CLI | No |
| Serve, funnel, file transfer, SSH | CLI | No |
| List all devices, user mgmt, DNS | API | Yes |
| Create/revoke auth keys | API | Yes |

## Setup

API config (optional, for tailnet-wide operations) is stored in `~/.claude-homelab/.env`:

```bash
TAILSCALE_API_KEY="tskey-api-k..."
TAILSCALE_TAILNET="-"
```

Get your API key from: Tailscale Admin Console → Settings → Keys → Generate API Key

The `TAILSCALE_TAILNET` can be `-` (auto-detect), your org name, or email domain.

---

## Local Operations (CLI)

These work on the current machine only.

### Status & Diagnostics

```bash
# Current status (peers, connection state)
tailscale status
tailscale status --json | jq '.Peer | to_entries[] | {name: .value.HostName, ip: .value.TailscaleIPs[0], online: .value.Online}'

# Network diagnostics (NAT type, DERP, UDP)
tailscale netcheck
tailscale netcheck --format=json

# Get this machine's Tailscale IP
tailscale ip -4

# Identify a Tailscale IP
tailscale whois 100.x.x.x
```

### Connectivity

```bash
# Ping a peer (shows direct vs relay)
tailscale ping 

# Connect/disconnect
tailscale up
tailscale down

# Use an exit node
tailscale up --exit-node=
tailscale exit-node list
tailscale exit-node suggest
```

### File Transfer (Taildrop)

```bash
# Send files to a device
tailscale file cp myfile.txt :

# Receive files (moves from inbox to directory)
tailscale file get ~/Downloads
tailscale file get --wait ~/Downloads  # blocks until file arrives
```

### Expose Services

```bash
# Share locally within tailnet (private)
tailscale serve 3000
tailscale serve https://localhost:8080

# Share publicly to internet
tailscale funnel 8080

# Check what's being served
tailscale serve status
tailscale funnel status
```

### SSH

```bash
# SSH via Tailscale (uses MagicDNS)
tailscale ssh user@hostname

# Enable SSH server on this machine
tailscale up --ssh
```

---

## Tailnet-Wide Operations (API)

These manage your entire tailnet. Requires API key.

### List All Devices

```bash
./scripts/ts-api.sh devices

# With details
./scripts/ts-api.sh devices --verbose
```

### Device Details

```bash
./scripts/ts-api.sh device 
```

### Check Online Status

```bash
# Quick online check for all devices
./scripts/ts-api.sh online
```

### Authorize/Delete Device

```bash
./scripts/ts-api.sh authorize 
./scripts/ts-api.sh delete 
```

### Device Tags & Routes

```bash
./scripts/ts-api.sh tags  tag:server,tag:prod
./scripts/ts-api.sh routes 
```

### Auth Keys

```bash
# Create a reusable auth key
./scripts/ts-api.sh create-key --reusable --tags tag:server

# Create ephemeral key (device auto-removes when offline)
./scripts/ts-api.sh create-key --ephemeral

# List keys
./scripts/ts-api.sh keys
```

### DNS Management

```bash
./scripts/ts-api.sh dns                 # Show DNS config
./scripts/ts-api.sh dns-nameservers     # List nameservers
./scripts/ts-api.sh magic-dns on|off    # Toggle MagicDNS
```

### ACLs

```bash
./scripts/ts-api.sh acl                 # Get current ACL
./scripts/ts-api.sh acl-validate  # Validate ACL file
```

---

## Common Use Cases

**"Who's online right now?"**
```bash
./scripts/ts-api.sh online
```

**"Send this file to my phone"**
```bash
tailscale file cp document.pdf my-phone:
```

**"Expose my dev server publicly"**
```bash
tailscale funnel 3000
```

**"Create a key for a new server"**
```bash
./scripts/ts-api.sh create-key --reusable --tags tag:server --expiry 7d
```

**"Is the connection direct or relayed?"**
```bash
tailscale ping my-server
```

---

## 🔧 Agent Tool Usage Requirements

**CRITICAL:** When invoking scripts from this skill via the zsh-tool, **ALWAYS use `pty: true`**.

Without PTY mode, command output will not be visible even though commands execute successfully.

**Correct invocation pattern:**
```typescript

./skills/SKILL_NAME/scripts/SCRIPT.sh [args]
true

```

## Source & license

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

- **Author:** [jmagar](https://github.com/jmagar)
- **Source:** [jmagar/claude-homelab](https://github.com/jmagar/claude-homelab)
- **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:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **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-jmagar-claude-homelab-tailscale
- Seller: https://agentstack.voostack.com/s/jmagar
- 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%.