Tailscale

The Tailscale integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] connects to the Tailscale API to monitor devices in your Tailscale network (Tailnet). Use this integration to create automations based on device connectivity, track usage patterns, or receive notifications when devices go online or offline.

Tailscale is a VPN service that creates secure point-to-point connections between your devices using WireGuard technology. This integration monitors your Tailnet but doesn’t provide VPN connectivity itself.

Prerequisites

Required information:

1. API Access Token: Create one in the Tailscale Admin Panel

   • Navigate to Settings > Keys
   • Click Generate auth key or Generate API key
   • Select appropriate expiration and permissions

2. Tailnet Name: Found in the top-left corner of the Admin Panel

   • Usually in the format: user@domain.com or organization-name
   • Also visible in the URL when browsing your admin panel

Configuration

To add the Tailscale hub to your Home Assistant instance, use this My button:

Supported functionality

Sensors

The integration provides sensors for monitoring your Tailscale network:

Device information sensors

• Device count: Total number of devices in your Tailnet
• Connected devices: Number of currently online devices
• Disconnected devices: Number of currently offline devices

Per-device sensors

For each device in your Tailnet:

• Connection status: Whether the device is online or offline
• Last seen: Timestamp when the device was last active
• Operating system: Device OS (Windows, macOS, Linux, iOS, Android)
• Tailscale version: Version of Tailscale client running
• IP addresses: Both Tailscale IP and external IP
• Location: Approximate geographic location (if available)

Binary sensors

The integration creates binary sensors for:

Network status

• Tailnet health: Overall network connectivity status
• Device reachability: Per-device online/offline status

Security monitoring

• Key expiration warnings: Alerts when auth keys are approaching expiration
• Unauthorized access: Notifications for new device connections (if configured)

Examples

Automated backups based on device availability

Start backups when specific devices are online:

automation:
  - alias: "Start backup when work laptop connects"
    triggers:
      - trigger: state
        entity_id: binary_sensor.work_laptop_tailscale
        from: "off"
        to: "on"
    conditions:
      - condition: time
        after: "18:00:00"  # Only after work hours
        before: "23:00:00"
    actions:
      - action: script.start_network_backup
      - action: notify.admin
        data:
          message: "Starting automated backup - work laptop detected"

Data updates

The Tailscale integration polls the Tailscale API every minute to check device status and network information.

Troubleshooting

Integration fails to connect

Symptom: “Unable to connect to Tailscale API” error

Solutions:

1. Verify API key:

   • Ensure the key is copied correctly (no extra spaces)
   • Check key hasn’t expired in the Tailscale admin panel
   • Verify key has appropriate permissions

2. Network connectivity:

   • Ensure Home Assistant can reach Tailscale’s API servers
   • Check firewall rules if running in restricted environments

Removing the integration

This integration follows standard integration removal.

To remove an integration instance from Home Assistant

1. Go to Settings > Devices & services and select the integration card.
2. From the list of devices, select the integration instance you want to remove.
3. Next to the entry, select the three dots menu. Then, select Delete.

After removal:

1. Your Tailscale API key remains active
2. Consider revoking the key in the Tailscale admin panel if no longer needed
3. Your Tailscale network and devices continue operating normally