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 is a feature that allows you to 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 behind the scenes and how to get started with it on your tailnet. For more specific use cases, see Tailscale Serve examples.

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

Setup

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

If you do not have HTTPS enabled in your tailnet, the Tailscale CLI command tailscale serve provides an interactive web UI that will prompt you to allow Tailscale to enable HTTPS on your behalf.

The serve command will prompt you as needed and send you to a web consent page to enable any unmet requirements.

The 'Start using serve' web consent page

The Tailscale Funnel box is checked by default. If you don’t plan to use Tailscale Funnel on the device, you can uncheck it.

Run Tailscale Serve

If you run the tailscale serve command and your tailnet isn’t properly configured to use Tailscale Serve, a login server URL will be presented that can be followed to enable the feature.

Tailscale Serve lets you serve local directories, files, plain text, or local ports with other devices in your tailnet. As an 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 to see more examples.

The CLI will open a foreground session that displays the status of what’s being served 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

Identity headers are sent exclusively when serving traffic from your tailnet via Tailscale Serve. Funnel traffic, being publicly available, does not include identity headers.

When using Serve to proxy traffic to a local service running on your machine, a few Tailscale identity headers are added to the request sent to your backend. These can be used by your destination service to identify the Tailscale user associated with the request.

  • Tailscale-User-Login: Filled with the requester’s login name (e.g. alice@example.com)
  • Tailscale-User-Name: Filled with the requester’s display name (e.g. Alice Architect)
  • Tailscale-User-Profile-Pic: Filled with the requester’s profile picture URL, if their identity provider provides one (e.g. https://example.com/photo.jpg)
These headers are not filled for traffic originating from tagged devices.

The identity headers can be used by your custom backend however desired or hooked up to a number of third-party services that offer auth proxy authentication, such as Grafana.

Although headers are only filled 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, the identity headers will be filled when your friend visits the Serve URL.

When using the identity headers to authenticate to a backend service, the service should only 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 (node-name.tailnet-name.ts.net)
  • Due to macOS app sandbox limitations, serving files and directories is limited to the open source variant

Troubleshooting

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

Last updated

On This Page