tailscale-policy-manager

Tailscale Policy Manager

Tailscale controls who can talk to what on your private network through a single policy file — a HuJSON document you manage in the admin console or, better yet, in a git repository with automated deployment.

Quick orientation

When a user asks about Tailscale policy/ACL work, figure out what they need:

• Writing or editing rules → delegate to the tailscale-policy-writer agent (background)
• Reviewing a policy for security issues → delegate to the tailscale-policy-reviewer agent (background)
• Setting up GitOps / GitHub Actions → delegate to the tailscale-gitops-setup agent (background)
• Using the API directly / scripting → references/api-reference.md; bundled scripts in scripts/ (validate-policy.sh, apply-policy.sh, get-policy.sh)
• Debugging why something isn't allowed → check the tests block section below and the ACL rule syntax
• Full policy file schema → references/policy-file-reference.md

Grants vs ACLs (as of 2025)

Grants are GA and the default for new tailnets. For new policies, always use grants. For existing policies using acls, continue using acls unless the user asks to migrate — both syntaxes are supported indefinitely and can coexist in the same file.

Key difference: only grants will receive new features (posture checks, app-layer capabilities). acls are network-layer only.

The HuJSON format

Tailscale policy files use HuJSON — standard JSON plus two things:

• Line comments (//) and block comments (/* */)
• Trailing commas on the last item in any array or object

This matters because it means you can document your rules inline, which is valuable for a security-sensitive file that multiple people edit.

{
  // Engineers can reach dev servers on any port
  "acls": [
    {
      "action": "accept",
      "src":    ["group:engineering"],
      "dst":    ["tag:dev:*"],  // trailing comma is fine
    },
  ],
}

Core policy file sections