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 | 中文

Read-only VMware vCenter/ESXi monitoring — 32 tools. No destructive operations exist in this codebase, and a test enforces that.

Why a separate repository? VMware Monitor is fully independent from VMware-AIops. No power off, delete, create, reconfigure, snapshot-create/revert/delete, clone, or migrate functions exist in this codebase — not a prompt constraint, an absence.

How that is enforced, precisely. tests/eval/regression/test_read_only_enforcement.py parses every source file with ast and requires each vSphere method the package calls to appear on a reviewed allowlist, cross-checked against pyVmomi's own type metadata: anything returning a vim.Task, or gated by vCenter on a non-read privilege, fails unless a human wrote down why. Today that allowlist is fourteen methods. The check is a gate on the code as written — it cannot see a method name assembled at runtime, and nothing runs it automatically, so it holds only as far as someone runs the test suite. For a guarantee that does not depend on this repository at all, point the skill at a dedicated account holding vCenter's built-in Read-Only role (which reads need more than that role).

What "read-only" does not cover. It is a claim about vCenter/ESXi: no code path changes their state. On vCenter the skill opens only its own login session and short-lived query handles it releases. It does write locally: ~/.vmware-monitor/config.yaml and .env (via init; plaintext passwords in .env are rewritten as b64: on load), audit logs (~/.vmware/audit.db for MCP calls, ~/.vmware-monitor/audit.log for CLI commands), --html snapshots in ~/vmware-health/, and — only after daemon start — daemon.pid, scan.log, and posts to a webhook you configured. Full table: setup guide.

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 <details> 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 <name>	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 <name>	Host state + cluster + the VMs it runs + mounted datastores + alarms + performance + correlated timeline
"What's happening around this datastore?"	vmware-monitor investigate datastore <name>	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.

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 @zw008/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 <10.0 resolves and connects via SOAP.
VCF 9.0 / vSphere 9.0	✅ Full	pyVmomi 8.0.3+ connects against vSphere 9 SOAP API.
8.0 / 8.0U1-U3	✅ Full	pyVmomi 8.0.3+
7.0 / 7.0U1-U3	✅ Full	All read-only APIs supported
6.7	✅ Compatible	Backward-compatible, tested
6.5	✅ Compatible	Backward-compatible, tested

Official Broadcom References

• SDKs: https://developer.broadcom.com/sdks — VCF Python SDK (recommended for VCF 9+, bundles pyVmomi + vSAN SDK), vSphere Automation SDK for Python
• REST APIs: https://developer.broadcom.com/xapis — vSphere Automation API, VCF API
• CLI Tools: https://developer.broadcom.com/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
Backup Window	How long backups held a snapshot open on a VM, from vCenter task history — CLI snapshots backup-window, MCP tool vm_backup_snapshot_history. A lower bound on the backup job, never its official duration

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	Each cycle: triggered alarms, vCenter events from the last lookback_hours, and new lines in the ESXi host logs hostd, vmkernel, vpxa
Host Logs	Read incrementally: each line is reported once per daemon run (a restarted daemon re-reads each log's last 500 lines once). A rotated log, or more than 500 new lines between cycles, adds an info row saying which lines were not scanned. Reading host logs needs the Global.Diagnostics privilege, which vCenter's Read-Only role does not include; a log that cannot be read becomes an info row with the reason, never a silent "all clear"
Log Analysis	Host-log lines matching error, fail, critical, panic, lost access, cannot, timeout, refused, corrupt — lines with critical/panic/corrupt are critical, the rest warning
Structured Log	JSONL output to ~/.vmware-monitor/scan.log — every issue, info rows included
Webhook	Slack, Discord, or any HTTP endpoint. Receives every critical issue and every alarm/event warning; host-log warnings go to the scan log only, and info rows are never sent
Cycle Summary	One line per cycle in the daemon's log output: findings (and how many went to the webhook), unreadable host logs, logs with unscanned lines, failed passes. If any pass failed or a target could not be reached it reads Scan INCOMPLETE, never "all clear"
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, checked by an AST allowlist gate over every vSphere call (tests/eval/regression/test_read_only_enforcement.py)
Audit Trail	MCP tool calls logged to ~/.vmware/audit.db (SQLite, via vmware-policy); CLI commands to ~/.vmware-monitor/audit.log (JSONL)
Password Protection	.env file loading with permission check (warn if not 600)
SSL Self-signed Support	verify_ssl: false — 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	Disabled by default. When configured, the daemon posts to your URL only: every critical issue (alarms, events, ESXi log lines matching critical/panic/corrupt, targets it could not connect to) and every alarm/event warning — host-log warnings stay in the scan log, and info rows are never sent. Each issue carries its entity name and message: sanitized alarm, event, or ESXi log text, or the connection error, which can include host names, IPs, and user names. No credentials from the skill's config or .env are sent
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 removes that class of risk from its own code: no destructive code paths exist, and the allowlist gate fails the build if one is added. Pair it with a read-only vCenter account for defence that does not rely on this codebase. 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.

---

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 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 <name> (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 verify_ssl: false

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/. All 32 tools are read-only, enforced by the allowlist gate described above.

Agent / Tool	Local Model Support	Config Template	Integration Guide
Xiaoguai (小怪)	✅ Self-hosted, any LLM	MCP setup	Guide
Goose	✅ Ollama, LM Studio	goose.json	Guide
LocalCowork	✅ Fully offline	localcowork.json	Guide
mcp-agent	✅ Ollama, vLLM	mcp-agent.yaml	Guide
VS Code Copilot	—	vscode-copilot.json	Guide
Cursor	—	cursor.json	—
Continue	✅ Ollama	continue.yaml	Guide
Claude Code	—	claude-code.json	—

Xiaoguai (小怪) — a self-hostable, audit-first agent platform (Rust, single binary + embedded SQLite) from the same maintainer. It runs the read-only vmware-monitor MCP server as one of its toolboxes; being both an MCP consumer and an MCP server, its HMAC-chained audit log pairs naturally with this skill's read-only design — every query is logged, and no code path here mutates. See its MCP integration guide.

Fully local operation (no cloud API required):

# Aider + Ollama + vmware-monitor (via SKILL.md)
aider --conventions skills/vmware-monitor/SKILL.md --model ollama/qwen2.5-coder:32b

# Any MCP agent + local model + vmware-monitor MCP server
# See examples/mcp-configs/ for your agent's config format

---

Installation

Step 0: Prerequisites

# Python 3.10+ required
python3 --version

# Node.js 18+ required for Gemini CLI and Codex CLI
node --version

Step 1: Clone & Install Python Backend

git clone https://github.com/vmware-skills/VMware-Monitor.git
cd VMware-Monitor
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Step 2: Configure

mkdir -p ~/.vmware-monitor
cp config.example.yaml ~/.vmware-monitor/config.yaml
# Edit config.yaml with your vCenter/ESXi targets

Set passwords via .env file (recommended):

cp .env.example ~/.vmware-monitor/.env
chmod 600 ~/.vmware-monitor/.env
# Edit and fill in your passwords

Security note: Prefer .env file over command-line export to avoid passwords appearing in shell history. config.yaml stores only hostnames, ports, and a reference to the .env file — it does not contain passwords or tokens. All secrets are stored exclusively in .env (chmod 600). Webhook notifications are disabled by default; when enabled, payloads go to user-configured URLs only and carry no credentials from your config — but they do carry vSphere's own alarm, event, and log text, which can include host names, IPs, and user names. We recommend a dedicated service account with vCenter's built-in Read-Only role.