Run Tailscale in plain English: 44 prompts for AI agents
Claude, Cursor, Codex, Continue, Cline — as long as one of these AI agents can reach the Tailscale REST API (api.tailscale.com/api/v2/), the tailscale CLI, or a Tailscale MCP server, you can tell it what to do in plain English. This handbook collects 44 prompts that work in practice. Copy any of them, paste it into the agent's chat box, change the details to match your home, and send.
What this is
This is a phrasebook that turns an AI agent into your Tailscale sidekick: write an ACL policy without memorizing hujson syntax, advertise a subnet router without looking up the flag, list your devices without SSHing in to run the CLI — say one sentence and the agent calls the API or the CLI for you.
Every card has a "Copy" button in its top-right corner. Paste the prompt into Claude Code, Cursor Chat or Codex Agent (the agent needs a Tailscale API key, or permission to run the tailscale CLI), swap in your own device name, CIDR and user email, and send it.
https://api.tailscale.com/api/v2/tailnet/<tailnet>/...), which needs an OAuth client or API access token created in the Tailscale admin console. Read-only work (who's online, routes) also runs from a local tailscale status --json. See tailscale.com/api.How to use these prompts
-
Connect the agent to Tailscale first
Three common ways: (a) give the agent an API token (for example, Claude Code plus the Bash tool); (b) let the agent call the local
tailscaleCLI directly; (c) attach a Tailscale MCP server (community servers such astailscale-mcporheadscale-mcp). Any of the three works. -
Pick the prompt closest to what you need and press Copy
Paste it into the agent's chat box. Every prompt in this handbook is worded to be read by the agent, not by you.
-
Replace the placeholders
<tailnet>,<[email protected]>,192.168.1.0/24andha-homeare placeholders — change them to match your setup. Always keep the "give me a summary before you change anything" line where a prompt has one. -
Look at a dry run before anything risky
For work that changes the policy or revokes an auth key, read the diff or summary the agent gives you on the first run, and confirm before you let it proceed.
ACL policy generation and editing
The Tailscale policy is a hujson file, and the hard part is getting it right without opening it too wide. Having an agent draft it and reviewing it yourself is much faster than writing it from scratch.
Use the Tailscale API to fetch the current ACL policy for my tailnet "<tailnet-name>", pretty-print the hujson for me, and explain in plain language what each grants, acls, tagOwners and nodeAttrs entry does. Read-only, do not change. Answer in English.
API endpoint: GET /api/v2/tailnet/{tailnet}/acl. Treat this as step one of read before you write.
Add one rule to my current policy: devices tagged tag:family may reach port 8123 on tag:ha devices (the Home Assistant Web UI), and no other port. Fetch the current policy first, produce the modified version and show me the diff, and PUT it only after I confirm. Answer in English.
A policy update is a full replace (PUT), so the flow is always read-modify-write.
Rewrite the old acls format in my policy as the newer grants format (the style Tailscale has recommended since 2024), keeping the semantics exactly equivalent. Once it is rewritten, run POST /api/v2/tailnet/{tailnet}/acl/validate and PUT it only after validation passes. Answer in English.
Write me a least-privilege policy skeleton for home use: 3 tags (tag:ha, tag:family, tag:guest). Point every tagOwners entry at <[email protected]>. Rules: family may reach port 8123 on ha, guest may reach only the *:80/443 I have opened to the outside, everything else is denied. Add an English comment on each section. Answer in English.
I need to give a contractor, "<[email protected]>", one week of temporary access: port 22 on tag:zigbee-gateway and nothing else, expiring automatically after 8 days. Set it up with autoApprovers plus autoDelete/expiry. Show me the diff before changing anything. Answer in English.
Do a dry run of what this policy does to my existing devices: run POST /api/v2/tailnet/{tailnet}/acl/preview with the policy body and the real list of tailnet nodes, then tell me which paths that used to work would be cut off and which ones would newly open. Answer in English.
Cross-check this policy once: find (a) tags no rule uses, (b) *:* rules that allow too much, and (c) tags with no tagOwners. Give me a list of improvements, and do not change the policy. Answer in English.
Translate this Tailscale policy into an equivalent Headscale ACL (the v0.23+ format); flag any field Headscale does not support and explain the workaround. Output both versions: the original Tailscale one and the matching Headscale one. Answer in English.
A required step when you move from Tailscale to Headscale.
Subnet router setup
A subnet router lets the tailnet see one segment of your LAN. It is one of the most useful things Tailscale does, and one of the easiest to get wrong.
On this Home Assistant host, make Tailscale a subnet router and advertise 192.168.1.0/24 into the tailnet. Steps: (1) re-advertise with tailscale up --advertise-routes=192.168.1.0/24 --reset; (2) check the state with tailscale status --json; (3) remind me to approve it in the admin console. Answer in English.
Use the Tailscale API to approve every subnet route the device "ha-home" advertises: GET /api/v2/device/{id}/routes first to see advertised vs enabled, add all the advertised ones to enabled, then POST it back. List them for me to confirm before you change anything. Answer in English.
An advertised subnet route is not an approved one — this is the most common trap.
I have two sites: home (LAN 192.168.1.0/24, subnet router = ha-home) and the studio (LAN 10.10.0.0/24, subnet router = studio-nas). Write a policy so that: (a) I can reach the studio from home and home from the studio; (b) family members can reach home only; (c) guests at the studio can reach neither subnet. Preview the change first. Answer in English.
List every subnet router in the tailnet and the CIDR each one advertises, as a table: hostname, tags, advertised routes, enabled routes, last seen. Use tailscale status --json or the API, whichever you have to hand. Answer in English.
I want to withdraw everything the subnet router "old-nas" advertises: clear its enabled routes, rename the hostname to DEPRECATED-old-nas, and produce a withdrawal record (time, reason, which tags are affected). Give me a checklist to confirm before you act. Answer in English.
Enable "ha-home" as an exit node with tailscale up --advertise-exit-node, then tell me to approve exit node use in the admin console. List the command my phone has to run once it is approved (tailscale set --exit-node=ha-home). Answer in English.
MagicDNS and DNS settings
MagicDNS gives every device a short URL that is easy to remember (ha-home, for example), and it can also do split DNS or add a custom nameserver.
Turn on MagicDNS for my tailnet through the API: GET /api/v2/tailnet/{tailnet}/dns/preferences to see the current state, and if it is off, POST {"magicDNS": true}. Also check whether nameservers are set; if they are not, skip that and leave it alone for now. Answer in English.
Add a split DNS entry to the tailnet DNS: resolve the domain *.internal.example.com with the DNS server 192.168.1.53, and leave every other domain on the existing settings. Use POST /api/v2/tailnet/{tailnet}/dns/nameservers or /dns/searchpaths, whichever is the right endpoint. Answer in English.
Rename the device "laptop-1234" in the tailnet to work-laptop with POST /api/v2/device/{id}/name. Once it is renamed, show me the matching *.tailXXXX.ts.net short URL that MagicDNS serves. Answer in English.
Produce a MagicDNS short-URL reference for every device in the tailnet: hostname, magicDNS FQDN, tailnet IP, tags. Output it as a markdown table — I want to paste it into Notion. Answer in English.
Use the Tailscale API to turn on override local DNS for the tailnet (overrideLocalDNS: true) so every device prefers the tailnet DNS. Before you change anything, tell me what this does to a home that currently uses the router as its DNS. Answer in English.
Serve/Funnel HTTPS reverse proxy
Serve gives a device inside the tailnet a short URL with a valid HTTPS certificate (*.tailXXXX.ts.net); Funnel goes one step further and opens that URL to the public internet. Funnel is the riskier of the two, so this handbook does Serve first.
On this HA host, use tailscale serve to give the Home Assistant Web UI an HTTPS short URL inside the tailnet: reverse-proxy localhost:8123 to https://ha-home.tailXXXX.ts.net. Do not turn on Funnel — keep it visible inside the tailnet only. When it is set up, show me tailscale serve status to confirm. Answer in English.
List every Serve and Funnel setting on this machine: run tailscale serve status --json, parse it, and present the path → backend mapping as a table, marking which entries are Serve and which are Funnel (visible on the public internet). Flag anything on Funnel in red. Answer in English.
Write my tailscale serve reverse-proxy setup for HA as a systemd unit or an add-on startup hook, so that serve comes back on its own after HA or the machine restarts. Give me the complete unit file and where to put it. Answer in English.
I am reverse-proxying ha-home.tailXXXX.ts.net inside the tailnet to HA, so it has to be trusted in HA's trusted_proxies: generate the addition my Home Assistant configuration.yaml needs — the http: section — and explain why it is needed. Give me the YAML only; do not actually change the HA configuration. Answer in English.
Risk analysis: if I move HA from Serve to Funnel (visible on the public internet), what are the risks? Give me a checklist: authentication, rate limiting, the attack surface that becomes public, and whether Funnel has an IP allowlist. Do not change any settings. Answer in English.
Tailscale SSH authorization
Tailscale SSH lets you log in to other devices with your tailnet identity, with no authorized_keys to maintain; the policy states directly who may SSH where.
Turn on Tailscale SSH in the policy: let <[email protected]> SSH into every machine tagged tag:ha as root or admin; nobody else may. Write it as an ssh block, show me the diff, and PUT it only after I confirm. Answer in English.
Turn on the Tailscale SSH server on this machine: run tailscale up --ssh (keeping the existing flags) and confirm that tailscale status shows SSH enabled. Before the change, remind me that this replaces the authorization path of the traditional sshd. Answer in English.
Give a contractor, "<[email protected]>", Tailscale SSH access that is valid for 7 days only, into tag:sandbox and nothing else, with the check mode set to check (a second confirmation before login). Do it in the policy's ssh block, with an expiry. Show me the diff before changing anything. Answer in English.
Produce a tailnet SSH audit report: fetch every SSH connection record from the last 30 days (GET /api/v2/tailnet/{tailnet}/logging/network/read), aggregate it into a table of who connected to which machine, how many times, and the average session length, and point out anything unusual. Answer in English.
Device approval and key management
Device approval makes a new device wait for a human to approve it before it joins the tailnet; an auth key is the credential that lets automation join. Both need looking after.
List the new devices currently pending approval in the tailnet: hostname, user, tags, requested at. When the list is done, ask me whether to approve them; when I say approve, call POST /api/v2/device/{id}/authorized. Answer in English.
Create a reusable auth key, valid for 24 hours, that can only create devices tagged tag:ephemeral-test. Use POST /api/v2/tailnet/{tailnet}/keys with reusable: true, ephemeral: true and expirySeconds: 86400. After you return the key, remind me to store it safely right away. Answer in English.
Find the devices in the tailnet with keyExpiryDisabled: true (they never expire) — usually a sign that someone took a shortcut. List them, and say which ones should have expiry turned back on and which are subnet routers that are meant to have it off. List only, do not change. Answer in English.
Remove in bulk every device in the tailnet with no lastSeen for 90 days: show me the list first and let me confirm, and call DELETE /api/v2/device/{id} only after I confirm. Print one log line for each device you delete. Answer in English.
Audit every auth key on the tailnet: query GET /api/v2/tailnet/{tailnet}/keys and list which keys have never been used, which have expired but were never deleted, and which are both reusable and never expire. Give me a cleanup list, and do not change any keys. Answer in English.
Network topology and inventory
Asking what your tailnet looks like right now, who is online and which relay the traffic takes is all read-only work, and you will do it often.
Use tailscale status --json to list every device currently online in the tailnet as a table: hostname, tailnet IP, OS, tags, last seen, and whether it is direct right now or on a DERP relay. For the DERP ones, also say which region. Answer in English.
Draw a mermaid graph of my tailnet: nodes are devices (colored by tag), edges are the access the policy allows, and the LAN CIDRs a subnet router brings in are drawn as cloud shapes. Output it as one ```mermaid block — I want to paste it into a GitHub README. Answer in English.
Test the P2P connection to every other online device with tailscale ping: loop over tailscale ping --c 1 <hostname> and collect direct-or-DERP and latency into a table. For the DERP ones, recommend turning on UPnP or NAT-PMP to see whether NAT traversal can make them direct. Answer in English.
Produce a monthly report for the tailnet: use the API to fetch the devices added and removed this month, subnet route changes, how many times the policy was modified, and the total number of SSH connections. Output it as markdown so I can post it to the team chat. Answer in English.
Find the devices in the tailnet with no tags at all — usually the ones someone added on the fly with a personal email and nobody manages. Show me the list, and suggest a suitable tag for each one (guess from the hostname). Suggest only, do not change. Answer in English.
Troubleshooting prompts
Cannot connect, cannot see it, too slow — hand these to the agent and let it run the diagnosis; it beats taking things apart blind.
Diagnose this: from my phone (iphone-15) I cannot open ha-home. Work through it in order: (1) tailscale status to see that both are online; (2) tailscale ping ha-home to see whether it gets through; (3) tailscale netcheck for a network health check; (4) fetch the policy to see whether a rule blocks it; (5) give me a short conclusion naming the layer at fault. Answer in English.
I advertised 192.168.1.0/24, but a phone on the tailnet still cannot reach 192.168.1.50. Check: (a) that the subnet route is enabled; (b) that the target IP really is in that range; (c) whether a firewall on the target device blocks tailnet sources; (d) whether IP forwarding is on for the HA host (sysctl net.ipv4.ip_forward). Give me a conclusion for each item. Answer in English.
Tailscale SSH suddenly stopped letting me in. Diagnose: (1) tailscale status --json to look at sshHostKeys on the target device; (2) fetch the policy's ssh block to see whether the rules changed; (3) the last 30 lines of journalctl -u tailscaled on the target machine; (4) give me the likely causes in order. Answer in English.
Why is every one of my devices relayed through DERP instead of direct? Run tailscale netcheck and analyze the report: UPnP, NAT-PMP and PCP status, preferred DERP, whether Global v4/v6 is present, and the home NAT type. Give me a list of improvements (switch to --advertise-exit-node, turn on UPnP on the router, or change the DERP region, for example). Answer in English.
Fetch the tailnet's audit log for the last 24 hours (GET /api/v2/tailnet/{tailnet}/logging/configuration/read), list every policy change, key creation and device approval, in the format [time] <actor> <action> <object>, and flag the ones that look unusual. Answer in English.
The Home Assistant Tailscale add-on will not start. Diagnose: (1) search the HA supervisor logs for anything about tailscaled; (2) check whether the auth_key in the add-on configuration has expired; (3) check whether the supervisor grants the full NET_ADMIN capability; (4) give me the three most likely causes and the fix for each. Answer in English.
Cheat sheet: save the agent a round of guessing
- Read before you write: for anything that touches the policy, open with "fetch the current policy first". It stops the agent overwriting by mistake.
- Name the API endpoint: writing "
GET /api/v2/tailnet/{tailnet}/acl" is ten times more precise than "look up the ACL". - Use a symbol for the tailnet: Tailscale officially accepts
-in place of the tailnet name (it means the tailnet the current OAuth client belongs to); write{tailnet}and let the agent fill it in. - Ask for a dry run or a diff: adding "give me a diff or a summary first, and apply it only after I confirm" is the cheapest insurance there is.
- Keep the colon in a tag: a Tailscale tag is always
tag:xxx; drop the colon and the agent generates the wrong format. - Narrow the scope: "only the ones last seen more than 90 days ago" is clearer than "the ones nobody uses", and it prevents accidental deletions.
- State the output format: markdown table, mermaid, CSV — say so up front, and whatever the agent writes is ready to paste anywhere.
FAQ
Can I use these without a Tailscale API token?
tailscale CLI (status, ping, up, serve, netcheck), the agent only needs to be able to run shell commands. You need an API token only to change the policy, keys or device authorization.Do these prompts work with Headscale too?
headscale api ... CLI or gRPC), so the intent of a prompt carries over, but you have to swap the endpoints and parameters for the Headscale ones. One prompt is dedicated to translating the policy.Does the agent need any permissions to run these?
Bash or Terminal tool allowed; with MCP you only have to authorize access for the tailscale-mcp server. Run anything that changes the policy in a controlled environment (a test tailnet) the first time.Could a prompt make the agent change my policy carelessly?
Which MCP server should I connect?
tailscale-mcp, a community wrapper around the REST API; (2) a generic bash or shell MCP plus the local tailscale CLI. The first is safer for device operations because it is type-checked; the second is the most flexible. On Headscale, use the headscale CLI directly or its gRPC MCP adapter.Take this handbook with you
The whole handbook is a self-contained single HTML file with every icon inlined. Download it, open it offline, and forward it to a colleague as it is.