Tailscale Device Onboarding

Guided multi-step workflow for adding a new device to the tailnet. Covers auth key creation, device authorization, tag assignment, route configuration, and connectivity verification.

When to Use

Trigger this skill when the user wants to:

• Add a new device or server to the tailnet
• Set up a new node (workstation, container, VM, exit node, subnet router)
• Onboard a fleet of similar devices

Workflow: Guided Onboarding

Phase 1 — Gather Requirements

Ask the user for:

• Device purpose: server, workstation, exit node, subnet router, CI runner
• Desired ACL tags: e.g., tag:server, tag:prod, tag:admin
• Subnet routes to advertise (if subnet router): e.g., 10.10.0.0/24
• Exit node: should this device serve as an exit node?
• Persistence: ephemeral (containers/VMs/CI) vs persistent (physical servers, workstations)

Phase 2 — Create Auth Key

Based on gathered requirements:

1. Determine key options:

• Fleet deployment: reusable key
• Single device: single-use key
• Containers/CI: ephemeral key
• Automated setup: preauthorized key

1. Set appropriate tags from Phase 1.
2. Set expiry (default 90 days; ephemeral devices: 1 day).
3. Call tailscale_key_create with the options.
4. ⚠️ Display the key value prominently — warn user to save it immediately.
5. Show the install command:

   tailscale up --authkey=<key>

Phase 3 — Wait for Device

1. Instruct the user to run the install command on the target device.
2. Call tailscale_device_list to check for the new device joining.
3. When found, show device status: IP, OS, online, pending authorization.
4. If not preauthorized: call tailscale_device_authorize to authorize it.

Phase 4 — Configure Device

1. Set ACL tags: tailscale_device_tags_set with tags from Phase 1.
2. If subnet router:

• tailscale_device_routes_get — verify advertised routes.
• tailscale_device_routes_set — enable requested subnet routes.

1. If exit node: enable the exit node route via tailscale_device_routes_set.
2. Set posture attributes if needed: tailscale_device_posture_set.

Phase 5 — Verify Connectivity

1. tailscale_device_get — confirm device is online, correct IP, tags applied.
2. tailscale_device_routes_get — verify routes are enabled.
3. tailscale_acl_test — verify the device can reach expected resources (if test cases exist).
4. If split DNS configured: note that DNS resolution should work for configured domains.

Phase 6 — Onboarding Report

Generate a summary:

• Device: name, Tailscale IP, OS
• Tags: applied tags
• Routes: enabled subnet routes / exit node status
• ACL: access verification results
• Auth key: type used (recommend cleanup for single-use keys)
• Next steps: add to monitoring, update documentation

Rules

• Auth key value is shown only once — warn the user to save it immediately.
• Tag changes affect ACL permissions — show the potential impact.
• Route changes affect network topology — list affected subnets.
• Preauthorized keys are recommended for automated deployments.
• Ephemeral keys are recommended for containers and CI runners.
• Always verify connectivity after configuration.
• If the device doesn't appear within a reasonable time, suggest checking the install command and network connectivity.

Key Tools

• tailscale_key_create — create auth key for the new device
• tailscale_device_list — check for new device joining
• tailscale_device_get — verify device details
• tailscale_device_authorize — authorize pending device
• tailscale_device_tags_set — set ACL tags
• tailscale_device_routes_get / tailscale_device_routes_set — configure subnet routes
• tailscale_device_posture_set — set posture attributes
• tailscale_acl_test — verify access rules