unbraid

Guides · Published · Updated on

Connect Android to your Headscale server

To connect an Android phone to Headscale, install the Tailscale app, open its account menu, choose Use an alternate server, and enter your server’s https:// address. Then either approve the phone on the server, or sign in with a pre-authenticated key created there.

What Headscale is

Headscale is an open source, self-hosted version of the control server that Tailscale runs for its own users. The control server doesn’t carry your traffic. It hands out addresses and keys, tells each device which others exist, and sends out DNS and route settings. The devices then talk to each other directly where they can.

The project’s README says it covers a single tailnet, meant for personal use or a small organisation, and that it isn’t associated with Tailscale Inc. It uses the normal Tailscale clients, which is why an Android phone can join with the Tailscale app. Features that depend on Tailscale’s hosted service, such as its admin console, aren’t there. You manage Headscale through its command line tool and set access rules in its policy.

Connecting the Tailscale app

Headscale’s Android page describes two ways in. Tailscale’s own page on custom control servers describes the same option with slightly different wording: tap the profile icon in the top-right corner to open settings, tap Log in or the signed-in user, open the menu, choose Use an alternate server, enter the URL and tap Log in. Menu names belong to the Tailscale app and differ between versions, so if one doesn’t match, trust what your screen shows.

With a browser sign-in

  1. Open the Tailscale app, then its settings menu in the upper-right corner.
  2. Tap Accounts.
  3. Tap the three-dot menu in the upper-right corner and choose Use an alternate server.
  4. Enter your server URL, for example https://headscale.example.com, and follow the instructions.

The phone opens a page that shows a registration command with an ID in it. On the server you approve the phone with headscale auth register --user <USER> --auth-id <AUTH_ID> (getting started). The Headscale page notes that the app connects by itself once registration completes, and that nothing shows in the server’s logs until then.

With a pre-authenticated key

  1. Do steps 1 to 4 above. If a sign-in page opens, close it and carry on.
  2. Open the settings menu again and tap Accounts.
  3. Tap the three-dot menu and choose Use an auth key.
  4. Paste the key. If needed, tap Log in on the main screen.

If the server is offline and you can’t log out of it, Tailscale’s page says to clear the Tailscale app’s stored data (in Android’s own settings, under the app’s storage). That resets the app’s local state, so use it only when you have to.

Pre-auth key or interactive login

With manual registration you approve each new device on the server, which is fine for one phone and tedious for ten. If your Headscale uses OpenID Connect, people sign in through that identity provider instead (registration methods). A pre-authenticated key lets the phone register without anyone at the server. You create one with:

headscale preauthkeys create --user <USER_ID>

By default the key is valid for one hour and works once, so an expired or already used key is refused. headscale preauthkeys --help lists the options for a longer life or a key that several devices can use. Treat a reusable key like a password: anyone who has it can add a device to your tailnet until it expires.

Users must exist first (headscale users create <USER>), and the key belongs to one of them. That user then owns the device.

Manual registration Pre-auth key
Needs the server’s command line Once per device, after the phone asks Once, before you set up the phone
Typing on the phone The server address The server address and the key
Works if the key expires before use Not applicable No, create a new one

HTTPS and certificates

Headscale itself can run without TLS, and its TLS page calls TLS optional. The examples in its Android and getting-started pages all use https://. A phone away from your home network needs a network path to the server, and for that you want HTTPS with a certificate the Tailscale client trusts. Either Headscale gets one itself with Let’s Encrypt, or a reverse proxy in front of it does.

If you supply your own certificate, it must contain the full chain. The page says some clients, the Tailscale Android client among them, reject it otherwise. And with Let’s Encrypt, the hostname must resolve to the server and match server_url, HTTP-01 needs inbound port 80 and TLS-ALPN-01 needs inbound port 443.

Headscale’s docs don’t cover self-signed certificates. Use a certificate the Tailscale client trusts, with its full chain. Installing a certificate on the phone doesn’t necessarily make the app trust it, because Android apps don’t automatically trust user-installed authorities (Android’s network security configuration). Open https://your-server/health in the phone’s browser to check that the server answers; Headscale’s getting-started page uses that address for the same purpose. A certificate warning there needs sorting out, and a clean result doesn’t prove the app can connect.

Names on a Headscale domain

MagicDNS gives each device a name under a base domain you choose. Headscale’s example configuration describes it like this: with magic_dns on and base_domain set to example.com, a device called laptop is reachable as laptop.example.com.

  • The base domain can’t contain your server’s address. The host in server_url must not be the base domain or a name below it, because clients take the domain over. With server_url set to headscale.example.com, a base domain of example.com breaks it, while tailnet.example.com is fine. Use the example configuration that matches your installed Headscale release, since defaults differ between versions.
  • Clients apply the DNS settings only if they accept them. That is the default for the Tailscale clients, as the example configuration notes.
  • override_local_dns makes clients use the nameservers you list in place of their local DNS settings. Without any global nameserver, there’s nothing to override with and clients keep their own.

Headscale can also hand out extra records with dns.extra_records, so grafana.tailnet.example.com can point at a device’s tailnet address. Its DNS page says Tailscale clients only process A and AAAA records.

An app that uses its own DNS resolver may bypass your tailnet’s DNS settings. Trying the device’s tailnet address separates a name problem from a connection problem.

Exit nodes and subnet routers

A device can offer to carry other devices’ internet traffic (an exit node) or to reach a network behind it (a subnet router). With Headscale, offering isn’t enough. The server has to approve the routes, as the routes page explains.

On the device that offers, for an exit node:

sudo tailscale up --login-server <YOUR_HEADSCALE_URL> --advertise-exit-node

For a subnet router, add --advertise-routes=192.168.0.0/24 with your own range. Both need IP forwarding on that device. Then, on the server:

headscale nodes list-routes
headscale nodes approve-routes --identifier <NODE_ID> --routes 0.0.0.0/0

Use the node ID that list-routes shows. The command sets the approved list for that node, so include every route that should stay approved, separated by commas.

An exit node shows 0.0.0.0/0 and ::/0 in the list, and approving one of them is enough, because the other is approved with it. For a subnet router, approve the range it offered. Headscale can approve routes automatically for tagged devices through its policy file. Other tailnet devices that should use the routes may need to accept them, which on a computer is tailscale set --accept-routes.

Tailscale’s own exit node page says an Android device that serves as an exit node is limited to userspace routing and may be too slow for most uses.

What goes wrong

What you see Likely cause
Nothing in the server’s logs Logs can stay empty until registration finishes, per Headscale’s Android page. Check that the server is reachable, then finish the approval or identity provider sign-in
Browser warns about the certificate Incomplete chain, a name that doesn’t match server_url, or a self-signed certificate
The pre-auth key is refused It expired (one hour by default), was already used once, or was created for a different server
The phone is in the tailnet but a name doesn’t resolve The base domain, DNS settings not accepted, or an app doing its own lookups. Try the device’s address
An exit node or subnet doesn’t show up The router isn’t advertising the routes, the server hasn’t approved them, or your policy doesn’t allow access
You changed servers and the old one still lists the phone The phone’s entry stays on the old server until you remove it there
A device can’t be reached even though it is listed The device is asleep or offline, or its own firewall or Headscale’s policy blocks the connection

Headscale in unbraid

unbraid is a split tunneling VPN client for Android: you bring your own provider account or server, and each app can leave through its own exit. Android allows one VPN connection at a time, and the Tailscale app uses it, so the Tailscale app can’t stay on next to a VPN app. unbraid includes a Tailscale client, which is how an app can reach your tailnet while its internet traffic goes out through a VPN exit.

  1. Open Settings, then Tailscale, and turn on Reach your tailnet.
  2. Open Advanced settings, then Control server. Enter the address of your server. It has to be a full https:// address: an invalid one turns Save off and shows “Use a full https:// address”.
  3. If you made a pre-authenticated key, enter it under Auth key (optional) in the same box.
  4. Tap Save, go back to Routes and connect unbraid. Without a key, tap Sign in to Tailscale when it appears and finish registration in your browser.

Changing the control server or entering a new auth key stops unbraid and resets its Tailscale sign-in, so the next connection registers the phone afresh. A sign-in link to your control server’s own host opens without an extra prompt, a link to another host asks first, and a link that isn’t a secure web address is refused.

Device names. Under Advanced settings, once unbraid has learned your server’s domain, a switch called Device names under that domain appears. It starts off. Turning it on lets your server answer every lookup under that domain, and nothing else: unbraid doesn’t adopt Headscale’s global DNS servers or other zones. Because a Headscale server can name any domain, unbraid wants your say-so before it trusts it. Changing the control server turns it off again.

Exit nodes. The Exit nodes list under Tailscale shows each node, whether it is online and how many routes use it. You pick one for a route in Routes, with +, Route, then Own servers. Tailscale uses one exit node at a time, so all your Tailscale routes share it. Choosing another replaces the first. To reach a whole network behind a subnet router, add its ranges under Local & home access, Advanced settings, Home subnets through Tailscale, and approve them on the server as described above.

Tailscale and a VPN at the same time on Android covers the whole tailnet setup, and A Tailscale exit node for some apps on Android covers sending chosen apps through a home exit.

Questions

Can I use the Tailscale app and Headscale for some devices and Tailscale’s own service for others? Different devices can use different control servers. On one phone only one tailnet is active at a time, and Tailscale lets you switch between saved accounts without signing in again while their keys remain valid.

Does Headscale work without a public address? The Headscale docs list being reachable from the internet as a prerequisite. A server that only answers on your home network works for devices on that network and not for a phone on mobile data, unless the phone first reaches that network some other way.

Is a pre-auth key safer than an interactive login? They do different jobs. An interactive login puts a person at the server for each device, which is a check. A key saves that step, so how well you guard the key decides how safe it is. A one-use key that expires in an hour limits the damage if it leaks.

Bring your own VPN

unbraid is a VPN client with no servers of its own. You sign in with an account you already have, or add your own server. It has built-in support for AirVPN, ExpressVPN, IVPN, Mullvad, NordVPN (affiliate link), Private Internet Access, Proton VPN (Free included), Surfshark and Windscribe. For CyberGhost, you import config files from your account, with step-by-step help in the app.

We earn a commission if you subscribe through a link marked (affiliate link). It helps keep unbraid free. If you're about to subscribe to a VPN service, thank you for considering doing it through one of them.