From 5d300273dc57d552c64d9ebd0142f1bce8a1bf66 Mon Sep 17 00:00:00 2001
From: Florian Preinstorfer <site-github@nblock.org>
Date: Sat, 24 Jan 2026 10:58:58 +0100
Subject: [PATCH] Add a tags page and describe a few common operations

---
 docs/about/features.md |  2 +-
 docs/ref/tags.md       | 54 ++++++++++++++++++++++++++++++++++++++++++
 mkdocs.yml             |  1 +
 3 files changed, 56 insertions(+), 1 deletion(-)
 create mode 100644 docs/ref/tags.md

diff --git a/docs/about/features.md b/docs/about/features.md
index afc81792..1d87019f 100644
--- a/docs/about/features.md
+++ b/docs/about/features.md
@@ -14,7 +14,7 @@ provides on overview of Headscale's feature and compatibility with the Tailscale
     - [x] [search domains](https://tailscale.com/kb/1054/dns#search-domains)
     - [x] [Extra DNS records (Headscale only)](../ref/dns.md#setting-extra-dns-records)
 - [x] [Taildrop (File Sharing)](https://tailscale.com/kb/1106/taildrop)
-- [x] [Tags](https://tailscale.com/kb/1068/tags)
+- [x] [Tags](../ref/tags.md)
 - [x] [Routes](../ref/routes.md)
     - [x] [Subnet routers](../ref/routes.md#subnet-router)
     - [x] [Exit nodes](../ref/routes.md#exit-node)
diff --git a/docs/ref/tags.md b/docs/ref/tags.md
new file mode 100644
index 00000000..7e08be13
--- /dev/null
+++ b/docs/ref/tags.md
@@ -0,0 +1,54 @@
+# Tags
+
+Headscale supports Tailscale tags. Please read [Tailscale's tag documentation](https://tailscale.com/kb/1068/tags) to
+learn how tags work and how to use them.
+
+Tags can be applied during [node registration](registration.md):
+
+- using the `--advertise-tags` flag, see [web authentication for tagged devices](registration.md#__tabbed_1_2)
+- using a tagged pre authenticated key, see [how to create and use it](registration.md#__tabbed_2_2)
+
+Administrators can manage tags with:
+
+- Headscale CLI
+- [Headscale API](api.md)
+
+## Common operations
+
+### Manage tags for a node
+
+Run `headscale nodes list` to list the tags for a node.
+
+Use the `headscale nodes tag` command to modify the tags for a node. At least one tag is required and multiple tags can
+be provided as comma separated list. The following command sets the tags `tag:server` and `tag:prod` on node with ID 1:
+
+```console
+headscale nodes tag -i 1 -t tag:server,tag:prod
+```
+
+### Convert from personal to tagged node
+
+Use the `headscale nodes tag` command to convert a personal (user-owned) node to a tagged node:
+
+```console
+headscale nodes tag -i <NODE_ID> -t <TAG>
+```
+
+The node is now owned by the special user `tagged-devices` and has the specified tags assigned to it.
+
+### Convert from tagged to personal node
+
+Tagged nodes can return to personal (user-owned) nodes by re-authenticating with:
+
+```console
+tailscale up --login-server <YOUR_HEADSCALE_URL> --advertise-tags= --force-reauth
+```
+
+Usually, a browser window with further instructions is opened. This page explains how to complete the registration on
+your Headscale server and it also prints the registration key required to approve the node:
+
+```console
+headscale nodes register --user <USER> --key <REGISTRATION_KEY>
+```
+
+All previously assigned tags get removed and the node is now owned by the user specified in the above command.
diff --git a/mkdocs.yml b/mkdocs.yml
index d1d9bdc1..5378f74f 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -191,6 +191,7 @@ nav:
       - DNS: ref/dns.md
       - DERP: ref/derp.md
       - API: ref/api.md
+      - Tags: ref/tags.md
       - Debug: ref/debug.md
       - Integration:
           - Reverse proxy: ref/integration/reverse-proxy.md