major-ai-skills/skills/tailscale/gpt.md

Installable agentic skills / AI agent skills (SKILL.md) for Claude Code, Cursor, Codex CLI, Gemini CLI & Antigravity - 402+ professional app, token-efficiency, and common-sense skills. SEO/GEO ready.

---

title: "Tailscale Mesh VPN AI Skill Guide (GPT & Codex)"
description: "Comprehensive operational skill specification for OpenAI GPT and Codex to automate, script, troubleshoot, and optimize Tailscale Local API, Tailscale REST API, Headscale self-hosting, and Terraform provisioning."
category: "Zero-Config Mesh VPN & Mesh Networking"
tags: ["tailscale", "tailscale-api", "headscale", "terraform-tailscale", "gpt-codex", "mesh-automation"]
---


# Tailscale Mesh VPN AI Skill Guide (GPT & Codex)

## Overview & Engine Architecture
Tailscale provides rich programmatic control via the **Tailscale Local Client API (Unix Domain Socket / Windows Named Pipe)** and the **Tailscale SaaS REST API**. GPT/Codex acts as a Principal Network DevOps Engineer and Automation Architect, delivering **Python Local API socket scripts**, **Terraform Tailscale provider automation**, **Headscale self-hosted control-plane management**, and **automated zero-touch container provisioning**.

### Architecture & Local API Socket Stack

```
┌─────────────────────────────────────────────────────────────┐
│                 Tailscale Developer Platform                │
│                                                             │
│  API Integration Layer                                      │
│  ├── Local Client API (Unix Domain Socket `/var/run/...`)   │
│  ├── SaaS REST API (OAuth2 Client Credentials & API Keys)   │
│  └── Terraform Provider (`tailscale/tailscale`)             │
│                                                             │
│  Node Automation & Coordination                             │
│  ├── Ephemeral Auth Key Generation & Auto-Tagging           │
│  ├── Headscale Open-Source Coordination Engine Support      │
│  └── Docker Container VPN Sidecar Pattern (`tailscale/tailscale`)│
└─────────────────────────────────────────────────────────────┘
```

---


## Operational Capabilities & Agent Directives

1. **Local Socket API Programming**: Author Python scripts communicating with `tailscaled.sock` via Unix domain sockets to query live peers, active IP addresses, and DERP maps without invoking CLI subprocesses.
2. **Terraform Infrastructure as Code (IaC)**: Write declarative Terraform configurations managing Tailscale ACL policies, DNS nameservers, device authorization, and OAuth clients.
3. **Headscale Self-Hosted Deployment**: Deploy and configure open-source `headscale` servers, registering nodes via pre-authenticated namespaces.
4. **Container VPN Sidecar Architecture**: Build Docker Compose setups routing microservice traffic securely through a Tailscale container sidecar using `network_mode: "service:tailscale"`.

---


## Production Python Automation: Tailscale Local Daemon Socket Client

Run this Python script to query node status, peers, and DERP latency directly through the local `tailscaled` Unix domain socket:

```python
"""
Tailscale Local Socket API Client
Communicates directly with the tailscaled daemon via Unix domain socket.
"""

import sys
import os
import json
import socket
import http.client

class UnixSocketHTTPConnection(http.client.HTTPConnection):
    def __init__(self, socket_path):
        super().__init__("localhost")
        self.socket_path = socket_path

    def connect(self):
        self.sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
        self.sock.connect(self.socket_path)

def query_tailscale_local_api(socket_path: str = "/var/run/tailscale/tailscaled.sock"):
    if not os.path.exists(socket_path):
        print(f"Error: Tailscale daemon socket '{socket_path}' not found.")
        return

    conn = UnixSocketHTTPConnection(socket_path)
    # The Local API expects a dummy Host header and an empty path for status
    conn.request("GET", "/localapi/v0/status", headers={"Host": "local-tailscaled.sock"})
    
    response = conn.getresponse()
    if response.status != 200:
        print(f"Error from Local API: {response.status} {response.reason}")
        return

    status_data = json.loads(response.read().decode("utf-8"))
    
    # Extract Node Information
    self_node = status_data.get("Self", {})
    node_name = self_node.get("HostName")
    tailscale_ips = self_node.get("TailscaleIPs", [])
    online = status_data.get("BackendState")

    print(f"--- [TAILSCALE NODE STATUS] ---")
    print(f"Hostname: {node_name} | State: {online}")
    print(f"Tailscale IPs: {', '.join(tailscale_ips)}")

    peers = status_data.get("Peer", {})
    print(f"\nConnected Mesh Peers ({len(peers)}):")
    for peer_key, peer_info in peers.items():
        peer_name = peer_info.get("HostName")
        peer_ips = peer_info.get("TailscaleIPs", [])
        active = peer_info.get("Active", False)
        relay = peer_info.get("Relay", "direct")
        print(f"  • {peer_name:<20} | IP: {peer_ips[0] if peer_ips else '-':<15} | Direct: {not bool(relay)} | Relay: {relay}")

if __name__ == "__main__":
    query_tailscale_local_api()
```

---


## Production Docker Compose: Containerized Tailscale Sidecar Proxy

Save this file as `docker-compose.yml` to securely route a web application through Tailscale:

```yaml
version: "3.8"

services:
  # Tailscale Network Sidecar
  tailscale:
    image: tailscale/tailscale:latest
    container_name: tailscale-sidecar
    hostname: production-app-node
    environment:
     - TS_AUTHKEY=tskey-auth-xxxxxx-ephemeral
     - TS_STATE_DIR=/var/lib/tailscale
     - TS_USERSPACE=false
    volumes:
     - ./tailscale_state:/var/lib/tailscale
     - /dev/net/tun:/dev/net/tun
    cap_add:
     - NET_ADMIN
     - SYS_MODULE
    restart: unless-stopped

  # Internal Web Application (Shares network stack with Tailscale)
  app:
    image: node:20-alpine
    container_name: internal-app
    network_mode: "service:tailscale"
    depends_on:
     - tailscale
    command: ["node", "-e", "require('http').createServer((r,s)=>s.end('Hello from secure Tailscale mesh!')).listen(8080)"]
```

---


## Technical Troubleshooting Matrix

| Issue & Failure Signature | Root Cause Analysis | Diagnostic & Resolution Pathway |
| :--- | :--- | :--- |
| **`Permission Denied` Connecting to `/var/run/tailscale/tailscaled.sock`** | Current user is not in the `tailscale` group or lacks root permissions to access the daemon socket. | 1. Add user to operator group: `sudo tailscale set --operator-group=$USER`.<br>2. Or execute script as root / `sudo`. |
| **Ephemeral Container Nodes Accumulating in Admin Console** | Docker container restarted with new machine key without deleting old node registration. | 1. Use pre-authenticated ephemeral keys (`tskey-auth-...` with Ephemeral checked).<br>2. Ephemeral nodes automatically deregister immediately when taken offline. |
| **`Error: /dev/net/tun not found` in Docker** | Docker host does not have the TUN kernel module loaded or container lacks `cap_add: [NET_ADMIN]`. | 1. On host, run `sudo modprobe tun`.<br>2. Ensure `volumes: ["/dev/net/tun:/dev/net/tun"]` is mounted. |
| **Headscale Client Fails: `node not registered`** | Client attempted authentication against a non-existent user namespace on Headscale. | 1. On Headscale server: `headscale users create default`.<br>2. Generate auth key: `headscale preauthkeys create -u default --reusable`. |

---


## Command Line Syntax & Batch Execution

```bash
# Register Node against Self-Hosted Headscale Control Server
sudo tailscale up --login-server https://headscale.mycompany.com --authkey <KEY>

# Set Non-Root Operator Permissions for CLI
sudo tailscale set --operator=$USER
```

### Essential File Locations
- **Daemon Socket**: `/var/run/tailscale/tailscaled.sock`
- **Daemon State**: `/var/lib/tailscale/tailscaled.state`
- **Windows Named Pipe**: `\\.\pipe\ProtectedPrefix\Administrators\Tailscale\tailscaled`

---


## Agent Operational Directive
> **MANDATORY**: For Docker and ephemeral cloud deployments, always generate pre-authenticated Ephemeral auth keys so offline instances automatically clean up from the Admin Console. Use container sidecar network sharing (`network_mode: "service:tailscale"`).