VMware Monitor

VMware Monitor

> Author: Wei Zhou, VMware by Broadcom — wei-wz.zhou@broadcom.com > This is a community-driven project by a VMware engineer, not an official VMware product. > For official VMware developer tools see developer.broadcom.com.

English | [中文](README-CN.md)

Read-only VMware vCenter/ESXi monitoring — 27 tools, code-level safety. No destructive operations exist in this codebase.

> Why a separate repository? VMware Monitor is fully independent from VMware-AIops. Safety is enforced at the code level: no power off, delete, create, reconfigure, snapshot-create/revert/delete, clone, or migrate functions exist in this codebase. Not just prompt constraints — zero destructive code paths.

[](https://clawhub.ai/skills/vmware-monitor) [](https://skills.sh/vmware-skills/VMware-Monitor) [](https://github.com/vmware-skills/VMware-Monitor) [](LICENSE)

Companion Skills

| Skill | Scope | Tools | Install | |-------|-------|:-----:|---------| | vmware-aiops ⭐ entry point | VM lifecycle, deployment, guest ops, clusters | 49 | uv tool install vmware-aiops | | vmware-storage | Datastores, iSCSI, vSAN | 11 | uv tool install vmware-storage | | vmware-vks | Tanzu Namespaces, TKC cluster lifecycle | 20 | uv tool install vmware-vks | | vmware-nsx | NSX networking: segments, gateways, NAT, IPAM | 33 | uv tool install vmware-nsx-mgmt | | vmware-nsx-security | DFW microsegmentation, security groups, Traceflow | 21 | uv tool install vmware-nsx-security | | vmware-aria | Aria Ops metrics, alerts, capacity planning | 28 | uv tool install vmware-aria | | vmware-avi | AVI (NSX ALB) load balancing, AKO on Kubernetes | 28 | uv tool install vmware-avi | | vmware-harden | Compliance baselines, drift detection (read-only) | 6 | uv tool install vmware-harden | | vmware-log-insight | Centralized syslog search, aggregation, alerts | 7 | uv tool install vmware-log-insight | | vmware-debug | Incident timeline correlation, root cause | 2 | uv tool install vmware-debug | | vmware-pilot | Multi-step workflow orchestration, approval gates | 13 | uv tool install vmware-pilot |

⚡ Quick Investigation Reports

Five opinionated, read-only reports that answer an operator's real questions — each aggregates and correlates server-side and hands back a high-signal result (never raw inventory). Every report also renders a self-contained offline HTML snapshot with --html (no external assets, nothing leaves the machine; drill-down detail collapses in native `` sections, zero JavaScript).

| Question | Command | What it correlates | |----------|---------|--------------------| | "Is anything on fire?" across all clusters | vmware-monitor summary | Every cluster's hosts + VM power + live CPU/mem + alarms → ranked top-N issues + per-cluster status | | "What needs attention now?" across all vCenters | vmware-monitor attention | Every configured vCenter merged into one globally-ranked issue list; unreachable targets degrade gracefully | | "What's happening around this VM?" | vmware-monitor investigate vm | VM state + host it runs on + cluster + backing datastores + snapshots + alarms + performance + a merged event timeline | | "What's happening around this host?" | vmware-monitor investigate host | Host state + cluster + the VMs it runs + mounted datastores + alarms + performance + correlated timeline | | "What's happening around this datastore?" | vmware-monitor investigate datastore | Capacity/free + mounting hosts + VMs it backs + alarms + correlated timeline |

# Triage the estate, then drill into whatever it flags:
vmware-monitor attention                         # what needs attention now, all vCenters
vmware-monitor summary --top 5                   # is anything on fire, one vCenter
vmware-monitor investigate vm web-01 --hours 72  # everything around a VM, 72h event window
vmware-monitor investigate vm web-01 --html      # → offline snapshot in ~/vmware-health/

Unknown object names return a teaching error naming exactly how to list objects. Via MCP these are the tools cluster_health_summary, cross_vcenter_attention, vm_investigation_bundle, host_investigation_bundle, datastore_investigation_bundle — the model calls them and explains the aggregated result in operational language. Full flags: [references/cli-reference.md](skills/vmware-monitor/references/cli-reference.md).

Quick Install (Recommended)

Works with Claude Code, Cursor, Codex, Gemini CLI, Trae, and 30+ AI agents:

# Via Skills.sh
npx skills add vmware-skills/VMware-Monitor

# Via ClawHub
clawhub install vmware-monitor

PyPI Install (No GitHub Access Required)

# Install via uv (recommended)
uv tool install vmware-monitor

# Or via pip
pip install vmware-monitor

# China mainland mirror (faster)
pip install vmware-monitor -i https://pypi.tuna.tsinghua.edu.cn/simple

Offline / Air-Gapped Install (from source)

This project uses the modern PEP 517 build system (hatchling), so there is no setup.py by design — that is expected, not a missing file. If you cloned the source and hit ERROR: File "setup.py" or "setup.cfg" not found ... editable mode currently requires a setuptools-based build, your pip is older than 21.3 and cannot do an editable (-e) install with a non-setuptools backend. Editable mode is a developer convenience, not needed to run the tool — do one of:

# From the source tree — a normal (non-editable) install builds a wheel:
pip install .              # NOT  pip install -e .

# ...or upgrade pip first, and editable works too:
pip install --upgrade pip && pip install -e .

For a truly air-gapped host, build the wheels on a connected machine and copy them over — the target then needs no network:

# On a connected machine, collect this package + its dependencies as wheels:
pip wheel . -w dist        # → dist/*.whl   (or: uv build, for just this package)

# Copy dist/ to the air-gapped host, then install offline:
pip install --no-index --find-links dist vmware-monitor

---

Capabilities (Read-Only)

Architecture

User (Natural Language)
  ↓
AI CLI Tool (Claude Code / Gemini / Codex / Aider / Continue / Trae / Kimi)
  ↓ Reads SKILL.md / AGENTS.md / rules
  ↓
vmware-monitor CLI (read-only)
  ↓ pyVmomi (vSphere SOAP API)
  ↓
vCenter Server ──→ ESXi Clusters ──→ VMs
    or
ESXi Standalone ──→ VMs

Version Compatibility

| vSphere / VCF Version | Support | Notes | |----------------|---------|-------| | VCF 9.1 / vSphere 9.1 | ✅ Full | Released 2026-05-12. pyVmomi ` — VCF Python SDK (recommended for VCF 9+, bundles pyVmomi + vSAN SDK), vSphere Automation SDK for Python

• REST APIs: — vSphere Automation API, VCF API
• CLI Tools: — PowerCLI 9.1, ESXCLI, OVF Tool

1. Inventory

| Feature | vCenter | ESXi | Details | |---------|:-------:|:----:|---------| | List VMs | ✅ | ✅ | Name, power state, CPU, memory, guest OS, IP, folder_path (vCenter inventory folder, e.g. /Datacenters/Production/Web Tier); MCP list_virtual_machines supports folder_filter for case-insensitive folder-tree search | | List Hosts | ✅ | ⚠️ Self only | CPU cores, memory, ESXi version, VM count, uptime | | List Datastores | ✅ | ✅ | Capacity, free/used, type (VMFS/NFS), usage % | | List Clusters | ✅ | ❌ | Host count, DRS/HA status | | List Networks | ✅ | ✅ | Network name, associated VM count, accessibility — CLI inventory networks, MCP list_all_networks |

2. Health & Monitoring

| Feature | vCenter | ESXi | Details | |---------|:-------:|:----:|---------| | Active Alarms | ✅ | ✅ | Severity, alarm name, entity, timestamp | | Event/Log Query | ✅ | ✅ | Filter by time range, severity; 50+ event types | | Hardware Sensors | ✅ | ✅ | Per-sensor type (temperature/voltage/fan...), reading, unit, and health status (green/yellow/red) — CLI health sensors, MCP get_host_sensors | | Host Services | ✅ | ✅ | hostd, vpxa running/stopped status — CLI health services, MCP get_host_services |

Monitored Event Types:

| Category | Events | |----------|--------| | VM Failures | VmFailedToPowerOnEvent, VmDiskFailedEvent, VmFailoverFailed | | Host Issues | HostConnectionLostEvent, HostShutdownEvent, HostIpChangedEvent | | Storage | DatastoreCapacityIncreasedEvent, SCSI high latency | | HA/DRS | DasHostFailedEvent, DrsVmMigratedEvent, DrsSoftRuleViolationEvent | | Auth | UserLoginSessionEvent, BadUsernameSessionEvent |

3. VM Info & Snapshot List (Read-Only)

| Feature | Details | |---------|---------| | VM Info | Name, power state, guest OS, CPU, memory, IP, VMware Tools, disks, NICs, folder_path | | Snapshot List | List existing snapshots with name and creation time (no create/revert/delete) — CLI vm snapshot-list, MCP tool vm_list_snapshots |

4. Scheduled Scanning & Notifications

| Feature | Details | |---------|---------| | Daemon | APScheduler-based, configurable interval (default 15 min) | | Multi-target Scan | Sequentially scan all configured vCenter/ESXi targets | | Scan Content | Alarms + Events + Host logs (hostd, vmkernel, vpxd) | | Log Analysis | Regex pattern matching: error, fail, critical, panic, timeout | | Structured Log | JSONL output to ~/.vmware-monitor/scan.log | | Webhook | Slack, Discord, or any HTTP endpoint | | Daemon Management | daemon start/stop/status, PID file, graceful shutdown |

5. Safety Features

| Feature | Details | |---------|---------| | Code-Level Isolation | Independent repository — zero destructive functions in codebase | | Audit Trail | All queries logged to ~/.vmware-monitor/audit.log (JSONL) | | Password Protection | .env file loading with permission check (warn if not 600) | | SSL Self-signed Support | disableSslCertValidation — only for ESXi with self-signed certs in isolated labs; production should use CA-signed certificates | | Prompt Injection Protection | vSphere event messages and host logs are truncated, sanitized, and wrapped in boundary markers | | Webhook Data Scope | Sends monitoring summaries to user-configured URLs only — no third-party services by default | | Production Recommended | AI agents can misinterpret context and execute unintended destructive operations — real-world incidents have shown AI-driven tools deleting production databases and entire environments. VMware-Monitor eliminates this risk: no destructive code paths exist. Use VMware-AIops only in dev/lab environments |

What's NOT Included (By Design)

These operations do not exist in this repository:

• ❌ Power on/off, reset, suspend VMs
• ❌ Create, delete, reconfigure VMs
• ❌ Create, revert, delete snapshots
• ❌ Clone or migrate VMs
• ❌ _double_confirm, _show_state_preview, _validate_vm_params

For these operations, use the full VMware-AIops repository.

---

Running with local or small models? See [skills/vmware-monitor/references/agent-guardrails.md](skills/vmware-monitor/references/agent-guardrails.md).

---

Common Workflows

Daily Health Check

1. Check alarms: vmware-monitor health alarms --target prod-vcenter
2. Review recent events: vmware-monitor health events --hours 24 --severity warning
3. List hosts: vmware-monitor inventory hosts — check connection state and memory usage

Investigate a Specific Object (drill-down)

One call correlates the object with its surrounding infrastructure and recent history — see [⚡ Quick Investigation Reports](#-quick-investigation-reports) above.

1. Start from triage: vmware-monitor attention (all vCenters) or vmware-monitor summary (one)
2. Drill into what it flags: vmware-monitor investigate vm (or host / datastore)
3. Widen the event window with --hours 72; share it with --html (offline snapshot)
4. If the name is unknown → the teaching error names how to list objects (inventory vms/hosts, list_all_datastores)

Set Up Continuous Monitoring

1. Configure webhook in ~/.vmware-monitor/config.yaml
2. Start daemon: vmware-monitor daemon start
3. Daemon scans every 15 min, sends alerts to Slack/Discord

---

Troubleshooting

Alarms returns empty but vCenter shows alarms

The get_alarms tool queries triggered alarms at the root folder level. Some alarms are entity-specific — try checking events instead: vmware-monitor health events --hours 1 --severity info.

"Connection refused" error

1. Run vmware-monitor doctor to diagnose
2. Verify target hostname/IP and port (443) in config.yaml
3. For self-signed certs: set disableSslCertValidation: true

Events returns too many results

Use severity filter: --severity warning (default) filters out info-level events. Use --hours 4 to narrow the time range.

VM info shows "guest_os: unknown"

VMware Tools not installed or not running in the guest. Install/start VMware Tools for guest OS detection, IP address, and guest family info.

Doctor passes but commands fail with timeout

vCenter may be under heavy load. Try targeting a specific ESXi host directly instead of vCenter, or increase connection timeout in config.yaml.

---

Supported AI Platforms

| Platform | Status | Config File | AI Model | |----------|--------|-------------|----------| | Claude Code | ✅ Native Skill | skills/vmware-monitor/SKILL.md | Anthropic Claude | | Gemini CLI | ✅ Context file + MCP | skills/vmware-monitor/SKILL.md | Google Gemini | | OpenAI Codex CLI | ✅ Skill + AGENTS.md | skills/vmware-monitor/SKILL.md | OpenAI GPT | | Aider | ✅ Conventions | skills/vmware-monitor/SKILL.md | Any (cloud + local) | | Continue CLI | ✅ Rules | skills/vmware-monitor/SKILL.md | Any (cloud + local) | | Trae IDE | ✅ Rules | skills/vmware-monitor/SKILL.md | Claude/DeepSeek/GPT-4o | | Kimi Code CLI | ✅ Skill | skills/vmware-monitor/SKILL.md | Moonshot Kimi | | MCP Server | ✅ MCP Protocol | vmware_monitor/mcp_server/ | Any MCP client | | Python CLI | ✅ Standalone | N/A | N/A |

Platform Comparison

| Feature | Claude Code | Gemini CLI | Codex CLI | Aider | Continue | Trae IDE | Kimi CLI | |---------|-------------|------------|-----------|-------|----------|----------|----------| | Cloud AI | Anthropic | Google | OpenAI | Any | Any | Multi | Moonshot | | Local models | — | — | — | Ollama | Ollama | — | — | | Skill system | SKILL.md | Context file | SKILL.md | — | Rules | Rules | SKILL.md | | MCP support | Native | Native | Via Skills | Third-party | Native | — | — | | Free tier | — | 60 req/min | — | Self-hosted | Self-hosted | — | — |

MCP Server Integrations

The vmware-monitor MCP server works with any MCP-compatible agent or tool. Ready-to-use configuration templates are in [examples/mcp-configs/](examples/mcp-configs/). All 27 tools are read-only — code-level enforced safety.

| Agent / Tool | Local Model Support | Config Template | Integration Guide | |-------------|:-------------------:|-----------------|-------------------| | Xiaoguai (小怪) | ✅ Self-hosted, any LLM | MCP setup | [G

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: vmware-skills
• Source: vmware-skills/VMware-Monitor
• License: MIT

Install and usage instructions live in the source repository linked above.