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

⚡ 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).

# 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

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

2. Health & Monitoring

Monitored Event Types:

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

4. Scheduled Scanning & Notifications

5. Safety Features

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 Comparison

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.

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.

Password environment variable naming convention:

VMWARE_{TARGET_NAME_UPPER}_PASSWORD
# Replace hyphens with underscores, UPPERCASE
# Example: target "home-esxi" → VMWARE_HOME_ESXI_PASSWORD
# Example: target "prod-vcenter" → VMWARE_PROD_VCENTER_PASSWORD

Step 3: Connect Your AI Tool

Choose one (or more) of the following:

Option A: Claude Code

Method 1: Skills.sh or ClawHub (recommended)

Either installer places the skill in Claude Code's skills directory for you:

npx skills add vmware-skills/VMware-Monitor
# or
clawhub install @zw008/vmware-monitor

Method 2: Manual skill install

git clone https://github.com/vmware-skills/VMware-Monitor.git
cd VMware-Monitor

# Copy the skill into Claude Code's personal skills directory
mkdir -p ~/.claude/skills/vmware-monitor
cp -r skills/vmware-monitor/. ~/.claude/skills/vmware-monitor/

For tool access (not just skill context), also register the MCP server:

claude mcp add vmware-monitor -- vmware-monitor mcp

Restart Claude Code, then:

> Show me all VMs on esxi-lab.example.com

Option B: Gemini CLI

# Install Gemini CLI
npm install -g @google/gemini-cli

# Load the skill as project context (Gemini CLI reads GEMINI.md on startup)
cp skills/vmware-monitor/SKILL.md ./GEMINI.md

For tool access (not just context), register the MCP server in ~/.gemini/settings.json:

{
  "mcpServers": {
    "vmware-monitor": {
      "command": "vmware-monitor",
      "args": ["mcp"],
      "env": { "VMWARE_MONITOR_CONFIG": "~/.vmware-monitor/config.yaml" }
    }
  }
}

Then start Gemini CLI:

gemini
> Show me all VMs on my ESXi host

Option C: OpenAI Codex CLI

# Install Codex CLI
npm i -g @openai/codex
# Or on macOS:
# brew install --cask codex

# Copy skill to Codex skills directory
mkdir -p ~/.codex/skills/vmware-monitor
cp skills/vmware-monitor/SKILL.md ~/.codex/skills/vmware-monitor/SKILL.md

# Copy AGENTS.md to project root
cp skills/vmware-monitor/SKILL.md ./AGENTS.md

Then start Codex CLI:

codex --enable skills
> List all VMs on my ESXi

Option D: Aider (supports local models)

# Install Aider
pip install aider-chat

# Install Ollama for local models (optional)
# macOS:
brew install ollama
ollama pull qwen2.5-coder:32b

# Run with cloud API
aider --conventions skills/vmware-monitor/SKILL.md

# Or with local model via Ollama
aider --conventions skills/vmware-monitor/SKILL.md \
  --model ollama/qwen2.5-coder:32b

Option E: Continue CLI (supports local models)

# Install Continue CLI
npm i -g @continuedev/cli

# Copy rules file
mkdir -p .continue/rules
cp skills/vmware-monitor/SKILL.md .continue/rules/vmware-monitor.md

Configure ~/.continue/config.yaml for local model:

models:
  - name: local-coder
    provider: ollama
    model: qwen2.5-coder:32b

Then:

cn
> Check ESXi health and alarms

Option F: Trae IDE

Copy the rules file to your project's .trae/rules/ directory:

mkdir -p .trae/rules
cp skills/vmware-monitor/SKILL.md .trae/rules/project_rules.md

Trae IDE's Builder Mode reads .trae/rules/ Markdown files at startup.

Note: You can also install Claude Code extension in Trae IDE and use .claude/skills/ format directly.

Option G: Kimi Code CLI

# Copy skill file to Kimi skills directory
mkdir -p ~/.kimi/skills/vmware-monitor
cp skills/vmware-monitor/SKILL.md ~/.kimi/skills/vmware-monitor/SKILL.md

Option H: MCP Server (Glama / Claude Desktop)

The MCP server exposes VMware read-only monitoring as tools via the Model Context Protocol. Works with any MCP-compatible client (Claude Desktop, Cursor, etc.).

After uv tool install vmware-monitor, start the MCP server with one command (v1.5.15+):

# Recommended — single command, no network re-resolve
vmware-monitor mcp

# With a custom config path
VMWARE_MONITOR_CONFIG=/path/to/config.yaml vmware-monitor mcp

Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "vmware-monitor": {
      "command": "vmware-monitor",
      "args": ["mcp"],
      "env": {
        "VMWARE_MONITOR_CONFIG": "/path/to/config.yaml"
      }
    }
  }
}

# Run without installing (requires PyPI access each launch)
uvx --from vmware-monitor vmware-monitor mcp

# Legacy entry point (still works, kept for backward compatibility)
vmware-monitor-mcp

Option I: Standalone CLI (no AI)

# Already installed in Step 1
source .venv/bin/activate

vmware-monitor inventory vms --target home-esxi
vmware-monitor health alarms --target home-esxi
vmware-monitor vm info my-vm --target home-esxi

Update / Upgrade

Already installed? Re-run the install command for your channel to get the latest version:

Check your current version: vmware-monitor --version

Chinese Cloud Models

For users in China who prefer domestic cloud APIs or have limited access to overseas services.

DeepSeek

export DEEPSEEK_API_KEY="your-key"
aider --conventions skills/vmware-monitor/SKILL.md \
  --model deepseek/deepseek-coder

Qwen (Alibaba Cloud)

export DASHSCOPE_API_KEY="your-key"
aider --conventions skills/vmware-monitor/SKILL.md \
  --model qwen/qwen-coder-plus

Local Models (Aider + Ollama)

For fully offline operation — no cloud API, no internet, full privacy.

brew install ollama
ollama pull qwen2.5-coder:32b
ollama serve

aider --conventions skills/vmware-monitor/SKILL.md \
  --model ollama/qwen2.5-coder:32b

CLI Reference

# Diagnostics
vmware-monitor doctor                   # Check environment, config, connectivity
vmware-monitor doctor --skip-auth       # Skip vSphere auth check (faster)

# MCP Config Generator
vmware-monitor mcp-config generate --agent goose        # Generate config for Goose
vmware-monitor mcp-config generate --agent claude-code  # Generate config for Claude Code
vmware-monitor mcp-config list                          # List all supported agents

# Inventory
vmware-monitor inventory vms [--target <name>]
vmware-monitor inventory vms --limit 10 --sort-by memory_mb   # Top 10 VMs by memory
vmware-monitor inventory vms --power-state poweredOn           # Only powered-on VMs
vmware-monitor inventory vms --sort-by folder_path             # Group VMs by inventory folder
# All `inventory vms` results include a `folder_path` field (e.g. `/Datacenters/Production/Web Tier`).
# MCP tool `list_virtual_machines` additionally supports `folder_filter="Production"` for case-insensitive folder-tree search.
vmware-monitor inventory hosts [--target <name>]
vmware-monitor inventory datastores [--target <name>]
vmware-monitor inventory clusters [--target <name>]

# Health
vmware-monitor health alarms [--target <name>]
vmware-monitor health events [--hours 24] [--severity warning]

# VM Info (read-only)
vmware-monitor vm info <vm-name>
vmware-monitor vm snapshot-list <vm-name>

# Scanning & Daemon
vmware-monitor scan now [--target <name>]
vmware-monitor daemon start
vmware-monitor daemon stop
vmware-monitor daemon status

Configuration

See config.example.yaml for all options.

Project Structure

VMware-Monitor/
├── skills/                        # Skills index (npx skills add)
│   └── vmware-monitor/
│       ├── SKILL.md
│       └── references/            # Detailed docs loaded on-demand
├── vmware_monitor/                # Python backend (read-only only)
│   ├── config.py                  # YAML + .env config
│   ├── connection.py              # Multi-target pyVmomi
│   ├── cli.py                     # Typer CLI (read-only commands only)
│   ├── ops/
│   │   ├── inventory.py           # VMs, hosts, datastores, clusters
│   │   ├── health.py              # Alarms, events, sensors
│   │   └── vm_info.py             # VM info, snapshot list (read-only)
│   ├── scanner/                   # Log scanning daemon
│   ├── notify/                    # Notifications (JSONL + webhook)
│   └── mcp_server/                # MCP server (read-only tools only)
├── examples/mcp-configs/          # MCP client config templates
├── tests/                         # Test suite
├── smithery.yaml                  # Smithery marketplace config
├── RELEASE_NOTES.md
├── config.example.yaml
└── pyproject.toml

Related Projects

Troubleshooting & Contributing

If you encounter any errors or issues, please send the error message, logs, or screenshots to zhouwei008@gmail.com. Contributions are welcome!

License

MIT