@underpostnet/cyberia 3.2.80

package/scripts/disk-clean.sh

@@ -0,0 +1,182 @@
+#!/usr/bin/env bash
+# disk-clean.sh
+# Automatic safe cleanup script for Rocky Linux 9
+# This script ALWAYS runs non-interactively (batch)
+# Usage: sudo ./disk-clean.sh
+set -euo pipefail
+
+VACUUM_SIZE="200M"          # journalctl vacuum target
+LARGE_LOG_SIZE="+100M"      # threshold for truncation (find syntax)
+TMP_AGE_DAYS=1              # remove files older than this from /tmp and /var/tmp
+CACHE_AGE_DAYS=5           # remove caches older than this from /var/cache
+KEEP_KERNELS=2              # keep this many latest kernels
+REMOVE_OPT=0                # ALWAYS allow removing /opt entries (user requested)
+
+timestamp() { date +"%F %T"; }
+log() {
+    echo "$(timestamp) $*"
+}
+
+# must be root
+if [ "$EUID" -ne 0 ]; then
+    echo "This script must be run as root. Exiting."
+    exit 1
+fi
+
+log "=== Starting Rocky Linux 9 automated cleanup (batch mode) ==="
+log "Command line: $0 $*"
+log "REMOVE_OPT=$REMOVE_OPT"
+log "VACUUM_SIZE=$VACUUM_SIZE, LARGE_LOG_SIZE=$LARGE_LOG_SIZE, TMP_AGE_DAYS=$TMP_AGE_DAYS, CACHE_AGE_DAYS=$CACHE_AGE_DAYS"
+
+# Report current disk usage
+log "Disk usage before cleanup:"
+df -h
+log "Top-level disk usage ( / ):"
+du -xh --max-depth=1 / | sort -rh | head -n 20
+
+# 1) DNF cleanup
+log "Cleaning DNF caches and removing orphaned packages..."
+dnf -y clean all
+dnf -y autoremove
+
+# 2) Journal logs vacuum
+log "Vacuuming systemd journal to keep ${VACUUM_SIZE}..."
+journalctl --vacuum-size="$VACUUM_SIZE"
+
+# 3) Truncate very large logs in /var/log (safer than delete)
+log "Truncating logs in /var/log larger than ${LARGE_LOG_SIZE} (keeps zero-sized file so services don't break)..."
+find /var/log -type f -size "$LARGE_LOG_SIZE" -print0 2>/dev/null | while IFS= read -r -d '' f; do
+    echo "Truncating $f"
+    : > "$f" || echo "Failed to truncate $f"
+done
+
+# 4) Clean /tmp and /var/tmp older than TMP_AGE_DAYS
+log "Removing files older than ${TMP_AGE_DAYS} days from /tmp and /var/tmp..."
+find /tmp -mindepth 1 -mtime +"$TMP_AGE_DAYS" -print0 2>/dev/null | xargs -0r rm -rf --
+find /var/tmp -mindepth 1 -mtime +"$TMP_AGE_DAYS" -print0 2>/dev/null | xargs -0r rm -rf --
+
+# 5) Clean /var/cache older than CACHE_AGE_DAYS (but not all cache immediately)
+log "Removing entries in /var/cache older than ${CACHE_AGE_DAYS} days..."
+find /var/cache -mindepth 1 -mtime +"$CACHE_AGE_DAYS" -print0 2>/dev/null | xargs -0r rm -rf --
+
+# 6) Clean user caches (~/.cache) and Downloads older than CACHE_AGE_DAYS
+log "Cleaning user caches and old downloads (home dirs)..."
+for homedir in /home/* /root; do
+    [ -d "$homedir" ] || continue
+    usercache="$homedir/.cache"
+    userdownloads="$homedir/Downloads"
+    usertrash="$homedir/.local/share/Trash"
+    
+    if [ -d "$usercache" ]; then
+        log "Removing contents of $usercache"
+        rm -rf "${usercache:?}/"* 2>/dev/null
+    fi
+    if [ -d "$userdownloads" ]; then
+        log "Removing files older than ${CACHE_AGE_DAYS} days from $userdownloads"
+        find "$userdownloads" -type f -mtime +"$CACHE_AGE_DAYS" -print0 2>/dev/null | xargs -0r rm -f -- 2>/dev/null
+    fi
+    if [ -d "$usertrash" ]; then
+        log "Emptying trash in $usertrash"
+        rm -rf "${usertrash:?}/"* 2>/dev/null
+    fi
+done
+
+# 7) Docker / Podman cleanup (if present) — this is what actually reclaims the
+#    overlay storage behind those duplicated `overlay` df lines.
+if command -v docker >/dev/null 2>&1; then
+    log "Docker detected: pruning images/containers/volumes/build cache (aggressive)..."
+    docker system df || true
+    docker system prune -a --volumes -f || true
+    docker builder prune -a -f || true
+fi
+
+if command -v podman >/dev/null 2>&1; then
+    log "Podman detected: pruning images/containers/volumes (aggressive)..."
+    podman system df || true
+    podman system prune -a --volumes -f || true
+fi
+
+if command -v buildah >/dev/null 2>&1; then
+    log "Buildah detected: removing leftover working containers..."
+    buildah rm --all || true
+fi
+
+# 7b) Unmount leaked container overlay 'merged' mounts. Pruning frees the data
+#     but leaves these mountpoints attached, so they keep flooding `df -h` with
+#     identical `overlay ... /merged` rows. Only unmount overlays not backing a
+#     still-existing container, so running workloads are never disturbed.
+log "Unmounting orphaned container overlay mounts..."
+if command -v podman >/dev/null 2>&1; then
+    podman umount --all >/dev/null 2>&1 || true
+fi
+active_merged="$(podman ps -aq 2>/dev/null | xargs -r -I{} podman inspect --format '{{.GraphDriver.Data.MergedDir}}' {} 2>/dev/null || true)"
+findmnt -rn -o TARGET 2>/dev/null | grep -E '/var/lib/(containers/storage|docker)/overlay.*/merged' | sort -r | while IFS= read -r m; do
+    if ! printf '%s\n' "$active_merged" | grep -qxF "$m"; then
+        echo "Unmounting orphaned overlay: $m"
+        umount -l "$m" 2>/dev/null || true
+    fi
+done
+
+# 8) Flatpak unused runtimes/apps (if present)
+if command -v flatpak >/dev/null 2>&1; then
+    log "Flatpak detected: trying to uninstall unused runtimes/apps..."
+    flatpak uninstall --unused -y || flatpak uninstall --unused
+    flatpak repair
+fi
+
+# 9) Python Pip cleanup
+if command -v pip3 >/dev/null 2>&1 || command -v pip >/dev/null 2>&1; then
+    log "Python Pip detected: cleaning cache..."
+    if command -v pip3 >/dev/null 2>&1; then
+        pip3 cache purge
+        elif command -v pip >/dev/null 2>&1; then
+        pip cache purge
+    fi
+fi
+
+# 10) Conda cleanup
+if command -v conda >/dev/null 2>&1; then
+    log "Conda detected: cleaning all..."
+    conda clean --all -y
+fi
+
+# 11) Remove old kernels but keep the last KEEP_KERNELS (safe)
+log "Removing old kernels, keeping the last $KEEP_KERNELS kernels..."
+OLD_KERNELS=$(dnf repoquery --installonly --latest-limit=-$KEEP_KERNELS -q 2>/dev/null)
+if [ -n "$OLD_KERNELS" ]; then
+    log "Old kernels to remove: $OLD_KERNELS"
+    dnf -y remove $OLD_KERNELS
+else
+    log "No old kernels found by DNF repoquery. Only $KEEP_KERNELS or fewer are currently installed."
+fi
+
+# 12) /opt review and removal (ON by default now)
+if [ -d /opt ]; then
+    log "/opt usage (top entries):"
+    du -sh /opt/* 2>/dev/null | sort -h | head -n 20
+    
+    if [ "$REMOVE_OPT" = "1" ]; then
+        OPT_TARGETS=(/opt/local-path-provisioner)
+        for t in "${OPT_TARGETS[@]}"; do
+            if [ -d "$t" ]; then
+                log "Removing $t as REMOVE_OPT=1"
+                rm -rf "$t"
+            fi
+        done
+    else
+        log "Automatic /opt removals disabled (set REMOVE_OPT=1 to enable)."
+    fi
+fi
+
+# 13) Find large files > 100MB (report only)
+log "Listing files larger than 100MB (report only):"
+find / -xdev -type f -size +100M -printf '%s\t%p\n' 2>/dev/null | sort -nr | head -n 50 | awk '{printf "%.1fMB\t%s\n",$1/1024/1024,$2}'
+
+# Final disk usage
+log "Disk usage cleanup:"
+df -h
+log "Top-level usage ( / ):"
+du -xh --max-depth=1 / | sort -rh | head -n 20
+
+log "=== Cleanup finished ==="
+exit 0

package/scripts/disk-devices.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# disk-devices.sh
+# List block devices with detailed info, including by-id names
+# Usage: sudo ./disk-devices.sh
+set -euo pipefail
+
+sudo bash -c 'printf "NODE\tTYPE\tSIZE\tFSTYPE\tLABEL\tUUID\tMOUNTPOINT\tBY-ID\n"; \
+lsblk -pnl -o NAME,TYPE,SIZE,FSTYPE,LABEL,UUID,MOUNTPOINT | while read -r DEV TYPE SIZE FS LBL UUID MNT; do \
+    node=$(readlink -f "$DEV"); \
+    byid=$(find /dev/disk/by-id/ -maxdepth 1 -lname "*${node##*/}" ! -name "nvme-eui*" ! -name "dm-uuid*" 2>/dev/null | head -n 1); \
+    [ -z "$byid" ] && byid=$(find /dev/disk/by-id/ -maxdepth 1 -lname "*${node##*/}" 2>/dev/null | head -n 1); \
+    printf "%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n" "$node" "$TYPE" "$SIZE" "$FS" "$LBL" "$UUID" "$MNT" "$(basename "$byid" 2>/dev/null)"; \
+done' | column -s $'\t' -t

package/scripts/gen-fqdns.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# gen-fqdns.sh - generate a readable plain table with FQDNs for all services and pods in the cluster
+
+set -euo pipefail
+
+CLUSTER_DOMAIN="${CLUSTER_DOMAIN:-cluster.local}"
+
+# Services: <service>.<namespace>.svc.<cluster-domain>
+kubectl get svc --all-namespaces -o custom-columns=NAMESPACE:.metadata.namespace,NAME:.metadata.name --no-headers \
+  | awk -v cd="$CLUSTER_DOMAIN" '{printf "%-20s %-34s %-6s %s.%s.svc.%s\n", $1, $2, "svc", $2, $1, cd}'
+
+# Pods: <pod>.<namespace>.pod.<cluster-domain>
+kubectl get pods --all-namespaces -o custom-columns=NAMESPACE:.metadata.namespace,NAME:.metadata.name --no-headers \
+  | awk -v cd="$CLUSTER_DOMAIN" '{printf "%-20s %-34s %-6s %s.%s.pod.%s\n", $1, $2, "pod", $2, $1, cd}'

package/scripts/gpu-diag.sh

@@ -0,0 +1,19 @@
+# GPUs and drivers in use
+sudo lspci -nnk | egrep -i 'vga|3d' -A3
+
+# modules loaded relevant
+lsmod | egrep 'nvidia|nouveau|amdgpu'
+
+# if exists nvidia tool
+nvidia-smi 2>/dev/null || echo "nvidia-smi not found"
+
+# kernel related errors
+sudo dmesg | egrep -i 'nvidia|nouveau|amdgpu' --color=auto
+
+# recent system errors / gdm / mutter / X
+sudo journalctl -b -p err --no-pager | head -n 200
+journalctl -b _COMM=gdm --no-pager | tail -n 200
+journalctl -b _COMM=Xorg --no-pager | tail -n 200
+
+# X log (if exists)
+sudo grep -E "(EE|WW|NVIDIA|nouveau|amdgpu)" /var/log/Xorg.0.log

package/scripts/ip-info.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+# ip-info.sh
+# Retrieve information about an IP address or hostname
+# Usage: ip-info.sh <IP-or-hostname>
+
+set -euo pipefail
+IFS=$'
+	'
+
+if [[ ${#} -lt 1 ]]; then
+  echo "Usage: $0 <IP-or-hostname>"
+  exit 1
+fi
+TARGET="$1"
+
+# Detect package manager
+PKG_MANAGER=""
+if command -v dnf >/dev/null 2>&1; then
+  PKG_MANAGER=dnf
+elif command -v yum >/dev/null 2>&1; then
+  PKG_MANAGER=yum
+fi
+
+# Commands we need (bind-utils provides dig)
+REQUIRED_CMDS=(curl jq whois dig traceroute)
+PKGS=(curl jq whois bind-utils traceroute)
+
+missing=()
+for i in "${!REQUIRED_CMDS[@]}"; do
+  cmd=${REQUIRED_CMDS[$i]}
+  if ! command -v "$cmd" >/dev/null 2>&1; then
+    missing+=("${PKGS[$i]}")
+  fi
+done
+
+if [[ ${#missing[@]} -gt 0 ]]; then
+  if [[ -z "$PKG_MANAGER" ]]; then
+    echo "Missing packages: ${missing[*]}
+No supported package manager found. Install: ${missing[*]} and re-run."
+    exit 1
+  fi
+  if [[ $EUID -ne 0 && -z "$(command -v sudo)" ]]; then
+    echo "Missing packages: ${missing[*]}
+Run as root or install sudo."
+    exit 1
+  fi
+  echo "Installing missing: ${missing[*]}"
+  sudo $PKG_MANAGER install -y ${missing[*]} >/dev/null
+fi
+
+# Resolve to IP(s)
+resolve_ips(){
+  if getent ahosts "$TARGET" >/dev/null 2>&1; then
+    getent ahosts "$TARGET" | awk '{print $1}' | sort -u
+  else
+    dig +short "$TARGET" | awk '/^[0-9]/ {print $1}' | sort -u
+  fi
+}
+
+mapfile -t IPS < <(resolve_ips)
+if [[ ${#IPS[@]} -eq 0 ]]; then
+  IPS=("$TARGET")
+fi
+
+format(){
+  if command -v jq >/dev/null 2>&1; then
+    jq '.' 2>/dev/null || cat
+  else
+    cat
+  fi
+}
+
+for IP in "${IPS[@]}"; do
+  printf "
+===== %s (resolved: %s) =====
+
+" "$TARGET" "$IP"
+
+  echo "-- REVERSE DNS --"
+  dig -x "$IP" +short
+
+  echo "
+-- WHOIS --"
+  whois "$IP" | sed -n '1,80p'
+
+  echo "
+-- IPINFO (ipinfo.io) --"
+  curl -sS "https://ipinfo.io/$IP/json" | format
+
+  echo "
+-- IP-API (ip-api.com) --"
+  curl -sS "http://ip-api.com/json/$IP?fields=status,message,country,regionName,city,zip,lat,lon,timezone,isp,org,as,query" | format
+
+  echo "
+-- IPWHOIS (ipwhois.app) --"
+  curl -sS "https://ipwhois.app/json/$IP" | format
+
+  echo "
+-- GEOPLUGIN --"
+  curl -sS "http://www.geoplugin.net/json.gp?ip=$IP" | format
+
+  echo "
+-- TRACEROUTE --"
+  traceroute -m 20 "$IP"
+
+  if [[ "$TARGET" =~ [A-Za-z] ]]; then
+    echo "
+-- DNS RECORDS for $TARGET --"
+    dig +short A "$TARGET"
+    dig +short AAAA "$TARGET"
+    dig +short MX "$TARGET"
+    dig +short TXT "$TARGET"
+  fi
+
+  echo "
+===== done: $IP =====
+"
+done

package/scripts/ipxe-setup.sh

@@ -0,0 +1,200 @@
+#!/bin/bash
+
+# --- Configuration ---
+# Set the target architecture you want to build for.
+# Options: "aarch64" (for ARM64 servers/devices) or "x86_64" (for standard Intel/AMD servers)
+TARGET_ARCH="${TARGET_ARCH:-aarch64}"
+
+IPXE_SRC_DIR="/home/dd/ipxe"
+EFI_FILENAME="ipxe.efi"
+
+# --- Argument Parsing ---
+TARGET_DIR_ARG=""
+REBUILD=false
+EMBED_SCRIPT=""
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --rebuild)
+            REBUILD=true
+            shift # past argument
+        ;;
+        --target-arch)
+            case "$2" in
+                arm64)
+                    TARGET_ARCH="aarch64"
+                ;;
+                amd64)
+                    TARGET_ARCH="x86_64"
+                ;;
+                *)
+                    echo "Error: Unsupported architecture '$2'. Use 'arm64' or 'amd64'."
+                    exit 1
+                ;;
+            esac
+            shift # past argument
+            shift # past value
+        ;;
+        --embed-script)
+            EMBED_SCRIPT="$2"
+            shift # past argument
+            shift # past value
+        ;;
+        *)
+            if [ -z "$TARGET_DIR_ARG" ]; then
+                TARGET_DIR_ARG="$1"
+            fi
+            shift # past argument
+        ;;
+    esac
+done
+
+# Use argument if provided, otherwise env var, otherwise current dir
+TARGET_DIR="${TARGET_DIR_ARG:-${TARGET_DIR:-.}}"
+
+# --- 1. Detect System Architecture ---
+HOST_ARCH=$(uname -m)
+echo "--- System Detection ---"
+echo "Host Architecture:   $HOST_ARCH"
+echo "Target Architecture: $TARGET_ARCH"
+echo "Target Directory:    $TARGET_DIR"
+echo "Rebuild Mode:        $REBUILD"
+echo "Embed Script:        ${EMBED_SCRIPT:-none}"
+
+# Determine iPXE build target based on requested architecture
+if [ "$TARGET_ARCH" = "aarch64" ]; then
+    BUILD_TARGET="bin-arm64-efi/ipxe.efi"
+    elif [ "$TARGET_ARCH" = "x86_64" ]; then
+    BUILD_TARGET="bin-x86_64-efi/ipxe.efi"
+else
+    echo "Error: Unsupported target architecture '$TARGET_ARCH'"
+    exit 1
+fi
+
+# Define the full path to the compiled binary
+COMPILED_SRC_PATH="$IPXE_SRC_DIR/src/$BUILD_TARGET"
+
+# Decide whether to build
+DO_BUILD=false
+
+if [ "$REBUILD" = true ]; then
+    DO_BUILD=true
+    elif [ ! -f "$COMPILED_SRC_PATH" ]; then
+    echo "Binary not found at $COMPILED_SRC_PATH. Initiating build..."
+    DO_BUILD=true
+    
+else
+    echo "Binary found at $COMPILED_SRC_PATH with matching embedded script. Skipping build."
+fi
+
+if [ "$DO_BUILD" = true ]; then
+    
+    # Helper function for package manager
+    if command -v dnf &> /dev/null; then
+        PKG_MGR="dnf"
+    else
+        PKG_MGR="yum"
+    fi
+    
+    # --- 2. Install Dependencies (RHEL/CentOS/Fedora) ---
+    echo ""
+    echo "--- Installing Build Dependencies ---"
+    echo "Requesting sudo permissions..."
+    
+    COMMON_PKGS="git make binutils-devel xz-devel perl"
+    
+    # Logic to determine if we need native or cross-compilers
+    if [ "$HOST_ARCH" = "$TARGET_ARCH" ]; then
+        # Native compilation
+        echo "Architecture match ($HOST_ARCH). Installing native GCC..."
+        sudo $PKG_MGR install -y $COMMON_PKGS gcc
+        CROSS_COMPILE_PREFIX=""
+        
+        elif [ "$HOST_ARCH" = "x86_64" ] && [ "$TARGET_ARCH" = "aarch64" ]; then
+        # Cross-compilation: x86_64 host -> aarch64 target
+        echo "Cross-compiling for $TARGET_ARCH on $HOST_ARCH..."
+        # Note: Ensure EPEL repo is enabled on RHEL/CentOS for this package
+        sudo $PKG_MGR install -y $COMMON_PKGS gcc-aarch64-linux-gnu
+        CROSS_COMPILE_PREFIX="aarch64-linux-gnu-"
+        
+    else
+        echo "Error: No automated path defined for Host: $HOST_ARCH -> Target: $TARGET_ARCH"
+        echo "You may need to install specific cross-compilers manually."
+        exit 1
+    fi
+    
+    # --- 3. Clone iPXE Source ---
+    echo ""
+    echo "--- Downloading iPXE Source Code ---"
+    if [ -d "$IPXE_SRC_DIR" ]; then
+        echo "Directory $IPXE_SRC_DIR already exists. Pulling latest changes..."
+        cd $IPXE_SRC_DIR
+        git pull
+    else
+        git clone https://github.com/ipxe/ipxe.git $IPXE_SRC_DIR
+        cd $IPXE_SRC_DIR
+    fi
+    
+    # --- 4. Compile the Binary ---
+    echo ""
+    echo "--- Compiling $EFI_FILENAME for $TARGET_ARCH ---"
+    cd src
+    
+    # Clean previous builds to ensure no arch mismatch
+    make clean
+    
+    # Build with embedded script if provided
+    if [ -n "$EMBED_SCRIPT" ]; then
+        echo "Embedding script into iPXE binary..."
+        if [ ! -f "$EMBED_SCRIPT" ]; then
+            echo "Error: Embed script file not found: $EMBED_SCRIPT"
+            exit 1
+        fi
+        echo "Running make for target: $BUILD_TARGET with EMBED=$EMBED_SCRIPT..."
+        make CROSS_COMPILE=$CROSS_COMPILE_PREFIX EMBED="$EMBED_SCRIPT" $BUILD_TARGET
+    else
+        echo "Running make for target: $BUILD_TARGET..."
+        make CROSS_COMPILE=$CROSS_COMPILE_PREFIX $BUILD_TARGET
+    fi
+    
+    if [ $? -ne 0 ]; then
+        echo "Error: Compilation failed."
+        if [ -n "$CROSS_COMPILE_PREFIX" ]; then
+            echo "Check that cross-compiler '$CROSS_COMPILE_PREFIX' is installed and in your PATH."
+        fi
+        exit 1
+    fi
+    
+    
+fi
+
+# --- 5. Deploy Binary ---
+echo ""
+echo "--- Deploying Binary ---"
+
+# Copy the file
+if [ -f "$COMPILED_SRC_PATH" ]; then
+    # Create target directory if it doesn't exist
+    if [ ! -d "$TARGET_DIR" ]; then
+        echo "Creating target directory: $TARGET_DIR"
+        mkdir -p "$TARGET_DIR"
+    fi
+    
+    echo "Copying $COMPILED_SRC_PATH to $TARGET_DIR/$EFI_FILENAME..."
+    cp "$COMPILED_SRC_PATH" "$TARGET_DIR/$EFI_FILENAME"
+    
+    if [ $? -eq 0 ]; then
+        echo "✓ Success!"
+        echo "---------------------------------------------------"
+        echo "Target: $TARGET_ARCH"
+        echo "Source: $COMPILED_SRC_PATH"
+        echo "Destination: $TARGET_DIR/$EFI_FILENAME"
+        echo "---------------------------------------------------"
+    else
+        echo "Error: Failed to copy file to $TARGET_DIR"
+        exit 1
+    fi
+else
+    echo "Error: Compiled file not found at $COMPILED_SRC_PATH"
+    exit 1
+fi

package/scripts/k3s-node-setup.sh

@@ -0,0 +1,124 @@
+#!/bin/bash
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Underpost K3s Node Setup
+#
+# This script runs INSIDE an LXD VM. It assumes the host has already mirrored
+# the project source into $ENGINE_ROOT (default /home/dd/engine) via the
+# `underpost lxd [vm-id] --vm-init` flow in `src/cli/lxd.js`. There is no
+# fallback to a globally installed `underpost`: every operational command
+# resolves from the local project so the latest local changes are always what
+# runs in the VM.
+#
+# Usage:
+#   --engine-root=<path>   Path to the mirrored engine source (default: /home/dd/engine)
+#   --control              Initialize as K3s control plane node (default)
+#   --worker               Initialize as K3s worker node
+#   --control-ip=<ip>      Control plane IP (required for --worker)
+#   --token=<token>        K3s node token (required for --worker)
+# ---------------------------------------------------------------------------
+
+ROLE="control"
+CONTROL_IP=""
+K3S_TOKEN=""
+ENGINE_ROOT="/home/dd/engine"
+
+for arg in "$@"; do
+    case $arg in
+        --worker)         ROLE="worker" ;;
+        --control)        ROLE="control" ;;
+        --control-ip=*)   CONTROL_IP="${arg#*=}" ;;
+        --token=*)        K3S_TOKEN="${arg#*=}" ;;
+        --engine-root=*)  ENGINE_ROOT="${arg#*=}" ;;
+    esac
+done
+
+# Fail fast if the bootstrap step did not run / left the directory empty.
+# Split into two checks so `ls -A` only runs against a path that exists; this
+# avoids needing an error-swallowing redirect.
+if [ ! -d "$ENGINE_ROOT" ]; then
+    echo "ERROR: engine source directory $ENGINE_ROOT does not exist."
+    echo "The LXD [vm-id] --vm-init flow must mirror the project here before running this script."
+    exit 1
+fi
+if [ -z "$(ls -A "$ENGINE_ROOT")" ]; then
+    echo "ERROR: engine source directory $ENGINE_ROOT is empty."
+    echo "The LXD [vm-id] --vm-init flow must mirror the project here before running this script."
+    exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# NVM and Node.js — required for `node bin ...` entrypoints
+# ---------------------------------------------------------------------------
+echo "Installing NVM and Node.js v24.15.0..."
+
+curl -o- https://cdn.jsdelivr.net/gh/nvm-sh/nvm@v0.40.1/install.sh | bash
+
+export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
+# shellcheck disable=SC1090
+[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
+
+nvm install 24.15.0
+nvm use 24.15.0
+nvm alias default 24.15.0
+ln -sf "$(command -v node)" /usr/local/bin/node
+ln -sf "$(command -v npm)" /usr/local/bin/npm
+ln -sf "$(command -v npx)" /usr/local/bin/npx
+
+echo "
+██╗░░░██╗███╗░░██╗██████╗░███████╗██████╗░██████╗░░█████╗░░██████╗████████╗
+██║░░░██║████╗░██║██╔══██╗██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔════╝╚══██╔══╝
+██║░░░██║██╔██╗██║██║░░██║█████╗░░██████╔╝██████╔╝██║░░██║╚█████╗░░░░██║░░░
+██║░░░██║██║╚████║██║░░██║██╔══╝░░██╔══██╗██╔═══╝░██║░░██║░╚═══██╗░░░██║░░░
+╚██████╔╝██║░╚███║██████╔╝███████╗██║░░██║██║░░░░░╚█████╔╝██████╔╝░░░██║░░░
+░╚═════╝░╚═╝░░╚══╝╚═════╝░╚══════╝╚═╝░░╚═╝╚═╝░░░░░░╚════╝░╚═════╝░░░░╚═╝░░░
+
+Bringing up underpost VM node from $ENGINE_ROOT (role=$ROLE)
+"
+
+cd "$ENGINE_ROOT"
+
+# Install JS deps and generate secrets using the local engine entrypoint only.
+npm install
+node bin run secret
+
+if [ "$ROLE" = "control" ]; then
+    echo "Installing underpost CLI..."
+    npm install -g underpost
+    underpost --version
+    echo "Initializing K3s control plane via local engine..."
+    node bin cluster --dev --k3s
+    ln -s /usr/local/bin/k3s /bin/k3s
+    ln -s /usr/local/bin/kubectl /bin/kubectl
+    
+    echo ""
+    echo "K3s control plane is ready."
+    echo "Node token (share with workers to join this cluster):"
+    sudo cat /var/lib/rancher/k3s/server/node-token
+    echo ""
+    echo "Control plane IP addresses:"
+    ip -4 addr show scope global | grep inet | awk '{print $2}' | cut -d/ -f1
+    
+    elif [ "$ROLE" = "worker" ]; then
+    if [ -z "$CONTROL_IP" ] || [ -z "$K3S_TOKEN" ]; then
+        echo "ERROR: --control-ip and --token are required for worker role."
+        echo "Usage: bash k3s-node-setup.sh --worker --control-ip=<ip> --token=<token>"
+        exit 1
+    fi
+    
+    # Worker nodes still need the minimal K3s host prep even though they join via
+    # the upstream installer rather than `node bin cluster --k3s`.
+    echo "Applying minimal K3s host configuration via local engine..."
+    node bin cluster --dev --config --k3s
+    
+    echo "Joining K3s cluster at https://${CONTROL_IP}:6443..."
+    curl -sfL https://get.k3s.io | \
+    K3S_URL="https://${CONTROL_IP}:6443" \
+    K3S_TOKEN="${K3S_TOKEN}" \
+    sh -s - agent
+    
+    echo ""
+    echo "K3s worker joined https://${CONTROL_IP}:6443 successfully."
+    sudo systemctl status k3s-agent --no-pager
+fi