Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
import type { ConnectionType } from '@/api/connections';
import {
SOURCE_AGENT_HOST_PROFILE_MANIFEST_ENTRIES,
getSourcePlatformManifestEntry,
type PlatformGovernanceState,
type PlatformPrimaryMode,
type PlatformReadinessStage,
type PlatformSupportFloor,
} from '@/utils/platformSupportManifest';
export type InfrastructureOnboardingConnectionType = Extract<
ConnectionType,
'agent' | 'availability' | 'pve' | 'pbs' | 'pmg' | 'truenas' | 'vmware'
>;
export interface InfrastructureOnboardingProductPresentation {
type: InfrastructureOnboardingConnectionType;
label: string;
bestFor: string;
coverage: string;
catalogDescription: string;
searchAliases: readonly string[];
sourceStrategy: InfrastructureSourceStrategy;
autoDetect: boolean;
governanceState: PlatformGovernanceState;
readinessStage: PlatformReadinessStage;
primaryMode: PlatformPrimaryMode;
canonicalProjections: readonly string[];
supportFloor: PlatformSupportFloor;
defaultSurfaceKeys: readonly string[];
}
export interface InfrastructureSourceManagerProductPresentation extends InfrastructureOnboardingProductPresentation {
actionLabel: string;
}
export type InfrastructureSourcePickerItemId =
'vmware' | 'pve' | 'truenas' | 'unraid' | 'pbs' | 'pmg' | 'linux-host' | 'docker' | 'kubernetes';
export type InfrastructureSourcePickerRouteStep = InfrastructureSourcePickerItemId;
export interface InfrastructureSourcePickerItemPresentation {
id: InfrastructureSourcePickerItemId;
routeStep: InfrastructureSourcePickerRouteStep;
connectionType: InfrastructureOnboardingConnectionType;
label: string;
bestFor: string;
coverage: string;
catalogDescription: string;
searchAliases: readonly string[];
sourceStrategy: InfrastructureSourceStrategy;
autoDetect: boolean;
governanceState: PlatformGovernanceState;
readinessStage: PlatformReadinessStage;
primaryMode: PlatformPrimaryMode;
canonicalProjections: readonly string[];
supportFloor: PlatformSupportFloor;
}
interface BaseProductPresentation {
label: string;
bestFor: string;
coverage: string;
catalogDescription: string;
searchAliases?: readonly string[];
sourceStrategy: InfrastructureSourceStrategy;
autoDetect: boolean;
sourcePlatformId?: string;
primaryMode?: PlatformPrimaryMode;
canonicalProjections?: readonly string[];
defaultSurfaceKeys: readonly string[];
}
export type InfrastructureSourceStrategy = 'api' | 'agent' | 'api-agent' | 'probe';
export interface InfrastructureSourceStrategyPresentation {
label: string;
summary: string;
detail: string;
}
export interface InfrastructureOnboardingPathPresentation {
title: string;
description: string;
bestFor: string;
coverage: string;
}
const INFRASTRUCTURE_AGENT_RUNTIME_PLATFORM_LABELS = [
'Linux',
'macOS',
'Windows',
'FreeBSD',
] as const;
const formatJoinedLabelList = (labels: readonly string[]): string => {
if (labels.length === 0) return '';
if (labels.length === 1) return labels[0];
if (labels.length === 2) return `${labels[0]} and ${labels[1]}`;
return `${labels.slice(0, -1).join(', ')}, and ${labels[labels.length - 1]}`;
};
const getInfrastructureAgentHostProfileLabels = (): readonly string[] => {
const labels = [
...INFRASTRUCTURE_AGENT_RUNTIME_PLATFORM_LABELS,
...SOURCE_AGENT_HOST_PROFILE_MANIFEST_ENTRIES.filter(
(profile) => profile.governanceState === 'supported',
).map((profile) => profile.family),
];
return Array.from(new Set(labels));
};
export const getInfrastructureAgentHostProfileSupportText = (): string =>
`${formatJoinedLabelList(getInfrastructureAgentHostProfileLabels())} host/appliance profiles`;
export const getInfrastructureGovernanceBadgeLabel = (
governanceState: PlatformGovernanceState,
readinessStage: PlatformReadinessStage,
): string | null => {
if (governanceState === 'supported') return null;
if (governanceState === 'presentation-only') return 'Presentation only';
if (readinessStage === 'first-lab-ready') return 'Preview';
return 'Preview';
};
const SOURCE_STRATEGY_PRESENTATION: Record<
InfrastructureSourceStrategy,
InfrastructureSourceStrategyPresentation
> = {
api: {
label: 'API inventory',
summary: 'Platform API',
detail: 'Uses the platform API for inventory, health, and managed resources.',
},
agent: {
label: 'Agent telemetry',
summary: 'Pulse Agent',
detail: `Installs Pulse Agent for ${getInfrastructureAgentHostProfileSupportText()}, local services, Docker, and Kubernetes.`,
},
'api-agent': {
label: 'API first',
summary: 'Platform API, agent optional',
detail:
'Starts with platform API inventory and adds Pulse Agent only where node-local telemetry is needed.',
},
probe: {
label: 'Availability probe',
summary: 'Agentless probe',
detail: 'Uses ICMP, TCP, or HTTP checks for devices that cannot run Pulse Agent.',
},
};
const PRODUCT_PRESENTATION: Record<
InfrastructureOnboardingConnectionType,
BaseProductPresentation
> = {
agent: {
label: 'Pulse Agent',
bestFor: `${getInfrastructureAgentHostProfileSupportText()} where you want low-overhead node-local telemetry.`,
coverage: 'Low-overhead host telemetry, SMART, services, Docker, and Kubernetes',
catalogDescription: 'Low-overhead host telemetry, services, Docker, Kubernetes',
searchAliases: ['host', 'server', 'machine', 'node', 'ubuntu', 'debian', 'windows', 'mac'],
sourceStrategy: 'agent',
autoDetect: false,
defaultSurfaceKeys: ['host'],
},
vmware: {
label: 'VMware vCenter',
bestFor: 'vCenter-managed VMware environments',
coverage: 'VM inventory, ESXi host health, datastore status',
catalogDescription: 'VM inventory, ESXi hosts, datastores',
searchAliases: ['vsphere', 'esxi', 'vcenter', 'vmware cluster'],
sourceStrategy: 'api',
autoDetect: true,
sourcePlatformId: 'vmware-vsphere',
defaultSurfaceKeys: ['vms', 'hosts', 'datastores'],
},
truenas: {
label: 'TrueNAS SCALE',
bestFor: 'TrueNAS appliances with API-backed management',
coverage: 'Pools, datasets, apps, replications',
catalogDescription: 'Pools, datasets, apps, replications',
searchAliases: ['nas', 'storage', 'zfs', 'truenas scale'],
sourceStrategy: 'api',
autoDetect: true,
sourcePlatformId: 'truenas',
defaultSurfaceKeys: ['datasets', 'pools', 'replication'],
},
pve: {
label: 'Proxmox VE',
bestFor: 'Virtualization clusters and standalone hypervisors',
coverage:
'VMs, containers, storage, and cluster health through the Proxmox API. Install Pulse Agent only on nodes where you want full node-local telemetry such as temperatures and SMART data',
catalogDescription: 'VMs, containers, storage, cluster health',
searchAliases: ['proxmox', 'pve', 'hypervisor', 'vm host', 'cluster'],
sourceStrategy: 'api-agent',
autoDetect: true,
sourcePlatformId: 'proxmox-pve',
defaultSurfaceKeys: ['vms', 'containers', 'storage', 'backups'],
},
pbs: {
label: 'Proxmox Backup Server',
bestFor: 'Backup infrastructure and protected storage',
coverage:
'Backup jobs, sync, verify, prune, and GC through the Proxmox API. Install Pulse Agent only where host-local telemetry is needed',
catalogDescription: 'Backup jobs, sync, verify, prune, GC',
searchAliases: ['backup', 'proxmox backup', 'pbs'],
sourceStrategy: 'api-agent',
autoDetect: true,
sourcePlatformId: 'proxmox-pbs',
defaultSurfaceKeys: [
'backups',
'datastores',
'syncJobs',
'verifyJobs',
'pruneJobs',
'garbageJobs',
],
},
pmg: {
label: 'Proxmox Mail Gateway',
bestFor: 'Mail filtering and delivery operations',
coverage: 'Mail stats, queues, quarantine, relay health',
catalogDescription: 'Mail stats, queues, quarantine, relay health',
searchAliases: ['mail', 'email', 'gateway', 'proxmox mail', 'pmg'],
sourceStrategy: 'api',
autoDetect: true,
sourcePlatformId: 'proxmox-pmg',
defaultSurfaceKeys: ['mailStats', 'queues', 'quarantine', 'domainStats'],
},
availability: {
label: 'Network endpoint',
bestFor: 'Devices that expose ICMP, TCP, or HTTP but cannot run Pulse Agent',
coverage: 'Agentless availability checks and downtime alerts',
catalogDescription: 'Ping, TCP port, and HTTP availability checks',
searchAliases: [
'ping',
'icmp',
'tcp',
'http',
'endpoint',
'probe',
'port',
'website',
'ip address',
'mqtt',
'esphome',
],
sourceStrategy: 'probe',
autoDetect: false,
primaryMode: 'api-backed',
canonicalProjections: ['network-endpoint'],
defaultSurfaceKeys: ['availability'],
},
};
const DEFAULT_AGENT_SUPPORT_FLOOR = {
setup: 'supported',
visibility: 'supported',
workloads: 'n/a',
storage: 'supported',
recovery: 'n/a',
alerts: 'supported',
assistantRead: 'supported',
assistantControl: 'supported',
} satisfies PlatformSupportFloor;
const AGENT_CATALOG_ITEMS: Record<
'linux-host' | 'unraid' | 'docker' | 'kubernetes',
Omit<
InfrastructureSourcePickerItemPresentation,
| 'id'
| 'connectionType'
| 'governanceState'
| 'readinessStage'
| 'primaryMode'
| 'canonicalProjections'
| 'supportFloor'
>
> = {
'linux-host': {
routeStep: 'linux-host',
label: 'Linux, macOS, Windows host',
bestFor: 'Machines where you want low-overhead node-local telemetry from Pulse Agent.',
coverage: 'Host telemetry, services, SMART, sensors, network metrics, and remote update state',
catalogDescription: 'Machine telemetry, services, SMART, sensors',
searchAliases: ['host', 'server', 'machine', 'node', 'ubuntu', 'debian', 'freebsd', 'windows'],
sourceStrategy: 'agent',
autoDetect: false,
},
unraid: {
routeStep: 'unraid',
label: 'Unraid',
bestFor: 'Unraid servers where array health and host-local telemetry both matter.',
coverage: 'Array health, disk posture, SMART, services, Docker containers, and host telemetry',
catalogDescription: 'Array health, disks, Docker, host telemetry',
searchAliases: ['nas', 'array', 'storage', 'home server', 'docker host'],
sourceStrategy: 'agent',
autoDetect: false,
},
docker: {
routeStep: 'docker',
label: 'Docker',
bestFor: 'Docker hosts where containers should be discovered from the machine running them.',
coverage:
'Docker inventory plus host CPU, memory, disk, network, services, and SMART telemetry',
catalogDescription: 'Containers plus host telemetry',
searchAliases: ['containers', 'container host', 'compose'],
sourceStrategy: 'agent',
autoDetect: false,
},
kubernetes: {
routeStep: 'kubernetes',
label: 'Kubernetes',
bestFor: 'Small clusters and lab nodes where Pulse Agent can collect cluster and node context.',
coverage: 'Kubernetes workload context plus node-local host telemetry from the agent',
catalogDescription: 'Workload context plus node telemetry',
searchAliases: ['k8s', 'pods', 'cluster', 'workloads'],
sourceStrategy: 'agent',
autoDetect: false,
},
};
const SOURCE_PICKER_PRODUCT_ITEMS: Partial<
Record<InfrastructureSourcePickerItemId, InfrastructureOnboardingConnectionType>
> = {
vmware: 'vmware',
pve: 'pve',
truenas: 'truenas',
pbs: 'pbs',
pmg: 'pmg',
};
const governanceStateForType = (
type: InfrastructureOnboardingConnectionType,
): PlatformGovernanceState => {
const sourcePlatformId = PRODUCT_PRESENTATION[type].sourcePlatformId;
if (!sourcePlatformId) return 'supported';
return getSourcePlatformManifestEntry(sourcePlatformId)?.governanceState ?? 'supported';
};
const manifestEntryForType = (type: InfrastructureOnboardingConnectionType) => {
const sourcePlatformId = PRODUCT_PRESENTATION[type].sourcePlatformId;
return sourcePlatformId ? getSourcePlatformManifestEntry(sourcePlatformId) : null;
};
const API_PRODUCT_ORDER: InfrastructureOnboardingConnectionType[] = [
'vmware',
'truenas',
'pve',
'pbs',
'pmg',
];
const SOURCE_MANAGER_PRODUCT_ORDER: InfrastructureOnboardingConnectionType[] = [
...API_PRODUCT_ORDER,
'agent',
];
const SOURCE_MANAGER_LABEL_OVERRIDES: Partial<
Record<
InfrastructureOnboardingConnectionType,
{
label: string;
actionLabel: string;
}
>
> = {
agent: {
label: 'Pulse Agent hosts',
actionLabel: 'Install Pulse Agent',
},
};
export const INFRASTRUCTURE_ONBOARDING_PATHS: Record<
'api' | 'agent',
InfrastructureOnboardingPathPresentation
> = {
api: {
title: 'Connect platform API',
description:
'Use a management API when the platform exposes one. Pulse validates the endpoint, requests credentials, and then starts collecting platform inventory and health.',
bestFor: 'TrueNAS, Proxmox, and the current VMware vCenter integration path',
coverage: 'Platform inventory, workloads, storage, backups, and health',
},
agent: {
title: 'Install Pulse Agent',
description: `Use the agent when you want low-overhead machine telemetry for ${getInfrastructureAgentHostProfileSupportText()}, or when the system does not expose a management API Pulse can connect to directly.`,
bestFor: `${getInfrastructureAgentHostProfileSupportText()} where you want full node-local telemetry.`,
coverage:
'Low-overhead CPU temperature, disk SMART, services, network metrics, Docker, and Kubernetes telemetry',
},
};
export const INFRASTRUCTURE_AGENT_DISCOVERY_LABELS = [
'Pulse Agent hosts',
'Docker',
'Kubernetes',
] as const;
export const INFRASTRUCTURE_AGENT_HOST_LABELS = getInfrastructureAgentHostProfileLabels();
const SOURCE_PICKER_ITEM_ORDER: InfrastructureSourcePickerItemId[] = [
// Proxmox suite kept adjacent so a Proxmox-heavy lab finds PVE, PBS, and
// PMG without scanning past unrelated cards.
'pve',
'pbs',
'pmg',
// Other platform-API integrations.
'truenas',
'vmware',
// Agent-install paths, named platforms first then the generic host card.
'unraid',
'docker',
'kubernetes',
'linux-host',
];
export const getInfrastructureOnboardingProductPresentation = (
type: InfrastructureOnboardingConnectionType,
): InfrastructureOnboardingProductPresentation => {
const manifestEntry = manifestEntryForType(type);
const presentation = PRODUCT_PRESENTATION[type];
return {
type,
...presentation,
searchAliases: presentation.searchAliases ?? [],
governanceState: manifestEntry?.governanceState ?? governanceStateForType(type),
readinessStage: manifestEntry?.readinessStage ?? 'supported',
primaryMode: manifestEntry?.primaryMode ?? presentation.primaryMode ?? 'agent-backed',
canonicalProjections: manifestEntry?.canonicalProjections ??
presentation.canonicalProjections ?? ['agent'],
supportFloor: manifestEntry?.supportFloor ?? DEFAULT_AGENT_SUPPORT_FLOOR,
};
};
export const getInfrastructureSourcePickerItemPresentation = (
id: InfrastructureSourcePickerItemId,
): InfrastructureSourcePickerItemPresentation => {
const productType = SOURCE_PICKER_PRODUCT_ITEMS[id];
if (productType) {
const product = getInfrastructureOnboardingProductPresentation(productType);
return {
id,
routeStep: id,
connectionType: product.type,
label: product.label,
bestFor: product.bestFor,
coverage: product.coverage,
catalogDescription: product.catalogDescription,
sourceStrategy: product.sourceStrategy,
autoDetect: product.autoDetect,
searchAliases: product.searchAliases,
governanceState: product.governanceState,
readinessStage: product.readinessStage,
primaryMode: product.primaryMode,
canonicalProjections: product.canonicalProjections,
supportFloor: product.supportFloor,
};
}
const agentItem = AGENT_CATALOG_ITEMS[id as keyof typeof AGENT_CATALOG_ITEMS];
return {
id,
...agentItem,
connectionType: 'agent',
governanceState: 'supported',
readinessStage: 'supported',
primaryMode: 'agent-backed',
canonicalProjections: ['agent'],
supportFloor: DEFAULT_AGENT_SUPPORT_FLOOR,
};
};
export const getInfrastructureSourcePickerItemForRouteStep = (
step: string | null | undefined,
): InfrastructureSourcePickerItemPresentation | null => {
const normalized = (step || '').trim();
if (!normalized) return null;
for (const id of SOURCE_PICKER_ITEM_ORDER) {
const item = getInfrastructureSourcePickerItemPresentation(id);
if (item.routeStep === normalized) return item;
}
return null;
};
export const getInfrastructureSourceStrategyPresentation = (
strategy: InfrastructureSourceStrategy,
): InfrastructureSourceStrategyPresentation => SOURCE_STRATEGY_PRESENTATION[strategy];
export const getInfrastructureApiProductPresentations =
(): InfrastructureOnboardingProductPresentation[] =>
API_PRODUCT_ORDER.map((type) => getInfrastructureOnboardingProductPresentation(type));
export const getInfrastructureSourceManagerProducts =
(): InfrastructureSourceManagerProductPresentation[] =>
SOURCE_MANAGER_PRODUCT_ORDER.map((type) => {
const product = getInfrastructureOnboardingProductPresentation(type);
const override = SOURCE_MANAGER_LABEL_OVERRIDES[type];
return {
...product,
label: override?.label ?? product.label,
actionLabel: override?.actionLabel ?? `Add ${product.label}`,
};
});
export const getInfrastructureApiProductsByGovernanceState = (
governanceState: PlatformGovernanceState,
): InfrastructureOnboardingProductPresentation[] =>
getInfrastructureApiProductPresentations().filter(
(product) => product.governanceState === governanceState,
);
export const getInfrastructureSourcePickerItems =
(): InfrastructureSourcePickerItemPresentation[] =>
SOURCE_PICKER_ITEM_ORDER.map((id) => getInfrastructureSourcePickerItemPresentation(id));
export const getInfrastructureAutoDetectLabels = (): string[] =>
getInfrastructureApiProductPresentations()
.filter((product) => product.autoDetect)
.map((product) => product.label);
export const getInfrastructureSupportSummaryBadges = (): {
supportedToday: string[];
currentAdmissionPath: string[];
installPath: string[];
} => ({
supportedToday: [
...getInfrastructureApiProductsByGovernanceState('supported').map((product) => product.label),
...INFRASTRUCTURE_AGENT_DISCOVERY_LABELS,
],
currentAdmissionPath: getInfrastructureApiProductsByGovernanceState('admitted').map(
(product) => product.label,
),
installPath: [...INFRASTRUCTURE_AGENT_HOST_LABELS, ...INFRASTRUCTURE_AGENT_DISCOVERY_LABELS],
});
export const getInfrastructureEmptyStateSummary = (): string =>
'Choose an infrastructure source to start monitoring your environment.';
export const getInfrastructureEmptyStateDetail = (): string =>
'Supported source types include TrueNAS SCALE, Proxmox VE, Proxmox Backup Server, Proxmox Mail Gateway, and Pulse Agent hosts. VMware vCenter is available as a preview platform while live support is validated. Docker and Kubernetes are discovered from supported agent hosts.';