Tailscale Serve

The CLI commands for both Tailscale Funnel and Tailscale Serve have changed in the 1.52 version of the Tailscale client. If you've used Funnel or Serve in previous versions, we recommend reviewing the CLI documentation.

Tailscale Serve lets you route traffic from other devices on your Tailscale network (known as a tailnet) to a local service running on your device. You can think of this as sharing the service, such as a website, with the rest of your tailnet. This page provides information about how Serve works and how to get started with it in your tailnet. For more specific use cases, refer to Tailscale Serve examples.

If you'd like to share local services publicly over the internet, use Tailscale Funnel instead.

Get started with Serve

Tailscale Serve requires you to enable HTTPS certificates in your tailnet.

If you don't have HTTPS enabled in your tailnet, the Tailscale CLI command tailscale serve provides an interactive web UI that prompts you to allow Tailscale to enable HTTPS on your behalf.

The serve command prompts you as needed and sends you to a web consent page to enable any unmet requirements.

The 'Start using serve' web consent page

Tailscale Funnel is enabled by default. If you don't plan to use Tailscale Funnel on the device, you can turn it off.

Run Tailscale Serve

If you run the tailscale serve command and your tailnet isn't properly configured to use Tailscale Serve, it presents a login server URL that you can follow to enable the feature.

Tailscale Serve lets you serve local directories, files, plain text, or local ports with other devices in your tailnet. For example, you can proxy requests to a web server running at http://127.0.0.1:3000 using the following command:

tailscale serve 3000

Run tailscale serve --help for more examples.

The CLI opens a foreground session that displays the status of what it's serving and the URL you can use to access your server:

tailscale serve 3000
Available within your tailnet:
https://amelie-workstation.pango-lin.ts.net

|-- / proxy http://127.0.0.1:3000

Press Ctrl+C to exit.

Identity headers

Serve traffic includes identity headers when serving traffic from your tailnet using Tailscale Serve. Funnel traffic, which is publicly available, does not include identity headers.

When you use Serve to proxy traffic to a local service running on your device, it adds a few Tailscale identity headers to the request sent to your backend. The destination server can use these headers to identify the Tailscale user associated with the request.

Tailscale-User-Login: Filled with the requester's login name (for example, alice@example.com).
Tailscale-User-Name: Filled with the requester's display name (for example, Alice Architect).
Tailscale-User-Profile-Pic: Filled with the requester's profile picture URL, if their identity provider provides one (for example, https://example.com/photo.jpg)..

If the values contain non-ASCII values, Tailscale might use RFC2047 "Q" encoding (for example, =?utf-8?q?Ferris_B=C3=BCller?=).

These identity headers are not populated for traffic originating from tagged devices.

You can use the identity headers with a custom backend or third-party services that offer authentication proxy authentication, such as Grafana.

Although identity headers are only populated for tailnet traffic, this includes traffic from external users who have accepted a share of your device. For example, if you share a device with a friend and have it configured with a Serve proxy, Tailscale populates the identity headers when your friend visits the Serve URL.

When you use the identity headers to authenticate to a backend service, it's best practice to only have the service listen on localhost. Otherwise, any user that can call your service directly (rather than with the Serve URL) could trivially provide their own values for these HTTP headers. By listening only on localhost, this limits tampering to only other services running on the Serve machine, and not anyone on your LAN or tailnet.

Limitations

DNS names are restricted to your tailnet's domain name (device-name.tailnet-name.ts.net).
Because of macOS app sandbox limitations, serving files and directories is limited to the open source variant of the Tailscale client for macOS.

Troubleshooting

Tailscale Serve requires that you enable HTTPS in your tailnet to automatically provision TLS certificates for your unique tailnet DNS name. If you use the interactive CLI flow as described in the Get started with Serve section, Tailscale automatically enables HTTPS if it is not already enabled.