Automation Workflows

The true value of Pharos is realized when it becomes the automated backbone of your infrastructure. This guide provides production-ready workflows for Home Lab and Enterprise environments.

🛠️ Proxmox Automation

Achieve zero-touch inventory by registering your LXC containers and VMs automatically during the provisioning process.

The Hook Script

Create a shell script on your Proxmox host (/usr/local/bin/pharos-hook.sh). This script uses the mdb client to notify the Pharos server whenever a container starts or stops.

#!/bin/bash
# Usage: ./pharos-hook.sh <vmid> <phase>
VMID=$1
PHASE=$2

if [ "$PHASE" == "post-start" ]; then
    HOSTNAME=$(pct exec $VMID -- hostname)
    IP=$(pct exec $VMID -- hostname -I | awk '{print $1}')
    # Register with Pharos mdb
    mdb add hostname="$HOSTNAME" ip="$IP" type="machine" vmid="$VMID" status="up"
fi

if [ "$PHASE" == "pre-stop" ]; then
    HOSTNAME=$(pct exec $VMID -- hostname)
    # "change" requires the "make" clause per RFC 2378 §3.10 - the selection clause (before
    # "make") and the modification clause (after it) are otherwise indistinguishable, and this
    # would silently match zero records instead of updating status.
    mdb change hostname="$HOSTNAME" make status="down"
fi

Enable the Hook

Apply the script to your container or VM configuration:

pct set 100 --hookscript local:snippets/pharos-hook.sh

🚀 CI/CD Integration

Pharos is designed for high-velocity DevSecOps teams. You can automate your infrastructure records by integrating Pharos into your CI/CD pipelines.

# Example snippet for a local CI runner
mdb add hostname="web-app-v2" ip="$RUNNER_IP" type="machine"

jobs:
  update-inventory:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy Pharos CLI
        run: |
          curl -sSL -O https://github.com/iamrichardd/pharos/releases/latest/download/mdb-linux-x86_64
          chmod +x mdb-linux-x86_64
          mv mdb-linux-x86_64 /usr/local/bin/mdb
      - name: Update Machine Record
        env:
          SSH_KEY: ${{ secrets.PHAROS_SSH_KEY }}
          PHAROS_SERVER: pharos.example.com
        run: |
          mkdir -p ~/.ssh
          echo "$SSH_KEY" > ~/.ssh/id_ed25519
          chmod 600 ~/.ssh/id_ed25519
          mdb add hostname="web-app-v2" ip="${{ steps.deploy.outputs.ip }}" type="machine"

🩺 Automated Inventory with Pulse

Pharos doesn’t just store static data; it automatically discovers and maintains your fleet’s inventory using pharos-pulse with an Inventory-First approach.

Baseline vs. Delta Strategy

To minimize network overhead and CPU impact, the Pulse agent employs a two-tier reporting strategy:

1. Baseline (ONLINE): On startup, pharos-pulse collects a full hardware and OS metadata package — CPU brand and core count, total RAM (mem_total_kb), OS name/version and kernel version, hardware serial number and UUID, manufacturer and product name, and real network interface addresses via multi-valued ip_addr and mac_addr fields — and registers it with the server. (Serial number and UUID require a one-time permission grant on Linux hosts, applied automatically by the Automated Installation Guide; fields the host can’t provide are simply omitted rather than sent as unknown.)
2. Delta (HEARTBEAT): Every 60 minutes, the agent sends a minimal presence signal to maintain the record’s freshness and verify identity.

Presence Lifecycle

Pharos automatically tracks the lifecycle of your nodes based on agent signals:

• ONLINE: Node has recently sent a baseline or heartbeat signal.
• OFFLINE: Node has gracefully shut down and sent a final SIGTERM signal.

Dead Man’s Switch Alerting

Not every failure is graceful — a crash, kill -9, or network partition never sends an OFFLINE signal, so a node can go silent with no explicit signal at all. pharos-server watches every machine’s heartbeat freshness continuously: if a node hasn’t reported in for longer than PHAROS_PRESENCE_ALERT_THRESHOLD_SECONDS (default 2 hours) without ever sending OFFLINE, it fires a configured webhook POST and/or a local recovery script — see the Configuration Reference for PHAROS_ALERT_WEBHOOK_URL and PHAROS_ALERT_SCRIPT. This is an external alert your automation can act on, not a status field written back onto the record itself.

Webhook Notifications for Record Changes

Separately from Dead Man’s Switch alerting above (which only fires when a node goes silent), pharos-server can also push a real-time notification on every successful add, change, or delete — useful for a live audit feed of inventory changes, not just failure alerts. Set PHAROS_WEBHOOK_URL to activate it, and PHAROS_WEBHOOK_FORMAT to pick a payload shape: generic (structured JSON for a custom endpoint, the default), slack, or discord. See the Configuration Reference for both variables. Because pharos-pulse’s 60-minute heartbeat is itself an add, expect a notification on every heartbeat too if you enable this on a heartbeat-heavy fleet — there’s no built-in filtering to distinguish a meaningful inventory change from routine heartbeat noise yet.

Agent-Native Inventory Dashboard

Use the Pharos Console — your lab’s Agent-Native Control Plane — to visualize your entire hardware and software fleet. Click any node to see its deep-linkable Resource-First Identity Card, featuring manufacturer serial numbers and specific kernel versions—essential for security audits and hardware lifecycle management.