The source post captures the core pieces needed to make a Tailscale Docker client on ZimaOS register with a self-hosted Headscale control plane: persistent state, a one-time/pre-auth key, the custom Headscale URL, TUN access, and the required container capabilities.
Current Tailscale and Headscale documentation now provide a clearer upstream contract. Tailscale officially supports a custom control server URL, and Headscale documents both interactive registration and pre-auth-key registration. Use those upstream methods to validate the current command/URL rather than relying only on a 2025 screenshot.
Headscale Replaces the Tailscale Coordination Control Plane
Headscale is a self-hosted implementation of the Tailscale control server protocol. Tailscale clients still create encrypted peer-to-peer tunnels, but registration and coordination are handled by the user's Headscale instance instead of the default Tailscale control plane.
Persist the Tailscale State Directory
The source created /DATA/AppData/tailscale/state and mapped it to /var/lib/tailscale. This is important because the node identity/state should survive container recreation and host reboot.
The source also recommended restrictive permissions on the host state directory. That is sensible because the state is part of the node's identity and should not be world-readable.
Use the Headscale URL as the Custom Control Server
Current Tailscale documentation supports custom control servers through:
tailscale login --login-server=<URL>Headscale's own docs use the same model with tailscale up --login-server <YOUR_HEADSCALE_URL>.
See Tailscale's current custom control-server guidance.
Use a Pre-Auth Key for Non-Interactive Registration
The source temporarily added TS_AUTHKEY, registered the node, then removed the variable. Headscale currently documents creating a pre-auth key and using it with --authkey for non-interactive registration.
Use Headscale's current registration methods.
Do Not Leave a Reusable Auth Key in the App Definition
If the key is reusable or has a long lifetime, leaving it in the ZimaOS app environment creates unnecessary exposure. After the node identity is stored successfully, remove the registration secret when it is no longer needed.
If a key was pasted into a public forum or screenshot, revoke it and create a new one.
Kernel TUN and Capabilities Affect the Networking Mode
The source maps /dev/net/tun and grants NET_ADMIN/NET_RAW, which is the kernel-networking style rather than pure userspace networking.
Current Tailscale containers can also operate in userspace mode, so choose the mode deliberately based on whether you need subnet routing, exit-node behavior, or full kernel networking.
Host Networking Is Powerful
The source uses Docker host networking. That removes normal container port isolation and makes Tailscale operate directly in the host network namespace.
Do not change from host to bridge—or vice versa—without understanding how the current Tailscale app stores routes, listeners, and advertised services.
The Headscale URL Should Be Reliably Reachable and Properly Secured
A self-hosted control server becomes critical infrastructure. Use stable DNS, a valid TLS configuration, and backups of Headscale's database/configuration. If the control server disappears, existing peers may continue communicating temporarily, but new registrations and coordination changes become unavailable.
The Source Is One Working Configuration, Not an IceWhale Support Contract
The post has no IceWhale staff confirmation. It is a community configuration that aligns well with upstream Tailscale/Headscale concepts but should still be tested against the current ZimaOS Tailscale package.
Headscale on ZimaOS FAQ
Can Tailscale clients use a custom Headscale control server?
Yes. Current Tailscale documentation officially supports custom control server URLs.
Should TS_AUTHKEY remain in the app forever?
No. The source removed it after registration, and long-lived registration secrets should not be left exposed unnecessarily.
Why persist /var/lib/tailscale?
It keeps the node's Tailscale identity/state across container recreation and reboot.
