first commit

2026-10-20 09:41:46 -06:00
commit 2f9031492e
116 changed files with 3737 additions and 0 deletions
@@ -0,0 +1,102 @@
+---
+title: "Headplane"
+category: "Networking and infrastructure"
+tagline: "A web dashboard for your private mesh network, built on Headscale and the Tailscale apps."
+replaces: ["Tailscale (hosted)", "ZeroTier Central", "Cisco AnyConnect", "NordLayer"]
+address: "headplane.example.com"
+website: "https://github.com/tale/headplane"
+upstreamDocs: "https://headscale.net/stable/"
+links:
+  - name: "Headplane on GitHub"
+    url: "https://github.com/tale/headplane"
+  - name: "Headscale documentation"
+    url: "https://headscale.net/stable/"
+  - name: "Download the Tailscale client"
+    url: "https://tailscale.com/download"
+  - name: "Tailscale: Access control policies (ACL syntax)"
+    url: "https://tailscale.com/kb/1018/acls"
+---
+
+## Overview
+
+Headplane is the dashboard for **Headscale**, an open-source server that coordinates a private **mesh VPN** using the official Tailscale apps. Devices you add (laptops, phones, servers, office machines) can reach each other securely over encrypted WireGuard connections, wherever they are, without opening ports on your router.
+
+Your Federated Core server runs the coordination service; your traffic goes directly between your devices whenever possible.
+
+Main capabilities:
+
+- **Machines**: see every connected device, its addresses, operating system, and last seen time.
+- **Users**: group devices by person.
+- **Access controls (ACLs)**: decide which devices and users can reach which others.
+- **MagicDNS**: reach devices by name, such as `office-printer`, instead of by IP address.
+- **Subnet routes**: let devices reach a whole office network through one machine.
+- **Exit nodes**: route all internet traffic through a chosen device, for example while on public Wi-Fi.
+- **Pre-auth keys** for adding servers and devices without an interactive sign-in.
+
+### What it replaces
+
+Headscale with Headplane replaces the hosted Tailscale control plane, ZeroTier Central, and traditional company VPNs such as Cisco AnyConnect or NordLayer for remote access.
+
+## Signing in
+
+Open your Headplane address and sign in. Depending on your setup, you sign in with your organization account or with an API key provided by your administrator.
+
+## Add a device
+
+You use the official Tailscale app on each device, pointed at your own Headscale server instead of Tailscale's.
+
+### Windows, macOS, and Linux
+
+1. Install Tailscale from [tailscale.com/download](https://tailscale.com/download).
+2. Connect it to your server. On Linux, or from a terminal on macOS and Windows:
+
+   ```bash
+   tailscale up --login-server https://headscale.example.com
+   ```
+
+   On macOS you can instead hold <kbd>Option</kbd> while clicking the Tailscale menu bar icon, then choose **Debug**, **Custom Login Server**. On Windows, run the command above in PowerShell.
+3. A browser window opens with a registration step. Complete it, or copy the registration key it shows and give it to your administrator.
+4. In Headplane, the administrator approves the device under **Machines** and assigns it to a user.
+
+### iPhone, iPad, and Android
+
+1. Install Tailscale from the App Store or Google Play.
+2. Open the app's settings and choose to use an **alternate server** (or **custom coordination server**), then enter your Headscale address.
+3. Sign in and complete registration as above.
+
+The address to use is shown in Superpanel. It is the Headscale server, which may differ from the Headplane dashboard address.
+
+{{< review "confirm the Headscale login-server address pattern on Federated Core and the sign-in method for Headplane." >}}
+
+## Manage machines
+
+In Headplane, open **Machines**:
+
+- **Rename** devices so they're easy to recognize.
+- **Move** a machine to a different user.
+- **Expire** a machine's key to force it to sign in again, or **remove** a lost or retired device.
+- **Approve routes**: if a device advertises a subnet or offers to be an exit node, approve it here before others can use it.
+
+## Control who can reach what
+
+Open **Access Control** to edit the policy. By default, devices may be able to reach everything; tighten this as your network grows. The policy uses the same format as Tailscale ACLs, for example allowing the `finance` group to reach only the accounting server on port 443. Save, and changes apply within seconds.
+
+## DNS
+
+Under **DNS**, turn on **MagicDNS** so devices can reach each other by name, and add nameservers or split DNS for internal domains.
+
+## Pre-auth keys for servers
+
+For servers and unattended devices, create a **pre-auth key** under the user's settings. Use it when connecting:
+
+```bash
+tailscale up --login-server https://headscale.example.com --authkey <key>
+```
+
+Make keys single-use and short-lived unless you need otherwise.
+
+## Superpanel settings
+
+{{< review "confirm Superpanel option names for Headplane/Headscale." >}}
+
+- **Access**: choose which administrators can open Headplane. Regular users don't need Headplane; they only need the Tailscale app.