tailscale-helper

name	tailscale-helper
description	Tailscale VPN and networking - CLI operations, MagicDNS, ACLs, SSH, funnel, serve, and network administration When user mentions Tailscale, tailscale commands, VPN, MagicDNS, tailnet, or Tailscale networking

Tailscale Helper Agent

What's New (2025-2026)

Tailscale Services (GA, Jan 2026) - Decouple apps from hosting devices with stable TailVIPs and MagicDNS names. Define services via API or admin console with virtual IPs auto-accepted across platforms.

Peer Relays (Beta, Oct 2025) - Use tailnet nodes as high-throughput relay servers when direct connections fail. Throughput approaches direct connections; orders of magnitude faster than managed DERP relays. Two free peer relays on all plans. Requires v1.86+.

Tailnet Lock (GA, Jun 2025) - Verify that only trusted nodes join the tailnet via cryptographic signing. Shifts trust from Tailscale coordination server to your own signing nodes.

Grants (GA, May 2025) - Unified network and application-layer access controls replacing traditional ACLs. Combine network rules with app capabilities in a single policy.

Visual Policy Editor (GA, Oct 2025) - Graphical ACL management in the admin console.

4via6 Subnet Routers (GA, Jan 2025) - Handle overlapping IPv4 subnets by mapping them through IPv6.

Fast User Switching (GA, Jan 2025) - Switch between multiple Tailscale accounts on a single device.

Node Key Sealing (GA, v1.90) - Hardware-backed node key protection on Linux, Windows, and macOS using TPM.

v1.94 Highlights: Workload identity tokens auto-generated, Peer Relay performance improvements, container/K8s Operator updates.

v1.92 Highlights: State file encryption, TPM attestation defaults, K8s workload identity federation, Funnel/Serve PROXY protocol support, network flow logs auto-recording.

Overview

Tailscale is a WireGuard-based mesh VPN that creates a secure overlay network (tailnet) connecting devices across any network topology. Every device gets a stable Tailscale IP from the CGNAT range (100.64.0.0/10) that persists regardless of physical location. Tailscale handles NAT traversal, key management, and peer discovery automatically through a coordination server, while all data flows directly between devices via encrypted WireGuard tunnels.

Public Product Reference

The upstream Tailscale skill is an Alpha reference index, not an authority for this workstation or homelab. Use references/public-product-reference.md for the broader product map (grants, device management, Kubernetes, Taildrop, Taildrive, Serve, Funnel, session recording, and tsnet) and fetch the linked official documentation when syntax or product availability may have changed.

Local rules remain mandatory: probe authentication with the exact read-only operation needed, verify live state before claiming a change worked, treat Serve/Funnel as exposure changes, and preserve the homelab's encryption and access-control requirements. Do not install or invoke an MCP server for this reference.

CLI Quick Reference

# Authentication & Connection
tailscale up                          # Connect and authenticate
tailscale up --auth-key=<key>         # Connect with pre-auth key
tailscale down                        # Disconnect from tailnet
tailscale login                       # Authenticate without connecting
tailscale logout                      # Disconnect and expire session
tailscale switch <account>            # Switch Tailscale account
tailscale switch --list               # List available accounts

# Status & Info
tailscale status                      # Show connection status
tailscale status --json               # JSON output
tailscale ip                          # Show Tailscale IP
tailscale ip --4                      # IPv4 only
tailscale ip --6                      # IPv6 only
tailscale whois <ip>                  # Identify device/user by IP
tailscale version                     # Show version
tailscale netcheck                    # Network diagnostics

# Connectivity
tailscale ping <hostname>             # Ping over Tailscale
tailscale ping --icmp <hostname>      # ICMP ping
tailscale ssh user@host               # SSH via Tailscale

# Configuration
tailscale set --hostname=<name>       # Set device hostname
tailscale set --ssh                   # Enable Tailscale SSH
tailscale set --advertise-exit-node   # Advertise as exit node
tailscale set --exit-node=<ip|name>   # Use exit node
tailscale set --advertise-routes=<cidr> # Advertise subnet routes
tailscale set --accept-routes         # Accept subnet routes
tailscale  --accept-dns            
tailscale  --shields-up            


tailscale file  <file> <host>:      
tailscale file get <>              


tailscale serve <port>                
tailscale serve --http=80 <port>      
tailscale serve status                
tailscale serve reset                 
tailscale funnel <port>               
tailscale funnel status               


tailscale drive share <name> <path>   
tailscale drive unshare <name>        
tailscale drive list                  


tailscale cert <domain>               
tailscale cert --cert-file=<f> --key-file=<f> <domain>


tailscale exit-node list              
tailscale exit-node suggest           


tailscale lock init                   
tailscale lock status                 
tailscale lock sign nodekey:<key>     
tailscale lock add tlpub:<key>        
tailscale lock remove tlpub:<key>     
tailscale lock  <secret>       


tailscale bugreport                   
tailscale bugreport --diagnose        
tailscale dns status                  
tailscale metrics                


tailscale update                      
tailscale update --dry-run            

Key Features

MagicDNS

Automatically registers DNS names for tailnet devices. Access machines by hostname (ssh user@myserver) instead of IP. Full domain: <machine>.<tailnet-name>.ts.net. Enabled by default for new tailnets.

Tailscale SSH

Replace SSH key management with identity-based access. Run tailscale set --ssh on destination, configure SSH ACLs in policy file. Supports check mode requiring periodic re-authentication.

Funnel

Expose local services to the public internet through encrypted relay. Limited to ports 443, 8443, and 10000. Traffic is end-to-end encrypted through Funnel relay servers.

Serve

Share local services within the tailnet. Supports reverse proxy, file serving, static text, and TCP forwarding. Auto-provisions HTTPS certificates. Use -bg flag for persistence across reboots.

Taildrop

Peer-to-peer encrypted file transfer between tailnet devices. Send with tailscale file cp, receive with tailscale file get.

Exit Nodes

Route all internet traffic through a designated tailnet device. Use for travel security, geo-access, or compliance. Supports Mullvad exit nodes for commercial VPN integration.

Subnet Routers

Extend tailnet to devices without Tailscale installed. Advertise routes with tailscale set --advertise-routes=<cidr>, approve in admin console or via autoApprovers.

Peer Relays

Client-to-client relay fallback when direct connections fail. Higher throughput than DERP relays. Configure with tailscale set --advertise-peer-relay.

Tailscale Services

Define stable virtual services with TailVIPs and MagicDNS names, independent of hosting devices. Supports high availability and granular access controls.

Docker & Containers

# Pull official image
docker pull tailscale/tailscale:latest

# Run with auth key
docker run -d \
  -e TS_AUTHKEY=tskey-auth-... \
  -e TS_HOSTNAME=my-container \
  -e TS_STATE_DIR=/var/lib/tailscale \
  -v ts-state:/var/lib/tailscale \
  tailscale/tailscale:latest

Key environment variables: TS_AUTHKEY, TS_HOSTNAME, TS_STATE_DIR, TS_ROUTES, TS_USERSPACE, TS_EXTRA_ARGS, TS_ACCEPT_DNS, TS_ENABLE_HEALTH_CHECK, TS_ENABLE_METRICS.

Use sidecar pattern with network_mode: service:tailscale for other containers.

ACL Policy Basics

{
  // Groups for role-based access
  "groups": {
    "group:engineering": ["[e-mail]"],
  },
  // Tag ownership
  "tagOwners": {
    "tag:server": ["group:engineering"],
  },
  // Access rules (deny-by-default)
  "acls": [
    {
      "action": "accept",
      "src": ["group:engineering"],
      "dst": ["tag:server:*"],
    },
  ],
  // SSH access
  "ssh": [
    {
      "action": 
       
       
       
    
  
  
   
        
     
  

Use huJSON format (comments and trailing commas allowed). Grants are the recommended modern alternative to ACLs.

Reference Files

• references/cli-reference.md - Complete CLI command reference with all subcommands, flags, and usage patterns
• references/networking.md - MagicDNS, subnet routers, exit nodes, DERP, NAT traversal, containers, Kubernetes
• references/acls-security.md - ACL policy syntax, grants, groups, tags, SSH ACLs, auth keys, API, Tailnet Lock

Common Troubleshooting

Issue	Command
Check connection status	tailscale status
Network diagnostics	tailscale netcheck
Test peer connectivity	tailscale ping <host>
DNS resolution issues	tailscale dns status
Generate bug report	tailscale bugreport --diagnose
Check daemon logs (Linux)	journalctl -u tailscaled
Check daemon logs (macOS)	log show --predicate 'process=="tailscaled"'
Force reconnect	tailscale down && tailscale up
Verify routes	tailscale status --json | jq '.Peer'