Tailscale

The Tailscale integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] monitors the devices in your Tailscale network (Tailnet) from Home Assistant. Tailscale is a VPN service that creates secure connections between your devices using WireGuard.

For each device in your Tailnet, the integration shows details such as when the device was last seen, its Tailscale IP address, when its key expires, and whether a client update is available. You can use this to keep an eye on your network, or to get notified when a device needs attention, such as an update or an expiring key.

Prerequisites

To set up the integration, you need two things from the Tailscale admin console:

• API access token: Create one under Settings > Keys in the admin console. Select Generate access token, then copy the token. Tailscale API access tokens are valid for 90 days, after which Home Assistant asks you to enter a new one.
• Tailnet name: The name of your Tailscale network. You can find it in the top-left corner of the admin console, next to the Tailscale logo. It is usually an email address or an organization name.

Configuration

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

Supported functionality

The integration creates a device in Home Assistant for each device in your Tailnet, with the following entities.

Sensors

• Last seen: The date and time the device was last seen on your Tailnet.
• IP address: The Tailscale IP address of the device.
• Expires: The date and time the device’s key expires.

Binary sensors

• Client: Whether a Tailscale client update is available for the device.
• Key expiry disabled: Whether key expiry is turned off for the device, meaning its key does not expire.
• Supports IPv6: Whether the device’s client supports IPv6.
• Supports UDP: Whether the device’s client supports UDP.
• Supports UPnP: Whether the device’s client supports UPnP.
• Supports NAT-PMP: Whether the device’s client supports NAT-PMP.
• Supports PCP: Whether the device’s client supports PCP.

Examples

Notify when a Tailscale client update is available

Send a notification when an update becomes available for one of your devices, so you can keep your Tailscale clients up to date:

alias: "Tailscale update available"
triggers:
  - trigger: state
    entity_id: binary_sensor.work_laptop_client
    to: "on"
actions:
  - action: notify.send_message
    target:
      entity_id: notify.my_device
    data:
      title: "Tailscale"
      message: "A Tailscale client update is available for the work laptop."

Data updates

The integration pollsData polling is the process of querying a device or service at regular intervals to check for updates or retrieve data. By defining a custom polling interval, you can control how frequently your system checks for new data, which can help optimize performance and reduce unnecessary network traffic. [Learn more] the Tailscale API every minute for the latest device and network information.

Known limitations

• The integration is read-only. You cannot change devices or your Tailnet from Home Assistant.
• There is no online or offline sensor for devices. To tell whether a device is currently connected, use the Last seen sensor.
• Tailscale API access tokens are valid for 90 days. When a token expires, the integration stops updating and asks you to enter a new token.

Troubleshooting

Integration fails to connect

If setup fails with a connection or authentication error:

1. Make sure the API access token is copied correctly, without extra spaces.
2. Check that the token has not expired. Tailscale API access tokens are valid for 90 days. Create a new one in the Tailscale admin console if needed.
3. Confirm that the Tailnet name matches the one shown in the top-left corner of the admin console.
4. Make sure your Home Assistant instance can reach the internet.

Removing the integration

This integration follows standard integration removal. No extra steps are required.

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.

Removing the integration does not revoke your Tailscale API access token. If you no longer need it, revoke it in the Tailscale admin console.