Trouble with Headscale & Headscale Admin install and config

[Builder-DE-TH]

Spent last night trying to get Headscale & Headscale Admin to work without success.

It appears that the advanced install has the default for TUN set to OFF for some reason and the headscale application silently fails to start.

Trying to add TUN to an existing LXC config causes the container to fail to restart.

Destroying the container and doing a fresh install with TUN set to ON results in the dreaded githib limit reppearing for the 1st time in a week and adding a github pat token as prompted fails to resolve it and the install fails.

Also it's not clear as to whether the headscale admin should be configured from the IP or the FQDN or whether it matters.

It's an important app for homelabs with a privacy amd security focus but the set up is highly counter intuitive and poorly documented, I think it needs more detailed notes for a fresh user such as the need to generate the headscale api token from the CLI etc.

Creation of pre auth in the admin UI for a user also doesn't seem to work but I'm unsure if that is related to the above or is a known unresolved bug in the UI admin app.

[tremor021]

I can't reproduce your issue, though i think by default script should automatically enable /dev/tun.. Gonna check that

[Builder-DE-TH]

I tried it again just now and it installed, no rate limit this time, but the TUN default is definetely set to NO in advanced. Thanks for having a look at this, been driving me nuts trying to get it to stand up.

[tremor021]

Advanced mode assumes no defaults, its user choice. If something is selected by default its because something has to be selected, it doesnt mean its "default". Default mode has defaults, as the name implies.

[Builder-DE-TH]

My apologies, it's just that with the containers that require passthrough, it's always set to yes for that, I assumed it would be the same with the vpn one with TUN.

[Builder-DE-TH]

Ran into another new issue I forgot earlier, now when I headscale apikeys create

I get

2026-03-21T17:04:58+07:00 FTL ../home/runner/work/headscale/headscale/cmd/headscale/cli/utils.go:124 > Could not connect: context deadline exceeded error="context deadline exceeded"

Which didn't happen before, confused.

[Builder-DE-TH]

You have to connect once to the FQDN, then run the command and it works.

[Builder-DE-TH]

However, when I try to test it with a debian 13 client on the LAN. with

tailscale up --login-server=http://192.168.1.24 --accept-dns --accept-routes

or using the FQDN it gives

failed to connect to local tailscaled; it doesn't appear to be running (sudo systemctl start tailscaled ?)

[tremor021]

do you have /dev/net/tun on your client?

[Builder-DE-TH]

No I don't, I just installed tailscale via apt

[Builder-DE-TH]

OK, unfortunately this is still not working. I ran a fresh install with TUN now on as default in an advanced install, cleared the browser cache.

1st attempt completed but when I headscale apikeys create

I'm again getting

../home/runner/work/headscale/headscale/cmd/headscale/cli/utils.go:124 > Could not connect: context deadline exceeded error="context deadline exceeded"

Even when I have connected to FQDN/admin in the browser, which worked before.

All subsequent attempts have failed with github rate limit even when you add a PAT when prompted.

[Builder-DE-TH]

Retried with headscale-admin not installed and also get

2026-03-22T12:34:56+07:00 FTL ../home/runner/work/headscale/headscale/cmd/headscale/cli/utils.go:124 > Could not connect: context deadline exceeded error="context deadline exceeded"

So the issue lies with headscale and not the admin add-on.

[ComputerRobot]

Had problems getting this API key to work in Brave browser, just wouldnt work and took ages to figure it out. Went over to chrome browser and all of a suddern works and got the extra options available. Havent connected the FQDM to it yet either.

[ComputerRobot]

disabled all blocking in Brave as well before I moved over to chrome.