# Tailscale Macos Headscale

> |

- **Type:** Skill
- **Install:** `agentstack add skill-aeyeops-aeo-skill-marketplace-tailscale-macos-headscale`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [AeyeOps](https://agentstack.voostack.com/s/aeyeops)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [AeyeOps](https://github.com/AeyeOps)
- **Source:** https://github.com/AeyeOps/aeo-skill-marketplace/tree/main/aeo-infra/skills/tailscale-macos-headscale

## Install

```sh
agentstack add skill-aeyeops-aeo-skill-marketplace-tailscale-macos-headscale
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Tailscale on macOS against a self-hosted headscale

A practical reference for getting a macOS host onto a headscale-managed
Tailscale mesh, with the macOS-specific traps that aren't called out in either
the Tailscale docs (which assume the public control server) or the headscale
docs (which assume Linux clients).

---

## Quick reference

| Item | Value |
|------|-------|
| Recommended client distribution | Homebrew Cask: `brew install --cask tailscale` |
| Do NOT also install | Homebrew formula `tailscale` (its bundled daemon fights the cask's NetworkExtension) |
| App location | `/Applications/Tailscale.app` |
| Bundled CLI binary | `/Applications/Tailscale.app/Contents/MacOS/Tailscale` |
| Operator-friendly CLI shim | `/usr/local/bin/tailscale` — installed via Tailscale menu bar → Preferences → "Install command line tool" |
| Daemon process name (in `ps`) | `IPNExtension` (inside the app bundle) |
| Daemon socket | macOS-internal IPC managed by the NetworkExtension subsystem; not a Unix socket the operator interacts with directly |
| Headscale preauth key minting | `headscale preauthkeys create --user  --expiration 1h` |
| Required permissions before daemon starts | Network Extension allow, VPN configuration approve, system extension activation |

---

## Reference files

| File | Read when |
|------|-----------|
| [installing-tailscale-on-macos.md](installing-tailscale-on-macos.md) | Installing Tailscale fresh, cleaning up a mixed cask+formula install, walking the operator through the macOS permission grants required for the NetworkExtension daemon to start. |
| [joining-headscale-from-macos.md](joining-headscale-from-macos.md) | Connecting a working Tailscale.app to a headscale coordinator — preauth-key CLI flow, deep-link fallback when the CLI cannot reach the daemon, headscale's `--user ` vs `--user ` pitfall, and verification commands. |

---

## Common tasks

### Install Tailscale for the first time on macOS

1. `brew install --cask tailscale` (the cask, not the formula — see [installing-tailscale-on-macos.md](installing-tailscale-on-macos.md) for why).
2. Open Tailscale.app once: `open -a Tailscale`.
3. Step through the macOS permission grants (Network Extension activation, VPN configuration approval). Detailed paths in [installing-tailscale-on-macos.md](installing-tailscale-on-macos.md).
4. Confirm the daemon is up: `pgrep -fl IPNExtension`.

### Join a headscale-controlled mesh with a preauth key

1. Mint a single-use preauth key on the headscale host (numeric user ID — see [joining-headscale-from-macos.md](joining-headscale-from-macos.md) for the user-id gotcha).
2. `sudo /Applications/Tailscale.app/Contents/MacOS/Tailscale up --login-server=https:// --auth-key= --accept-routes --ssh --hostname=`.
3. Verify: `tailscale status` shows the host plus peers.

### Recover from "failed to connect to local tailscale service"

This means the CLI is fine but the NetworkExtension daemon either has not
been activated or has not been granted permission. Procedure in
[installing-tailscale-on-macos.md](installing-tailscale-on-macos.md) under
"Permission dance".

### Recover from a mixed cask + formula install

The brew formula `tailscale` ships its own `tailscaled` that competes with
the cask's NetworkExtension for the local IPC socket. Symptom: Tailscale.app
GUI stuck on "Starting..." and `tailscale up` hangs indefinitely. Full
cleanup steps in [installing-tailscale-on-macos.md](installing-tailscale-on-macos.md).

### Persist Tailscale across reboots

The cask installs a LaunchAgent that auto-starts Tailscale.app on login.
Nothing extra to configure. If using the formula (not recommended), see the
formula's own caveats — not covered here.

---

## Related skills in this marketplace

Cross-skill references in this marketplace use the form
`@` (e.g., `glinet-slate7@aeo-infra` means the
`glinet-slate7` skill living in the `aeo-infra` plugin).

- `glinet-slate7@aeo-infra` — if Tailscale is being layered on top of a
  WireGuard underlay terminated by a GL-iNet Slate 7 (or other sdk4
  firmware) router, that skill covers the underlay side: client `wg0.conf`
  patterns, the wg-server admin API, peer rotation, and the leak-fix rules
  for Linux clients running Tailscale on top of WireGuard. On macOS the
  leak-fix rules do not apply (macOS routing model differs from Linux
  `ip rule` policy routing), but the WG client config and server
  provisioning are the same.
- `lima-vm-operations@aeo-infra` — if the macOS host is acting as a Lima
  hypervisor and the actual Tailscale client is a Linux VM inside Lima, the
  procedures here do not apply; install Tailscale inside the VM per the
  Linux path instead.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [AeyeOps](https://github.com/AeyeOps)
- **Source:** [AeyeOps/aeo-skill-marketplace](https://github.com/AeyeOps/aeo-skill-marketplace)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-aeyeops-aeo-skill-marketplace-tailscale-macos-headscale
- Seller: https://agentstack.voostack.com/s/aeyeops
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.