@geekbeer/minion 1.0.0

package/.env.example

@@ -0,0 +1,22 @@
+# @geekbeer/minion - Agent Configuration
+# Copy this file to .env and fill in your values
+#
+# If HQ_URL and API_TOKEN are omitted, the agent runs in standalone mode
+# (no heartbeat, no HQ communication).
+
+# HQ URL (optional) - The URL of the HQ server
+# For managed service: https://minion.geekbeer.co.jp
+# For local Docker development: http://host.docker.internal:3000
+HQ_URL=
+
+# API Token (optional) - Get this from the HQ dashboard after creating a minion
+API_TOKEN=
+
+# Minion ID (optional) - The minion's UUID assigned by HQ
+MINION_ID=
+
+# Agent port (optional, default: 3001)
+AGENT_PORT=3001
+
+# Heartbeat interval in seconds (optional, default: 30)
+HEARTBEAT_INTERVAL=30

package/api.js

@@ -0,0 +1,76 @@
+/**
+ * API Client for Minion Agent
+ * Communicates with the Minion management API
+ *
+ * In standalone mode (no HQ configured), all API calls are no-ops.
+ */
+
+const { config, isHqConfigured } = require('./config')
+
+/**
+ * Send HTTP request to the HQ server
+ * @param {string} endpoint - API endpoint path
+ * @param {object} options - Fetch options
+ */
+async function request(endpoint, options = {}) {
+  if (!isHqConfigured()) {
+    return { skipped: true, reason: 'HQ not configured' }
+  }
+
+  const url = `${config.HQ_URL}/api/minion${endpoint}`
+
+  const response = await fetch(url, {
+    ...options,
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${config.API_TOKEN}`,
+      ...options.headers,
+    },
+  })
+
+  const data = await response.json()
+
+  if (!response.ok) {
+    throw new Error(data.error || `API request failed: ${response.status}`)
+  }
+
+  return data
+}
+
+/**
+ * Send heartbeat with status update
+ * @param {string} status - 'online' | 'offline' | 'busy'
+ * @param {string|null} currentTask - Current task description
+ */
+async function sendHeartbeat(status, currentTask = null) {
+  return request('/heartbeat', {
+    method: 'POST',
+    body: JSON.stringify({
+      status,
+      current_task: currentTask,
+    }),
+  })
+}
+
+/**
+ * Send a log entry
+ * @param {string} message - Log message
+ * @param {'info'|'warning'|'error'} level - Log level
+ * @param {object|null} metadata - Additional metadata
+ */
+async function log(message, level = 'info', metadata = null) {
+  return request('/log', {
+    method: 'POST',
+    body: JSON.stringify({
+      message,
+      level,
+      metadata,
+    }),
+  })
+}
+
+module.exports = {
+  request,
+  sendHeartbeat,
+  log,
+}

package/config.js

@@ -0,0 +1,48 @@
+/**
+ * Minion Agent Configuration
+ *
+ * Optional environment variables (for HQ connection):
+ * - HQ_URL: The URL of the HQ server (e.g., https://minion.geekbeer.co.jp)
+ * - API_TOKEN: The API token for this minion (obtained from dashboard)
+ * - MINION_ID: The minion's UUID (assigned by HQ)
+ *
+ * If HQ_URL and API_TOKEN are not set, the agent runs in standalone mode
+ * (no heartbeat, no HQ communication).
+ *
+ * Other optional environment variables:
+ * - AGENT_PORT: Port for the local agent server (default: 3001)
+ * - HEARTBEAT_INTERVAL: Interval between heartbeats in seconds (default: 30)
+ */
+
+const config = {
+  // HQ Server Configuration (optional - omit for standalone mode)
+  HQ_URL: process.env.HQ_URL || '',
+  API_TOKEN: process.env.API_TOKEN || '',
+  MINION_ID: process.env.MINION_ID || '',
+
+  // Server settings
+  AGENT_PORT: parseInt(process.env.AGENT_PORT, 10) || 3001,
+
+  // Heartbeat interval in seconds
+  HEARTBEAT_INTERVAL: parseInt(process.env.HEARTBEAT_INTERVAL, 10) || 30,
+}
+
+/**
+ * Check if HQ connection is configured
+ */
+function isHqConfigured() {
+  return !!(config.HQ_URL && config.API_TOKEN)
+}
+
+/**
+ * Validate configuration and log mode
+ */
+function validate() {
+  if (isHqConfigured()) {
+    console.log(`[Config] HQ configured: ${config.HQ_URL}`)
+  } else {
+    console.log('[Config] HQ not configured, running in standalone mode')
+  }
+}
+
+module.exports = { config, validate, isHqConfigured }

package/heartbeat.js

@@ -0,0 +1,91 @@
+/**
+ * Heartbeat Manager for Minion Agent
+ * Sends periodic heartbeats to the API
+ */
+
+const { config } = require('./config')
+const api = require('./api')
+
+// Current state
+let currentStatus = 'online'
+let currentTask = null
+let intervalId = null
+
+/**
+ * Start the heartbeat loop
+ */
+function start() {
+  console.log(`[Heartbeat] Starting with interval: ${config.HEARTBEAT_INTERVAL}s`)
+
+  // Send initial heartbeat
+  sendHeartbeat()
+
+  // Schedule periodic heartbeats
+  intervalId = setInterval(sendHeartbeat, config.HEARTBEAT_INTERVAL * 1000)
+}
+
+/**
+ * Stop the heartbeat loop
+ */
+function stop() {
+  if (intervalId) {
+    clearInterval(intervalId)
+    intervalId = null
+    console.log('[Heartbeat] Stopped')
+  }
+}
+
+/**
+ * Send a heartbeat to the API
+ */
+async function sendHeartbeat() {
+  try {
+    await api.sendHeartbeat(currentStatus, currentTask)
+    console.log(`[Heartbeat] Sent: status=${currentStatus}, task=${currentTask || 'none'}`)
+  } catch (error) {
+    console.error(`[Heartbeat] Failed: ${error.message}`)
+  }
+}
+
+/**
+ * Set the current status
+ * @param {'online'|'offline'|'busy'} status
+ */
+function setStatus(status) {
+  if (!['online', 'offline', 'busy'].includes(status)) {
+    throw new Error(`Invalid status: ${status}`)
+  }
+  currentStatus = status
+}
+
+/**
+ * Set the current task
+ * @param {string|null} task
+ */
+function setTask(task) {
+  currentTask = task || null
+}
+
+/**
+ * Get the current status
+ */
+function getStatus() {
+  return currentStatus
+}
+
+/**
+ * Get the current task
+ */
+function getTask() {
+  return currentTask
+}
+
+module.exports = {
+  start,
+  stop,
+  sendHeartbeat,
+  setStatus,
+  setTask,
+  getStatus,
+  getTask,
+}

package/minion-cli.sh

@@ -0,0 +1,445 @@
+#!/usr/bin/env bash
+#
+# Minion Agent CLI (@geekbeer/minion)
+# CLI tool for interacting with and setting up the minion agent
+#
+# Usage:
+#   minion-cli setup [options]               # Set up minion agent service
+#   minion-cli start                         # Start agent service
+#   minion-cli stop                          # Stop agent service
+#   minion-cli restart                       # Restart agent service
+#   minion-cli status                        # Get current status
+#   minion-cli health                        # Health check
+#   minion-cli set-status busy "Running X"   # Set status and task
+#   minion-cli set-status online             # Set status only
+#   minion-cli log "Message" [level] [skill] # Send log entry
+#
+# Setup options:
+#   --hq-url <URL>        HQ server URL (optional, omit for standalone mode)
+#   --minion-id <UUID>    Minion ID (optional)
+#   --api-token <TOKEN>   API token (optional)
+#   --setup-tunnel        Set up cloudflared tunnel (requires --hq-url and --api-token)
+
+set -euo pipefail
+
+# Resolve version from package.json (installed location)
+CLI_DIR="$(cd "$(dirname "$(readlink -f "$0")")" && pwd)"
+CLI_VERSION="$(node -p "require('${CLI_DIR}/package.json').version")"
+
+# Use sudo only when not running as root
+SUDO=""
+if [ "$(id -u)" -ne 0 ] && command -v sudo &>/dev/null; then
+  SUDO="sudo"
+fi
+
+# Detect process manager: systemd or supervisord
+# systemd takes priority when both are available (standard Linux VPS)
+SERVICE_NAME="minion-agent"
+if command -v systemctl &>/dev/null && systemctl --version &>/dev/null 2>&1; then
+  PROC_MGR="systemd"
+elif command -v supervisorctl &>/dev/null; then
+  PROC_MGR="supervisord"
+else
+  PROC_MGR=""
+fi
+
+# Service control helper
+svc_control() {
+  local action="$1"
+  case "$PROC_MGR" in
+    systemd)
+      $SUDO systemctl "$action" "$SERVICE_NAME"
+      ;;
+    supervisord)
+      $SUDO supervisorctl "$action" "$SERVICE_NAME"
+      ;;
+    *)
+      echo "Error: No supported process manager found (systemd or supervisord)"
+      exit 1
+      ;;
+  esac
+}
+
+AGENT_URL="${MINION_AGENT_URL:-http://localhost:3001}"
+
+# ============================================================
+# setup subcommand
+# ============================================================
+do_setup() {
+  local HQ_URL=""
+  local MINION_ID=""
+  local API_TOKEN=""
+  local SETUP_TUNNEL=false
+
+  # Parse arguments
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --hq-url)
+        HQ_URL="$2"
+        shift 2
+        ;;
+      --minion-id)
+        MINION_ID="$2"
+        shift 2
+        ;;
+      --api-token)
+        API_TOKEN="$2"
+        shift 2
+        ;;
+      --setup-tunnel)
+        SETUP_TUNNEL=true
+        shift
+        ;;
+      *)
+        echo "Unknown option: $1"
+        echo "Usage: minion-cli setup [--hq-url <URL>] [--minion-id <UUID>] [--api-token <TOKEN>] [--setup-tunnel]"
+        exit 1
+        ;;
+    esac
+  done
+
+  echo "========================================="
+  echo " @geekbeer/minion Setup"
+  echo "========================================="
+
+  if [ -n "$HQ_URL" ]; then
+    echo "Mode: Connected to HQ ($HQ_URL)"
+  else
+    echo "Mode: Standalone (no HQ connection)"
+  fi
+  if [ "$SETUP_TUNNEL" = true ]; then
+    echo "Tunnel: Enabled"
+  fi
+  echo ""
+
+  local TOTAL_STEPS=5
+  if [ "$SETUP_TUNNEL" = true ]; then
+    TOTAL_STEPS=6
+  fi
+
+  # Step 1: Create config directory
+  echo "[1/${TOTAL_STEPS}] Creating config directory..."
+  $SUDO mkdir -p /opt/minion-agent
+  echo "  -> /opt/minion-agent/ created"
+
+  # Step 2: Generate .env file
+  echo "[2/${TOTAL_STEPS}] Generating .env file..."
+  local ENV_CONTENT=""
+  ENV_CONTENT+="# Minion Agent Configuration\n"
+  ENV_CONTENT+="# Generated by minion-cli setup\n\n"
+
+  if [ -n "$HQ_URL" ]; then
+    ENV_CONTENT+="HQ_URL=${HQ_URL}\n"
+  fi
+  if [ -n "$API_TOKEN" ]; then
+    ENV_CONTENT+="API_TOKEN=${API_TOKEN}\n"
+  fi
+  if [ -n "$MINION_ID" ]; then
+    ENV_CONTENT+="MINION_ID=${MINION_ID}\n"
+  fi
+
+  ENV_CONTENT+="AGENT_PORT=3001\n"
+  ENV_CONTENT+="HEARTBEAT_INTERVAL=30\n"
+
+  echo -e "$ENV_CONTENT" | $SUDO tee /opt/minion-agent/.env > /dev/null
+  echo "  -> /opt/minion-agent/.env generated"
+
+  # Step 3: Create service configuration
+  echo "[3/${TOTAL_STEPS}] Creating service configuration ($PROC_MGR)..."
+  local NPM_ROOT
+  NPM_ROOT="$(npm root -g)"
+  local SERVER_PATH="${NPM_ROOT}/@geekbeer/minion/server.js"
+
+  if [ ! -f "$SERVER_PATH" ]; then
+    echo "  ERROR: server.js not found at $SERVER_PATH"
+    echo "  Please run: npm install -g @geekbeer/minion"
+    exit 1
+  fi
+
+  case "$PROC_MGR" in
+    systemd)
+      $SUDO tee /etc/systemd/system/minion-agent.service > /dev/null <<SVCEOF
+[Unit]
+Description=Minion Agent API (@geekbeer/minion)
+After=network.target
+
+[Service]
+Type=simple
+User=root
+WorkingDirectory=/opt/minion-agent
+ExecStart=/usr/bin/node ${SERVER_PATH}
+Restart=always
+RestartSec=10
+EnvironmentFile=/opt/minion-agent/.env
+
+[Install]
+WantedBy=multi-user.target
+SVCEOF
+      echo "  -> /etc/systemd/system/minion-agent.service created"
+      ;;
+
+    supervisord)
+      # Build environment line from .env values
+      local ENV_LINE="environment="
+      local ENV_PAIRS=()
+      while IFS='=' read -r key value; do
+        [[ -z "$key" || "$key" == \#* ]] && continue
+        ENV_PAIRS+=("${key}=\"${value}\"")
+      done < /opt/minion-agent/.env
+      ENV_LINE+="$(IFS=,; echo "${ENV_PAIRS[*]}")"
+
+      $SUDO tee /etc/supervisor/conf.d/minion-agent.conf > /dev/null <<SUPEOF
+[program:minion-agent]
+command=/usr/bin/node ${SERVER_PATH}
+directory=/opt/minion-agent
+${ENV_LINE}
+autorestart=true
+priority=500
+startsecs=3
+stdout_logfile=/var/log/supervisor/minion-agent.log
+stderr_logfile=/var/log/supervisor/minion-agent.log
+SUPEOF
+      echo "  -> /etc/supervisor/conf.d/minion-agent.conf created"
+      ;;
+
+    *)
+      echo "  ERROR: No supported process manager found (systemd or supervisord)"
+      exit 1
+      ;;
+  esac
+
+  # Step 4: Enable and start service
+  echo "[4/${TOTAL_STEPS}] Starting minion-agent service..."
+  case "$PROC_MGR" in
+    systemd)
+      $SUDO systemctl daemon-reload
+      $SUDO systemctl enable minion-agent
+      $SUDO systemctl start minion-agent
+      ;;
+    supervisord)
+      if $SUDO supervisorctl status &>/dev/null; then
+        $SUDO supervisorctl reread
+        $SUDO supervisorctl update
+      else
+        echo "  -> supervisord not running; config will be loaded on next start"
+      fi
+      ;;
+  esac
+  echo "  -> minion-agent service started ($PROC_MGR)"
+
+  # Step 5: Health check with retry
+  echo "[5/${TOTAL_STEPS}] Running health check..."
+  local RETRIES=5
+  local DELAY=2
+  local SUCCESS=false
+
+  for i in $(seq 1 $RETRIES); do
+    if curl -sf http://localhost:3001/api/health > /dev/null 2>&1; then
+      SUCCESS=true
+      break
+    fi
+    echo "  Waiting for agent to start... (attempt $i/$RETRIES)"
+    sleep $DELAY
+  done
+
+  if [ "$SUCCESS" = true ]; then
+    echo "  -> Health check passed"
+  else
+    echo "  WARNING: Health check failed after $RETRIES attempts"
+    if [ "$PROC_MGR" = "systemd" ]; then
+      echo "  Check logs with: journalctl -u minion-agent -f"
+    else
+      echo "  Check logs with: tail -f /var/log/supervisor/minion-agent.log"
+    fi
+  fi
+
+  # Notify HQ if configured
+  if [ -n "$HQ_URL" ] && [ -n "$API_TOKEN" ]; then
+    echo ""
+    echo "Notifying HQ of setup completion..."
+    local NOTIFY_RESPONSE
+    NOTIFY_RESPONSE=$(curl -sf -X POST "${HQ_URL}/api/minion/setup-complete" \
+      -H "Content-Type: application/json" \
+      -H "Authorization: Bearer ${API_TOKEN}" \
+      -d "{}" 2>&1) || true
+
+    if echo "$NOTIFY_RESPONSE" | grep -q '"success":true' 2>/dev/null; then
+      echo "  -> HQ notified successfully"
+    else
+      echo "  -> HQ notification skipped (HQ may not be reachable)"
+    fi
+  fi
+
+  # Step 6 (optional): Cloudflare Tunnel setup
+  if [ "$SETUP_TUNNEL" = true ]; then
+    echo ""
+    echo "[6/${TOTAL_STEPS}] Setting up Cloudflare Tunnel..."
+
+    if [ -z "$HQ_URL" ] || [ -z "$API_TOKEN" ]; then
+      echo "  ERROR: --setup-tunnel requires --hq-url and --api-token"
+      exit 1
+    fi
+
+    # Install cloudflared if not present
+    if ! command -v cloudflared &>/dev/null; then
+      echo "  Installing cloudflared..."
+      curl -fsSL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb \
+        -o /tmp/cloudflared.deb
+      $SUDO dpkg -i /tmp/cloudflared.deb
+      rm -f /tmp/cloudflared.deb
+    else
+      echo "  -> cloudflared already installed"
+    fi
+
+    # Fetch tunnel config from HQ API
+    # Response contains credentials_json and config_yml (generated server-side)
+    echo "  Fetching tunnel configuration from HQ..."
+    local TUNNEL_DATA
+    TUNNEL_DATA=$(curl -sf -H "Authorization: Bearer ${API_TOKEN}" \
+      "${HQ_URL}/api/minion/tunnel-credentials" 2>&1) || true
+
+    if [ -z "$TUNNEL_DATA" ] || ! echo "$TUNNEL_DATA" | jq -e '.tunnel_id' > /dev/null 2>&1; then
+      echo "  ERROR: Failed to fetch tunnel credentials from HQ"
+      echo "  Tunnel may not be configured for this minion yet"
+      echo "  Skipping tunnel setup (agent is running without tunnel)"
+    else
+      local TUNNEL_ID CREDS_JSON CONFIG_YML
+      TUNNEL_ID=$(echo "$TUNNEL_DATA" | jq -r '.tunnel_id')
+      CREDS_JSON=$(echo "$TUNNEL_DATA" | jq -r '.credentials_json')
+      CONFIG_YML=$(echo "$TUNNEL_DATA" | jq -r '.config_yml')
+
+      # Save credentials file (content from HQ, saved as-is)
+      $SUDO mkdir -p /etc/cloudflared
+      echo "$CREDS_JSON" | $SUDO tee "/etc/cloudflared/${TUNNEL_ID}.json" > /dev/null
+      $SUDO chmod 600 "/etc/cloudflared/${TUNNEL_ID}.json"
+      $SUDO chown root:root "/etc/cloudflared/${TUNNEL_ID}.json"
+      echo "  -> /etc/cloudflared/${TUNNEL_ID}.json saved"
+
+      # Save config file (content from HQ, saved as-is)
+      echo "$CONFIG_YML" | $SUDO tee /etc/cloudflared/config.yml > /dev/null
+      echo "  -> /etc/cloudflared/config.yml saved"
+
+      # Install and start cloudflared service
+      $SUDO cloudflared service install 2>/dev/null || true
+      $SUDO systemctl enable cloudflared 2>/dev/null || true
+      $SUDO systemctl start cloudflared 2>/dev/null || true
+      echo "  -> cloudflared tunnel configured and started"
+    fi
+  fi
+
+  echo ""
+  echo "========================================="
+  echo " Setup Complete!"
+  echo "========================================="
+  echo ""
+  echo "Useful commands:"
+  echo "  minion-cli status                     # Agent status"
+  echo "  minion-cli health                     # Health check"
+  echo "  minion-cli restart                    # Restart agent"
+  echo "  minion-cli stop                       # Stop agent"
+  if [ "$PROC_MGR" = "systemd" ]; then
+    echo "  journalctl -u minion-agent -f         # View logs"
+  else
+    echo "  tail -f /var/log/supervisor/minion-agent.log  # View logs"
+  fi
+}
+
+# ============================================================
+# Main command dispatch
+# ============================================================
+case "${1:-}" in
+  --version|-v)
+    echo "@geekbeer/minion v${CLI_VERSION}"
+    ;;
+
+  setup)
+    shift
+    do_setup "$@"
+    ;;
+
+  status)
+    curl -s "$AGENT_URL/api/status" | jq .
+    ;;
+
+  set-status)
+    STATUS="${2:-online}"
+    TASK="${3:-}"
+
+    if [ -n "$TASK" ]; then
+      curl -s -X POST "$AGENT_URL/api/status" \
+        -H "Content-Type: application/json" \
+        -d "{\"status\": \"$STATUS\", \"current_task\": \"$TASK\"}" | jq .
+    else
+      curl -s -X POST "$AGENT_URL/api/status" \
+        -H "Content-Type: application/json" \
+        -d "{\"status\": \"$STATUS\", \"current_task\": null}" | jq .
+    fi
+    ;;
+
+  log)
+    MESSAGE="${2:-}"
+    LEVEL="${3:-info}"
+    SKILL="${4:-}"
+
+    if [ -z "$MESSAGE" ]; then
+      echo "Usage: minion-cli log \"message\" [level] [skill_name]"
+      exit 1
+    fi
+
+    if [ -n "$SKILL" ]; then
+      curl -s -X POST "$AGENT_URL/api/log" \
+        -H "Content-Type: application/json" \
+        -d "{\"message\": \"$MESSAGE\", \"level\": \"$LEVEL\", \"skill_name\": \"$SKILL\"}" | jq .
+    else
+      curl -s -X POST "$AGENT_URL/api/log" \
+        -H "Content-Type: application/json" \
+        -d "{\"message\": \"$MESSAGE\", \"level\": \"$LEVEL\"}" | jq .
+    fi
+    ;;
+
+  health)
+    curl -s "$AGENT_URL/api/health" | jq .
+    ;;
+
+  start)
+    svc_control start
+    echo "minion-agent started ($PROC_MGR)"
+    ;;
+
+  stop)
+    svc_control stop
+    echo "minion-agent stopped ($PROC_MGR)"
+    ;;
+
+  restart)
+    svc_control restart
+    echo "minion-agent restarted ($PROC_MGR)"
+    ;;
+
+  *)
+    echo "Minion Agent CLI (@geekbeer/minion) v${CLI_VERSION}"
+    echo ""
+    echo "Usage:"
+    echo "  minion-cli setup [options]                # Set up agent service"
+    echo "  minion-cli start                          # Start agent service"
+    echo "  minion-cli stop                           # Stop agent service"
+    echo "  minion-cli restart                        # Restart agent service"
+    echo "  minion-cli status                         # Get current status"
+    echo "  minion-cli health                         # Health check"
+    echo "  minion-cli set-status <status> [task]     # Set status and optional task"
+    echo "  minion-cli log <message> [level] [skill]  # Send log entry"
+    echo "  minion-cli --version                       # Show version"
+    echo ""
+    echo "Setup options:"
+    echo "  --hq-url <URL>        HQ server URL (optional)"
+    echo "  --minion-id <UUID>    Minion ID (optional)"
+    echo "  --api-token <TOKEN>   API token (optional)"
+    echo "  --setup-tunnel        Set up cloudflared tunnel (requires --hq-url, --api-token)"
+    echo ""
+    echo "Status values: online, offline, busy"
+    echo "Log levels: info, warn, error"
+    echo ""
+    echo "Environment:"
+    echo "  MINION_AGENT_URL  Agent URL (default: http://localhost:3001)"
+    ;;
+esac

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@geekbeer/minion",
+  "version": "1.0.0",
+  "description": "AI Agent runtime for Minion - manages heartbeat, status, and skill deployment on VPS",
+  "main": "server.js",
+  "bin": {
+    "minion-cli": "./minion-cli.sh"
+  },
+  "files": [
+    "server.js",
+    "config.js",
+    "heartbeat.js",
+    "api.js",
+    "minion-cli.sh",
+    ".env.example"
+  ],
+  "scripts": {
+    "start": "node server.js"
+  },
+  "dependencies": {
+    "fastify": "^5.2.2"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "ai-agent",
+    "minion",
+    "claude",
+    "automation"
+  ],
+  "license": "MIT"
+}

package/server.js

@@ -0,0 +1,563 @@
+/**
+ * Minion Agent HTTP Server
+ * Provides local status reporting and control endpoints
+ */
+
+const { exec, execSync } = require('child_process')
+const { promisify } = require('util')
+const fs = require('fs').promises
+const path = require('path')
+const os = require('os')
+const execAsync = promisify(exec)
+
+const fastify = require('fastify')({ logger: true })
+const { config, validate, isHqConfigured } = require('./config')
+const heartbeat = require('./heartbeat')
+const api = require('./api')
+
+// Detect process manager (matching minion-cli.sh logic)
+function detectProcessManager() {
+  try {
+    execSync('systemctl --version', { stdio: 'ignore' })
+    return 'systemd'
+  } catch {
+    // systemd not available
+  }
+  try {
+    execSync('which supervisorctl', { stdio: 'ignore' })
+    return 'supervisord'
+  } catch {
+    // supervisord not available
+  }
+  return 'standalone'
+}
+
+const PROC_MGR = detectProcessManager()
+
+// Use sudo only when not running as root
+const SUDO = process.getuid && process.getuid() !== 0 ? 'sudo ' : ''
+
+// Build allowed commands based on detected process manager
+function buildAllowedCommands() {
+  const commands = {}
+
+  if (PROC_MGR === 'systemd') {
+    commands['restart-agent'] = {
+      description: 'Restart the minion agent service',
+      command: `${SUDO}systemctl restart minion-agent`,
+      deferred: true,
+    }
+    commands['update-agent'] = {
+      description: 'Update @geekbeer/minion to latest version and restart',
+      command: `npm update -g @geekbeer/minion && ${SUDO}systemctl restart minion-agent`,
+      deferred: true,
+    }
+    commands['restart-display'] = {
+      description: 'Restart Xvfb and noVNC services',
+      command: `${SUDO}systemctl restart xvfb novnc`,
+    }
+    commands['status-services'] = {
+      description: 'Check status of all services',
+      command: 'systemctl status minion-agent xvfb novnc --no-pager',
+    }
+  } else if (PROC_MGR === 'supervisord') {
+    commands['restart-agent'] = {
+      description: 'Restart the minion agent service',
+      command: `${SUDO}supervisorctl restart minion-agent`,
+      deferred: true,
+    }
+    commands['update-agent'] = {
+      description: 'Update @geekbeer/minion to latest version and restart',
+      command: `npm update -g @geekbeer/minion && ${SUDO}supervisorctl restart minion-agent`,
+      deferred: true,
+    }
+    commands['restart-display'] = {
+      description: 'Restart Xvfb, x11vnc and noVNC services',
+      command: `${SUDO}supervisorctl restart xvfb fluxbox x11vnc novnc`,
+    }
+    commands['status-services'] = {
+      description: 'Check status of all services',
+      command: `${SUDO}supervisorctl status`,
+    }
+  } else {
+    // Standalone mode: limited commands
+    commands['update-agent'] = {
+      description: 'Update @geekbeer/minion to latest version',
+      command: 'npm update -g @geekbeer/minion',
+    }
+    commands['status-services'] = {
+      description: 'Show agent process info',
+      command: 'echo "Process Manager: standalone (no systemd/supervisord)" && echo "Agent PID: $$" && echo "Node version: $(node -v)" && echo "Uptime: $(ps -o etime= -p $$)"',
+    }
+  }
+
+  return commands
+}
+
+const ALLOWED_COMMANDS = buildAllowedCommands()
+
+/**
+ * Verify API token from Authorization header
+ */
+function verifyToken(request) {
+  const authHeader = request.headers.authorization
+  if (!authHeader?.startsWith('Bearer ')) {
+    return false
+  }
+  const token = authHeader.substring(7)
+  return token === config.API_TOKEN
+}
+
+// Validate configuration before starting
+validate()
+console.log(`[Config] Process manager: ${PROC_MGR}`)
+console.log(`[Config] Available commands: ${Object.keys(ALLOWED_COMMANDS).join(', ')}`)
+
+// Health check endpoint
+fastify.get('/api/health', async () => {
+  return {
+    status: 'ok',
+    timestamp: new Date().toISOString(),
+  }
+})
+
+// Get current status
+fastify.get('/api/status', async () => {
+  return {
+    status: heartbeat.getStatus(),
+    current_task: heartbeat.getTask(),
+    uptime: process.uptime(),
+    timestamp: new Date().toISOString(),
+  }
+})
+
+// Update status
+fastify.post('/api/status', async (request, reply) => {
+  const { status, current_task } = request.body || {}
+
+  try {
+    if (status) {
+      heartbeat.setStatus(status)
+    }
+
+    if (current_task !== undefined) {
+      heartbeat.setTask(current_task)
+    }
+
+    // Immediately send heartbeat with new status
+    await heartbeat.sendHeartbeat()
+
+    return { success: true }
+  } catch (error) {
+    reply.code(400)
+    return { success: false, error: error.message }
+  }
+})
+
+// Send log entry
+fastify.post('/api/log', async (request, reply) => {
+  const { message, level = 'info', metadata } = request.body || {}
+
+  if (!message) {
+    reply.code(400)
+    return { success: false, error: 'message is required' }
+  }
+
+  try {
+    await api.log(message, level, metadata)
+    return { success: true }
+  } catch (error) {
+    reply.code(500)
+    return { success: false, error: error.message }
+  }
+})
+
+// List available commands
+fastify.get('/api/commands', async (request, reply) => {
+  // Require authentication
+  if (!verifyToken(request)) {
+    reply.code(401)
+    return { success: false, error: 'Unauthorized' }
+  }
+
+  return {
+    commands: Object.entries(ALLOWED_COMMANDS).map(([name, info]) => ({
+      name,
+      description: info.description,
+    })),
+  }
+})
+
+// Change VNC password
+fastify.post('/api/vnc-password', async (request, reply) => {
+  // Require authentication
+  if (!verifyToken(request)) {
+    reply.code(401)
+    return { success: false, error: 'Unauthorized' }
+  }
+
+  const { password } = request.body || {}
+
+  if (!password || password.length < 1) {
+    reply.code(400)
+    return { success: false, error: 'password is required' }
+  }
+
+  console.log('[VNC] Changing VNC password')
+
+  try {
+    // Log password change to HQ
+    await api.log('Changing VNC password', 'info')
+
+    // Escape single quotes in password for shell safety
+    const escapedPassword = password.replace(/'/g, "'\\''")
+
+    // Use x11vnc to store the new password
+    await execAsync(
+      `x11vnc -storepasswd '${escapedPassword}' ~/.vnc/passwd`,
+      { timeout: 10000 }
+    )
+
+    // Restart x11vnc to apply the new password
+    if (PROC_MGR === 'systemd') {
+      await execAsync(`${SUDO}systemctl restart x11vnc`, { timeout: 10000 })
+    } else if (PROC_MGR === 'supervisord') {
+      await execAsync(`${SUDO}supervisorctl restart x11vnc`, { timeout: 10000 })
+    }
+
+    console.log('[VNC] Password changed successfully')
+
+    return {
+      success: true,
+      message: 'VNC password changed successfully',
+    }
+  } catch (error) {
+    console.error(`[VNC] Failed to change password: ${error.message}`)
+
+    // Log error to HQ
+    await api.log(`Failed to change VNC password: ${error.message}`, 'error')
+
+    reply.code(500)
+    return {
+      success: false,
+      error: error.message,
+    }
+  }
+})
+
+// Execute a whitelisted command
+fastify.post('/api/command', async (request, reply) => {
+  // Require authentication
+  if (!verifyToken(request)) {
+    reply.code(401)
+    return { success: false, error: 'Unauthorized' }
+  }
+
+  const { command } = request.body || {}
+
+  if (!command) {
+    reply.code(400)
+    return { success: false, error: 'command is required' }
+  }
+
+  // Check if command is in whitelist
+  const allowedCommand = ALLOWED_COMMANDS[command]
+  if (!allowedCommand) {
+    reply.code(403)
+    return {
+      success: false,
+      error: `Command '${command}' is not allowed`,
+      allowed_commands: Object.keys(ALLOWED_COMMANDS),
+    }
+  }
+
+  console.log(`[Command] Executing: ${command}`)
+
+  // Log command execution to HQ
+  await api.log(`Executing command: ${command}`, 'info', { command })
+
+  // Deferred commands (e.g. restart-agent) kill the current process,
+  // so respond first and execute after a short delay.
+  if (allowedCommand.deferred) {
+    console.log(`[Command] Scheduling deferred command: ${command}`)
+    setTimeout(() => {
+      exec(allowedCommand.command, { timeout: 60000 }, (err) => {
+        if (err) console.error(`[Command] Deferred command failed: ${command} - ${err.message}`)
+        else console.log(`[Command] Deferred command completed: ${command}`)
+      })
+    }, 1000)
+
+    return {
+      success: true,
+      command,
+      output: 'Command scheduled for execution',
+      deferred: true,
+    }
+  }
+
+  try {
+    const { stdout, stderr } = await execAsync(allowedCommand.command, {
+      timeout: 60000, // 60 second timeout
+    })
+
+    console.log(`[Command] Success: ${command}`)
+
+    return {
+      success: true,
+      command,
+      output: stdout,
+      stderr: stderr || undefined,
+    }
+  } catch (error) {
+    console.error(`[Command] Failed: ${command} - ${error.message}`)
+
+    // Log error to HQ
+    await api.log(`Command failed: ${command} - ${error.message}`, 'error', { command, error: error.message })
+
+    reply.code(500)
+    return {
+      success: false,
+      command,
+      error: error.message,
+      stdout: error.stdout,
+      stderr: error.stderr,
+    }
+  }
+})
+
+// List deployed skills from local .claude/skills directory
+fastify.get('/api/list-skills', async (request, reply) => {
+  // Require authentication
+  if (!verifyToken(request)) {
+    reply.code(401)
+    return { success: false, error: 'Unauthorized' }
+  }
+
+  console.log('[Skills] Listing deployed skills')
+
+  try {
+    const homeDir = os.homedir()
+    const skillsDir = path.join(homeDir, '.claude', 'skills')
+
+    // Check if skills directory exists
+    try {
+      await fs.access(skillsDir)
+    } catch {
+      // Directory doesn't exist, return empty list
+      console.log('[Skills] Skills directory does not exist, returning empty list')
+      return { success: true, skills: [] }
+    }
+
+    // Read directory contents
+    const entries = await fs.readdir(skillsDir, { withFileTypes: true })
+
+    // Filter to only directories that contain SKILL.md
+    const skills = []
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const skillMdPath = path.join(skillsDir, entry.name, 'SKILL.md')
+        try {
+          await fs.access(skillMdPath)
+          skills.push(entry.name)
+        } catch {
+          // SKILL.md doesn't exist, skip this directory
+        }
+      }
+    }
+
+    console.log(`[Skills] Found ${skills.length} deployed skills: ${skills.join(', ') || '(none)'}`)
+
+    return { success: true, skills }
+  } catch (error) {
+    console.error(`[Skills] Failed to list skills: ${error.message}`)
+    reply.code(500)
+    return { success: false, error: error.message }
+  }
+})
+
+// Deploy skill to local .claude/skills directory
+fastify.post('/api/deploy-skill', async (request, reply) => {
+  // Require authentication
+  if (!verifyToken(request)) {
+    reply.code(401)
+    return { success: false, error: 'Unauthorized' }
+  }
+
+  const { name, content, references = [] } = request.body || {}
+
+  if (!name || !content) {
+    reply.code(400)
+    return { success: false, error: 'name and content are required' }
+  }
+
+  // Validate skill name (URL-safe slug)
+  if (!/^[a-z0-9-]+$/.test(name)) {
+    reply.code(400)
+    return { success: false, error: 'Skill name must be URL-safe (lowercase letters, numbers, and hyphens only)' }
+  }
+
+  console.log(`[Deploy] Deploying skill: ${name}`)
+
+  try {
+    // Log deployment to HQ
+    await api.log(`Deploying skill: ${name}`, 'info', { skill: name })
+
+    // Create skill directory in ~/.claude/skills/
+    const homeDir = os.homedir()
+    const skillDir = path.join(homeDir, '.claude', 'skills', name)
+    const referencesDir = path.join(skillDir, 'references')
+
+    // Create directories
+    await fs.mkdir(skillDir, { recursive: true })
+    await fs.mkdir(referencesDir, { recursive: true })
+
+    // Write SKILL.md with frontmatter
+    const skillContent = `---
+name: ${name}
+description: Deployed from HQ
+---
+
+${content}`
+    await fs.writeFile(path.join(skillDir, 'SKILL.md'), skillContent, 'utf-8')
+
+    // Write reference files
+    for (const ref of references) {
+      if (ref.filename && ref.content) {
+        // Sanitize filename to prevent directory traversal
+        const safeFilename = path.basename(ref.filename)
+        await fs.writeFile(path.join(referencesDir, safeFilename), ref.content, 'utf-8')
+      }
+    }
+
+    console.log(`[Deploy] Skill deployed successfully: ${name}`)
+
+    return {
+      success: true,
+      message: `Skill "${name}" deployed successfully`,
+      path: skillDir,
+      references_count: references.length,
+    }
+  } catch (error) {
+    console.error(`[Deploy] Failed to deploy skill: ${error.message}`)
+
+    // Log error to HQ
+    await api.log(`Failed to deploy skill ${name}: ${error.message}`, 'error', { skill: name, error: error.message })
+
+    reply.code(500)
+    return {
+      success: false,
+      error: error.message,
+    }
+  }
+})
+
+// Graceful shutdown
+async function shutdown(signal) {
+  console.log(`[Server] Received ${signal}, shutting down...`)
+
+  // Send final offline heartbeat if HQ is configured
+  if (isHqConfigured()) {
+    heartbeat.setStatus('offline')
+    try {
+      await heartbeat.sendHeartbeat()
+      console.log('[Server] Status set to offline')
+    } catch (error) {
+      console.error(`[Server] Failed to update status: ${error.message}`)
+    }
+    heartbeat.stop()
+  }
+
+  // Close server
+  await fastify.close()
+  process.exit(0)
+}
+
+process.on('SIGTERM', () => shutdown('SIGTERM'))
+process.on('SIGINT', () => shutdown('SIGINT'))
+
+// Sync VNC password from HQ
+async function syncVncPassword() {
+  console.log('[VNC] Syncing VNC password from HQ...')
+
+  try {
+    const url = `${config.HQ_URL}/api/minion/vnc-password`
+    const response = await fetch(url, {
+      method: 'GET',
+      headers: {
+        'Authorization': `Bearer ${config.API_TOKEN}`,
+      },
+    })
+
+    if (!response.ok) {
+      const errorText = await response.text()
+      console.error(`[VNC] Failed to get VNC password from HQ: ${response.status} - ${errorText}`)
+      return false
+    }
+
+    const data = await response.json()
+    const vncPassword = data.vnc_password
+
+    if (!vncPassword) {
+      console.log('[VNC] No VNC password set in HQ, using default')
+      return true
+    }
+
+    console.log('[VNC] Got VNC password from HQ, applying...')
+
+    // Escape single quotes for shell safety
+    const escapedPassword = vncPassword.replace(/'/g, "'\\''")
+
+    // Ensure .vnc directory exists and set password
+    const homeDir = os.homedir()
+    const vncDir = path.join(homeDir, '.vnc')
+    const vncPasswdPath = path.join(vncDir, 'passwd')
+    await execAsync(`mkdir -p ${vncDir}`, { timeout: 5000 })
+    await execAsync(
+      `x11vnc -storepasswd '${escapedPassword}' ${vncPasswdPath}`,
+      { timeout: 10000 }
+    )
+    await execAsync(`chmod 600 ${vncPasswdPath}`, { timeout: 5000 })
+
+    // Restart x11vnc to apply the new password
+    if (PROC_MGR === 'systemd') {
+      await execAsync(`${SUDO}systemctl restart x11vnc`, { timeout: 10000 })
+    } else if (PROC_MGR === 'supervisord') {
+      await execAsync(`${SUDO}supervisorctl restart x11vnc`, { timeout: 10000 })
+    }
+
+    console.log('[VNC] VNC password synced successfully')
+    return true
+  } catch (error) {
+    console.error(`[VNC] Failed to sync VNC password: ${error.message}`)
+    return false
+  }
+}
+
+// Start server
+async function start() {
+  try {
+    // Listen on all interfaces
+    await fastify.listen({ port: config.AGENT_PORT, host: '0.0.0.0' })
+
+    console.log(`[Server] Minion agent listening on port ${config.AGENT_PORT}`)
+
+    if (isHqConfigured()) {
+      console.log(`[Server] HQ URL: ${config.HQ_URL}`)
+
+      // Start heartbeat
+      heartbeat.start()
+
+      // Sync VNC password from HQ (non-blocking, run in background)
+      syncVncPassword().catch(err => {
+        console.error('[VNC] Background sync failed:', err.message)
+      })
+    } else {
+      console.log('[Server] Running in standalone mode (no HQ connection)')
+    }
+  } catch (err) {
+    fastify.log.error(err)
+    process.exit(1)
+  }
+}
+
+start()