home-assistant.io/source/_integrations/tailscale.markdown

title, description, ha_category, ha_release, ha_iot_class, ha_config_flow, ha_codeowners, ha_domain, ha_platforms, ha_integration_type

title	description	ha_category	ha_release	ha_iot_class	ha_config_flow	ha_codeowners	ha_domain	ha_platforms	ha_integration_type
Tailscale	Instructions on how to integrate Tailscale within Home Assistant.	Binary sensor Network Sensor	2021.12	Cloud Polling	true	@frenck	tailscale	binary_sensor diagnostics sensor	hub

The Tailscale {% term integration %} 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.

{% important %} This integration monitors your Tailscale network but does not provide VPN access to Home Assistant.

To access Home Assistant remotely via Tailscale:

1. Install Tailscale directly on your Home Assistant device
2. Follow the Tailscale installation guide
3. Configure port forwarding or use Tailscale's subnet routes if needed {% endimportant %}

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

{% include integrations/config_flow.md %}

{% configuration_basic %} API Key: description: "Your Tailscale API access token from the Admin Panel." Tailnet: description: "Your Tailnet name (organization name or email address)." {% endconfiguration_basic %}

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.

{% include integrations/remove_device_service.md %}

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