tailscale

Tailscale + Headscale スキルバンドル

この包括的なスキルは、オープンソースのコントロールサーバーとしてHeadscaleを使用する、セルフホスト可能な Tailscale エコシステムを対象としています。コンテキストに応じて自動的に読み込まれる 7 つのサブスキルを提供します。

セキュリティ事前確認

SSH、Serve、Funnel、アプリコネクター、オンボーディングを有効にする場合や、コントロールプレーンの公開範囲を変更する場合は、事前にセキュリティトリアージをお読みください。また、Tailworm、侵害の疑い、またはセキュリティ強化に関する依頼でも読み込んでください。共有クライアント防御策はホスト型 Tailscale にも適用されますが、Headscale の操作はセルフホスト環境に限られます。このバンドルの管理用スクリプトが Headscale を対象としていることだけを理由に、これらの保護を求めるホスト型環境のユーザーを拒否しないでください。

実行する前に、対象、範囲、ロールバック手順を確認してください。読み取り専用の調査は確認なしで進められます。 デバイスの削除を含む破壊的な封じ込めには、ユーザーからの明示的な指示が必要です。 利便性を理由に Tailscale SSH をデフォルトで有効にしないでください。無効にする前に、別の管理アクセス経路を確保してテストしてください。ユーザーのシステムで公開エクスプロイトキットを実行しないでください。 公開範囲の一覧、対応可能な緩和策、確認できた検証結果、未解決のリスクを含めて完了してください。さらなる検証に必要な証拠や権限が得られない場合は、そこで停止してください。

コンテキストに応じた自動読み込み

ユーザーのメッセージがトリガーキーワードに一致すると、該当するサブスキルの SKILL.md が読み込まれます。複数のトリガーが重複する場合は、複数のサブスキルが同時に読み込まれることがあります。

トリガーキーワード	読み込まれるサブスキル
"deploy headscale", "install headscale", "setup headscale server", "headscale config"	headscale-deploy
"ACL", "policy file", "tailnet policy", "access control", "grant", "tag owners"	tailnet-policy
"install tailscale", "connect to headscale", "tailscale client", "tailscale up", "tailscale status", "diagnose tailscale", "connectivity"	tailscale-client
"auth key", "preauthkey", "register node", "approve node", "tag node", "node list", "decommission node"	headscale-node-lifecycle
"subnet router", "exit node", "advertise route", "approve route"	headscale-routing
"DERP", "relay", "peer relay", "STUN"	headscale-derp
"backup headscale", "restore headscale", "migrate headscale", "headscale backup"	headscale-backup
"Tailscale", "Headscale", "tailnet", "mesh VPN", "WireGuard mesh", "self-hosted VPN"	ナビゲーション用にこの包括的な SKILL.md を読み込みます

サブスキルの順序と依存関係

headscale-deploy ─────┬──> tailnet-policy ───> headscale-routing
                       │
                       ├──> headscale-node-lifecycle
                       │
                       ├──> tailscale-client
                       │
                       ├──> headscale-derp
                       │
                       └──> headscale-backup (prerequisite: a running headscale instance)

• headscale-deployを最初に完了する必要があります。ほかのサブスキルには、稼働中の Headscale サーバーが必要です
• tailnet-policy（ACL を設定します）は、ほかのユーザーに tailnet を開放する前に設定することを推奨します
• headscale-derpは任意ですが、NAT 環境での信頼性を高めるため推奨します
• 本番環境へのデプロイでは、headscale-backupを定期的に実行してください

ルートスクリプト（共有ユーティリティ）

これらはバンドルのルートにある scripts/ に配置されており、すべてのサブスキルから利用できます。

利用可能なスクリプト

スクリプト	目的	実行方法
scripts/headscale-health-check.sh	Headscale サーバーのヘルス状態（バージョン、ノード数、DB の整合性）を確認します。コントロールサーバーに変更を加えた後に実行し、ノードやクライアントに問題が発生した場合は、最初の診断として実行してください。	scripts/headscale-health-check.sh --json
scripts/headscale-backup.sh	設定済みの SQLite と復旧用パスから、チェックサム付きマニフェストを含む Headscale アーカイブを作成します。アップグレードや移行の前に実行してください。--dry-run を指定すると、書き込みを行わずにプレビューできます。	scripts/headscale-backup.sh --dry-run --json
scripts/headscale-restore.sh	マニフェストを含む、サポート対象のアーカイブを検証し、記録された保存先に復元します。復旧時に実行してください。実行後は必ずノード一覧とポリシーを確認してください。	scripts/headscale-restore.sh --backup headscale-backup-2026-01-01.tar.gz --dry-run --json
scripts/tailscale-status-json.sh	ピアの診断情報を含む、tailscale status --json の構造化ラッパーです。任意のクライアントから実行して、接続状態、ピア、中継／直接接続経路を機械可読形式で確認できます。	scripts/tailscale-status-json.sh
scripts/test-all.sh	実行中の Headscale がなくても、バンドル内のすべてのスクリプトをスモークテストします（--help、構文、実行可能性）。バンドル内のスクリプトを変更した後に実行してください。CI では scripts/check-skill-tests.py 経由で実行されます。	bash scripts/test-all.sh

テンプレート

テンプレートは templates/ にあり、一般的なデプロイパターンをカバーしています。

• templates/docker-compose-headscale.yaml — Headscale + 組み込み DERP + Traefik TLS
• templates/headscale-config.yaml — 注釈付きの Headscale 完全設定
• templates/policy-allow-all.json — 最小限の全許可ポリシー
• templates/policy-deny-all.json — 制限の厳しい全拒否ポリシー
• templates/policy-tagged-segmented.json — タグベースのアクセスモデル
• templates/derp-map.json — カスタム DERP リレーマップ

環境変数

変数	使用対象	目的
HEADSCALE_URL	すべて	Headscale サーバーの URL（例：https://headscale.example.com）
HEADSCALE_API_KEY	すべて	Headscale API キー（headscale apikeys create で作成）
TAILSCALE_AUTHKEY	tailscale-client	対話なしでクライアントをセットアップするための事前認証済みキー

CLI ツールを使用する

すべてのスクリプトは --json、--dry-run を使用でき、わかりやすい --help 出力を備えています。 バンドルルートからのスクリプトの相対パス：scripts/<tool> または skills/<sub-skill>/scripts/<tool>。

詳しい使用方法については、各サブスキルの SKILL.md を参照してください。

前提条件

• スクリプトを実行するホストに bash、Python 3.10 以降、jq、curl が必要です（compatibility を参照）。
• サーバー側の操作には、HEADSCALE_URL と HEADSCALE_API_KEY を設定した稼働中の Headscale サーバーが必要です（API キーは headscale apikeys create で作成します）。対話なしでクライアントを登録するには TAILSCALE_AUTHKEY が必要です。
• ステータス確認およびルーティングのサブスキルでは、対象マシンに tailscale クライアントがインストールされている必要があります。コントロールサーバーの管理には headscale CLI（または API アクセス）が必要です。
• headscale-backup／restore では、サーバーの SQLite DB、設定、ポリシー、証明書の各パスへのファイルシステムアクセスと、コントロールサーバーホスト外にアーカイブを保存するためのストレージが必要です。
• 移行する場合は、検証済みの restore ヘルパーを移行先のソース側と同じパスにインストールするか、HEADSCALE_REMOTE_RESTORE_SCRIPT に移行先のパスを設定してください。復元前に、記録されたアーカイブパスとディレクトリの所有権を準備してください。

制限事項

• このバンドルはセルフホストの Headscale コントロールプレーンを前提としており、Tailscale のホスト型 SaaS は管理しません（「使用しない場合」を参照）。
• スクリプトは実行時に環境変数を確認し、未設定の場合はわかりやすいエラーを表示します。認証情報を自ら作成することはありません。
• バックアップと復元の対象は、コントロールサーバーのホスト上に存在するファイルです。バックアップされていないデータは復旧できません。また、復元後は必ずヘルスチェックを行ってください。
• 復元で受け付けるのはマニフェストバージョン 1 のアーカイブです。マニフェストのない古い tarball は拒否されます。移行するには、検証済みの復元ヘルパーを移行先にインストールする必要があります。生の展開にフォールバックしたり、検証済みの復元結果なしに成功を報告したりすることはありません。移行前に、アーカイブ内のパスと対象ディレクトリの所有権を準備してください。ファイルを移動する root のオーバーライドは、設定パスとサービスパスを個別に更新して検証するまで拒否されます。
• サブスキルのスクリプトは skills/<sub-skill>/scripts/ にあり、このドキュメントではなく、それぞれの SKILL.md ファイルに記載されています。

使用しない場合

タスクが単一のサブスキルに該当する場合は、このアンブレラスキルを読み込まず、該当するサブスキルを直接読み込んでください（例：headscale-deploy、tailnet-policy、tailscale-client）。このスキルはセルフホストの Headscale コントロールサーバーを前提としています。ホスト型コントロールプレーンの管理や Tailscale 以外の VPN ツールには、代わりに適切なネットワークスキルを使用してください。上記の共通のセキュリティトリアージは、ホスト型 Tailscale にも適用されます。