Self-Hosting with Headscale

Aircast reaches your device over a tailnet: a private WireGuard mesh coordinated by a control server. By default that's Tailscale's hosted coordination service. If you'd rather own the whole path, point the device at your own Headscale server instead. No Tailscale account and no third-party coordinator, just your control plane and your devices.

Before you start

• A small always-on host with a public IP or DNS name for Headscale (a $5 VPS is plenty, since it carries control traffic, not video).
• A domain with HTTPS for the control server. Headscale clients require TLS; terminate it with Caddy, a reverse proxy, or Headscale's built-in ACME.
• An Aircast device already flashed and reachable on your LAN, see First flight. Or set Headscale while you flash the card, see step 5.

Throughout this guide, replace https://headscale.example.com with your own control server URL.

Set it up

mkdir -p ./config ./data
curl -fsSL https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml \
  -o ./config/config.yaml
# edit ./config/config.yaml → set: server_url: https://headscale.example.com

docker run -d --name headscale \
  -v ./config:/etc/headscale \
  -v ./data:/var/lib/headscale \
  -p 8080:8080 \
  headscale/headscale:stable \
  serve

curl -fsS https://headscale.example.com/health

2

Connect the admin panel

Everything from here on happens in headscale-admin , a web UI for users, pre-auth keys, and nodes. Run it next to Headscale and serve it from the same domain under /admin:

On your control-server host

docker run -d --name headscale-admin \
  -p 8000:80 \
  goodieshq/headscale-admin:latest
# reverse-proxy https://headscale.example.com/admin → localhost:8000

The panel authenticates against Headscale with an API key, so mint one:

On your control-server host

docker exec headscale headscale apikeys create --expiration 90d

Open https://headscale.example.com/admin → Settings, set the API URL to your control server, paste the API key, and save. Once it reads Authorized, you're connected. This is the last time you touch the terminal.

3

Create a user

Devices register under a user (a namespace). In the Users tab, click Create and name it. The user's card then lists every node it owns and its pre-auth keys:

4

Mint a pre-auth key

A pre-auth key lets the device join unattended, with no browser sign-in and no manual approval. This is the path Aircast is built around. On the user's card, next to PreAuth Keys, click Create. Copy the hskey-… value, which you'll paste into the device in the next step.

Mark the key Reusable if you're provisioning several devices from it, and Ephemeral for devices that should be dropped from the tailnet when they go offline. Set an expiration you're comfortable with, since the key is a credential.

6

Confirm it joined

The admin panel's Nodes tab lists every registered device with its online status and tailnet IP. Your Aircast device shows up here alongside any phones or laptops on the tailnet. The device's Tailscale card now reads connected with its tailnet name, and you can reach it at that address from anywhere on the same tailnet.

Join your viewing devices

To watch the stream, the device you view from, a phone or laptop, also needs to be on your tailnet. In the official Tailscale app, add an account with Use an alternate server and enter your Headscale URL, and the app signs in against your control plane instead of Tailscale's.

On a phone, open the account menu and pick Use an alternate server:

On macOS or desktop it's the same: Add Account → Use an alternate server, then enter your Headscale URL:

Once it connects, the account's Server shows your Headscale URL, confirming the device is on your control plane, not Tailscale's:

Joining unattended (CLI, or a machine without a browser)? tailscale up --login-server https://headscale.example.com --authkey <pre-auth key>, the app's Use an auth key option does the same.

Connect QGroundControl over the tailnet

With both ends on the tailnet, your ground station reaches the device by its tailnet address, with no port forwarding, no public exposure. In Aircast QGC, point telemetry at the device's tailnet IP or name, and video follows.

Telemetry (MAVLink)

Open Application Settings → Comm Links → Add. Create a UDP link and add a server address pointing at the device's tailnet IP on the MAVLink port, typically <device-tailnet-ip>:14550:

Save it, then Connect: it sits alongside any other links (e.g. a direct 4G link) so you can switch between paths:

Video (RTSP)

Once telemetry arrives over this link, the device announces its camera and Aircast QGC sets up Camera 1 by itself. For another camera, or a ground station that doesn't pick it up, open Application Settings → Video, press Add camera stream under Cameras, and use the device's tailnet name: rtsp://<device-tailnet-host>:8554/<camera name>.

Troubleshooting: “key hex string doesn't have expected type prefix mkey:”

If you do register a node through headscale-admin's Create form, you'll hit this error when you paste a key without its mkey: prefix. The field wants the full prefixed key, not the bare hex.

Where does the key come from? A node can't be created from a hostname. It only exists once the device starts registration, which is what generates its machine key. When a client signs in to a self-hosted Headscale interactively, it shows a Machine registration page with a ready-to-run command. The value after --key, including the mkey: prefix, is exactly what the form expects.

Paste that full mkey:-prefixed value into the Create form, pick the user, and submit. The node registers cleanly.