add-node

Provision remote machines as k3s nodes over SSH and Tailscale.

Updated Mar 15, 2026
One-click install
npx skills add https://github.com/Kord96/kordinate --skill add-node-kord96
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: add-node
Source: https://github.com/Kord96/kordinate/tree/main/agents/charon/skills/add-node
Command: npx skills add https://github.com/Kord96/kordinate --skill add-node-kord96

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Adds and configures remote machines as k3s nodes without requiring direct LAN access or opening Kubernetes ports, removing the need for manual on-node execution or complex firewall rules by routing cluster traffic over Tailscale's DERP relay.

Core Features & Use Cases

  • Remote provisioning: SSH into a target, install Tailscale, authenticate, detect architecture, and install k3s agent or server as needed.
  • Join or bootstrap clusters: Join an existing control plane using its Tailscale IP and k3s node-token, or bootstrap a new control plane and deploy the standard infrastructure stack.
  • Idempotent and resilient: Detects existing installations, supports password-based SSH via sshpass, updates Alfred's config.yaml, and verifies node readiness with kubectl.
  • Use case: Easily add a home or staging machine behind NAT to your fleet without exposing port 6443 by leveraging Tailscale and SSH.

Quick Start

Run the add-node command with the SSH target and optional cluster name, for example: /add-node [email protected] homelab

Frequently Asked Questions about add-node

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a remote machine to a k3s cluster behind NAT without exposing ports?

Add a remote node to a k3s cluster by routing traffic over Tailscale's DERP relay, which removes the need to open Kubernetes port 6443 or require direct LAN access. SSH is used to provision the target machine and join it to the existing control plane.

Can I bootstrap a new k3s control plane over Tailscale and SSH?

You can bootstrap a new k3s control plane over Tailscale and SSH by installing the k3s server on the target machine, authenticating with Tailscale, and deploying the standard infrastructure stack using DERP-relayed connections for nodes behind NAT.

What prerequisites do I need to remotely provision a k3s node?

Remotely provisioning a k3s node requires SSH access with sudo privileges on the target machine, Tailscale installation with authentication or a preauth key, and access to the k3s node-token on the control plane to authorize the joining node.

Does adding a k3s node over SSH support password authentication instead of keys?

Password-based SSH authentication is supported for adding a k3s node through the use of sshpass, allowing remote provisioning when SSH key access is unavailable, provided sudo privileges are still granted on the target machine.

How does Tailscale DERP relay handle k3s cluster traffic for remote nodes?

Tailscale DERP relay routes k3s cluster traffic between nodes by establishing encrypted connections that bypass NAT restrictions, allowing remote machines to join the cluster without requiring direct LAN access or complex firewall configurations.

What happens if k3s or Tailscale is already installed on the target node?

The remote provisioning process is idempotent, meaning it detects existing k3s or Tailscale installations on the target node and skips redundant setup steps, ensuring the node is correctly configured without overwriting current installations.