{"slug":"using-tailscale-with-captive-portals","title":"Using Tailscale with captive portals","tags":["tailscale"],"agent_summary":"Last validated: Dec 10, 2025","trigger_phrases":[],"runnable":false,"markdown":"\r\n# Using Tailscale with captive portals\r\n\r\nLast validated: Dec 10, 2025\r\n\r\nWhen you connect to a public network, you might be redirected to a [captive portal](https://en.wikipedia.org/wiki/Captive_portal) requiring you to authenticate or accept terms before accessing the internet.\r\n\r\nA captive portal typically appears before the user can access any other web pages, and often includes login forms, payment options, or advertisements. Captive portals are commonly used in public Wi-Fi hotspots such as those found in airports, hotels, coffee shops, libraries, and other public venues. They are also frequently implemented in corporate environments and educational institutions to ensure only users with credentials can connect to the network.\r\n\r\nIf you connect your device to a captive portal and do not complete the authentication steps, Tailscale cannot establish a connection to the coordination server, and connectivity with other devices in your tailnet is not possible.\r\n\r\n## [Captive portal notifications](https://tailscale.com/docs/integrations/captive-portals\\#captive-portal-notifications)\r\n\r\nCaptive portal notifications are currently only supported on macOS and iOS. Notification permissions must be granted for the Tailscale client in order for notifications to appear.\r\n\r\nIn Tailscale v1.72 or later, a notification will appear on your device when a captive portal is detected:\r\n\r\n![Notification informing the user about the presence of a captive portal on macOS](https://tailscale.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fcaptive-portal-notification.dfd52e9a.png&w=828&q=75)\r\n\r\nOn platforms where the [Tailscale CLI](https://tailscale.com/docs/reference/tailscale-cli) is available, the `tailscale status` command will also include a health warning:\r\n\r\n```shell\r\ntailscale status\r\n```\r\n\r\nThis command should output the following:\r\n\r\n```shell\r\n# Health check:\r\n# - This network requires you to log in using your web browser.\r\n```\r\n\r\nTo resolve the issue, complete the necessary authentication steps in your web browser by attempting to access a website such as [`example.com`](http://www.example.com/).\r\n\r\n## [How Tailscale detects captive portals](https://tailscale.com/docs/integrations/captive-portals\\#how-tailscale-detects-captive-portals)\r\n\r\nCaptive portal detection requires Tailscale v1.72 or later.\r\n\r\nAlthough a number of [standards](https://www.rfc-editor.org/rfc/rfc8952.html) have been proposed over the years, captive portals are implemented differently by each networking equipment manufacturer or ISP. Due to the lack of a uniform standard, there is no widely used protocol to reliably detect a captive portal. The Tailscale client detects captive portals continuously in the background, on a best-effort basis, by performing these steps:\r\n\r\n1. The client continuously observes the state of network interfaces and connections to the Tailscale [coordination server](https://tailscale.com/docs/reference/glossary#coordination-server) and [relay servers](https://tailscale.com/docs/reference/derp-servers). If a connectivity issue is observed, the captive portal detection process starts. Captive portal detection does not run unless a connectivity issue is observed.\r\n2. Tailscale attempts to contact a set of relay servers that are known to accept incoming connections on TCP port `80`. The client executes an unencrypted HTTP request reaching out to a `/generate_204` endpoint on the relay server. This endpoint is expected to return an HTTP response with a 204 status code.\r\n3. Because [DNS resolution](https://tailscale.com/docs/reference/dns-in-tailscale) is unreliable behind some captive portals, Tailscale reaches out to the relay server by directly using its IPv4 address. For instance, the outgoing HTTP request may target a relay server at `http://123.12.12.123/generate_204`.\r\n4. As part of the HTTP request above, Tailscale may also send a challenge in the HTTP headers of the request (`X-Tailscale-Challenge`), if the relay server supports the challenge protocol. This challenge header value is `ts_`, where `` is the hostname of the relay server being used.\r\n5. The HTTP request is sent, and the status code and headers of the HTTP response are evaluated.\r\n\r\n- If the status code is `204` and the `X-Tailscale-Response` is `response ts_`, Tailscale assumes that no captive portal has been detected.\r\n- If `X-Tailscale-Response` is missing from the response, or has an unexpected value, or the return status code is not `204`, Tailscale infers that something is tampering with the HTTP connection, and therefore a captive portal is likely present.\r\n\r\n## [Disable captive portal detection](https://tailscale.com/docs/integrations/captive-portals\\#disable-captive-portal-detection)\r\n\r\nYou can turn off captive portal detection if you always use your computer in the same location or want to avoid detection-related traffic to our servers by configuring the `disable-captive-portal-detection` [node attribute](https://tailscale.com/docs/reference/syntax/policy-file#nodeattrs) in your tailnet [access control policies](https://tailscale.com/docs/features/access-control):\r\n\r\n```json\r\n{\r\n \"nodeAttrs\": [\\\r\n {\\\r\n \"target\": [\\\r\n \"autogroup:member\"\\\r\n ],\\\r\n \"attr\": [\\\r\n \"disable-captive-portal-detection\"\\\r\n ]\\\r\n }\\\r\n ]\r\n}\r\n```\r\n\r\nYou can use the [visual policy editor](https://tailscale.com/docs/features/visual-editor) to manage your tailnet policy file. Refer to the [visual editor reference](https://tailscale.com/docs/reference/visual-editor) for guidance on using the visual editor.\r\n\r\n![Project Logo](https://cdn.brandfetch.io/tailscale.com/fallback/lettermark/theme/dark/h/256/w/256/icon?c=1bfwsmEH20zzEfSNTed)\r\n\r\nAsk AI\r\n\r\nreCAPTCHA\r\n\r\nRecaptcha requires verification.\r\n\r\nprotected by **reCAPTCHA**\r\n","html":"

Using Tailscale with captive portals

\n

Last validated: Dec 10, 2025

\n

When you connect to a public network, you might be redirected to a captive portal requiring you to authenticate or accept terms before accessing the internet.

\n

A captive portal typically appears before the user can access any other web pages, and often includes login forms, payment options, or advertisements. Captive portals are commonly used in public Wi-Fi hotspots such as those found in airports, hotels, coffee shops, libraries, and other public venues. They are also frequently implemented in corporate environments and educational institutions to ensure only users with credentials can connect to the network.

\n

If you connect your device to a captive portal and do not complete the authentication steps, Tailscale cannot establish a connection to the coordination server, and connectivity with other devices in your tailnet is not possible.

\n

Captive portal notifications

\n

Captive portal notifications are currently only supported on macOS and iOS. Notification permissions must be granted for the Tailscale client in order for notifications to appear.

\n

In Tailscale v1.72 or later, a notification will appear on your device when a captive portal is detected:

\n

\"Notification

\n

On platforms where the Tailscale CLI is available, the tailscale status command will also include a health warning:

\n
tailscale status\n
\n

This command should output the following:

\n
# Health check:\r\n#     - This network requires you to log in using your web browser.\n
\n

To resolve the issue, complete the necessary authentication steps in your web browser by attempting to access a website such as example.com.

\n

How Tailscale detects captive portals

\n

Captive portal detection requires Tailscale v1.72 or later.

\n

Although a number of standards have been proposed over the years, captive portals are implemented differently by each networking equipment manufacturer or ISP. Due to the lack of a uniform standard, there is no widely used protocol to reliably detect a captive portal. The Tailscale client detects captive portals continuously in the background, on a best-effort basis, by performing these steps:

\n
    \n
  1. The client continuously observes the state of network interfaces and connections to the Tailscale coordination server and relay servers. If a connectivity issue is observed, the captive portal detection process starts. Captive portal detection does not run unless a connectivity issue is observed.
    2. \n
  2. Tailscale attempts to contact a set of relay servers that are known to accept incoming connections on TCP port 80. The client executes an unencrypted HTTP request reaching out to a /generate_204 endpoint on the relay server. This endpoint is expected to return an HTTP response with a 204 status code.
    3. \n
  3. Because DNS resolution is unreliable behind some captive portals, Tailscale reaches out to the relay server by directly using its IPv4 address. For instance, the outgoing HTTP request may target a relay server at http://123.12.12.123/generate_204.
    4. \n
  4. As part of the HTTP request above, Tailscale may also send a challenge in the HTTP headers of the request (X-Tailscale-Challenge), if the relay server supports the challenge protocol. This challenge header value is ts_<hostname>, where <hostname> is the hostname of the relay server being used.
    5. \n
  5. The HTTP request is sent, and the status code and headers of the HTTP response are evaluated.
    6. \n
\n
    \n
  • If the status code is 204 and the X-Tailscale-Response is response ts_<hostname>, Tailscale assumes that no captive portal has been detected.
    • \n
  • If X-Tailscale-Response is missing from the response, or has an unexpected value, or the return status code is not 204, Tailscale infers that something is tampering with the HTTP connection, and therefore a captive portal is likely present.
    • \n
\n

Disable captive portal detection

\n

You can turn off captive portal detection if you always use your computer in the same location or want to avoid detection-related traffic to our servers by configuring the disable-captive-portal-detection node attribute in your tailnet access control policies:

\n
{\r\n  \"nodeAttrs\": [\\\r\n    {\\\r\n      \"target\": [\\\r\n        \"autogroup:member\"\\\r\n      ],\\\r\n      \"attr\": [\\\r\n        \"disable-captive-portal-detection\"\\\r\n      ]\\\r\n    }\\\r\n  ]\r\n}\n
\n

You can use the visual policy editor to manage your tailnet policy file. Refer to the visual editor reference for guidance on using the visual editor.

\n

\"Project

\n

Ask AI

\n

reCAPTCHA

\n

Recaptcha requires verification.

\n

protected by reCAPTCHA

\n"}