VMware Debug

VMware Debug

For a read-only check of this skill with your model and agent host, use the shared model-fit self-test in the marketplace root.

Disclaimer: Community-maintained open-source project, **not affiliated with,

endorsed by, or sponsored by VMware, Inc. or Broadcom Inc.** "VMware" and

"vSphere" are trademarks of Broadcom. Source is publicly auditable under the MIT

license.

The diagnostic brain of the VMware skill family. You bring the symptom (an error, a log dump, a slow VM); this skill runs a systematic investigation, correlates events from the other skills into one timeline, ranks root-cause hypotheses, and tells you what to check next. It never touches vSphere — it connects to nothing and never executes fixes; its only writes are to a local case ledger under $OPS_HOME. Remediation is routed to vmware-aiops (single op) or vmware-pilot (multi-step, gated), mirroring the vmware-harden → vmware-pilot advisor/executor split.

See skills/vmware-debug/SKILL.md for the full methodology, the event-envelope contract, and symptom routing.

Upgrading to 2.0

2.0 renames 13 of its 14 MCP tools so every name starts with a verb (e.g. case_close → close_case, case_get → get_case, case_grade → grade_case). The full old → new table is in RELEASE_NOTES.md. Nothing else changes: same tools, parameters, safety gates and CLI commands. If an agent prompt, script or ~/.vmware/rules.yaml names a tool, update it — though deny rules written with the old names keep working with vmware-policy ≥ 1.18.1 (vmware-audit policy lists any rule the renames widened), and vmware-pilot ≥ 1.13 translates old names in saved workflows. If an install older than 2.0 shares that rules.yaml, give it vmware-policy ≥ 1.18.2 too: it matches each rule against both the old and the new name, so one file serves both.

Companion Skills

Install

uv tool install vmware-debug

vmware-debug categories # see which symptom categories it can diagnose

MCP tools (14 — 7 read, 7 write)

The seven writes go to the local case ledger only; none reaches a VMware system.

Correlation — stateless, for a single look:

Investigation ledger — for an incident you will reason about over time:

Event envelope: {ts, source, severity, entity, text, fields}. The agent normalizes events from each source into this shape before handing them to debug, so debug has zero runtime dependency on the other packages. Keep each event's `event_type` in `fields` — the classifier matches it as well as the text, and most modern vSphere events are EventEx: the text is a generic boilerplate sentence, and only eventTypeId says what the event actually is.

Security

Offline and credential-free by construction: it connects to no vCenter/NSX/Aria, has no destructive surface on VMware, and holds no secret to leak. The only writes are the local case ledger: evidence, gaps, hypotheses and grade history are append-only; timeline.md is regenerated from the evidence, and case.json holds the current grade and status. The same holds with several writers: every write to a case first takes that case's lock file (.ledger.lock, exclusive create), so two processes writing the same case in a shared $OPS_HOME are serialized instead of dropping each other's entries; every file is written under a temporary name and then moved into place, so a reader never sees a half-written file (on a file system without hard links, a new evidence file is instead created in place: still never overwritten, but it can be read half-written). A lock left behind by a crashed process is reported together with its holder and never deleted automatically; delete it by hand once you have confirmed no process is writing that case. Released versions 1.11.3 and earlier do not take this lock, so every machine sharing a case directory must upgrade. See SECURITY.md.

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-debug

Remote access (HTTPS) and limiting tools

By default vmware-debug mcp speaks stdio to one local client and offers every tool. Two options change that (vmware-policy ≥ 1.21.0).

Serve over HTTPS so clients on other machines can connect. Every caller needs a bearer token:

vmware-audit token create alice          # prints the token once; give it to alice

vmware-audit token list # names only vmware-audit token revoke alice # refused from its next request, no restart vmware-debug mcp --transport https --host 0.0.0.0 --port 8443 \ --cert /etc/vmware-mcp/server.pem --key /etc/vmware-mcp/server-key.pem \ --public-name mcp.example.com

Connect a client (Claude Code shown; any MCP client that supports streamable HTTP and custom headers works):

claude mcp add --transport http vmware-debug https://mcp.example.com:8443/mcp \

--header "Authorization: Bearer $VMWARE_MCP_TOKEN"

{

"mcpServers": { "vmware-debug": { "type": "http", "url": "https://mcp.example.com:8443/mcp", "headers": { "Authorization": "Bearer ${VMWARE_MCP_TOKEN}" } } } }

• The server will not start without a token, refuses Host/Origin values outside --public-name, and checks before it binds that unauthenticated requests get 401. Use a certificate your clients trust for those names.
• Behind a TLS-terminating reverse proxy on the same machine use --transport http --host 127.0.0.1 --public-name mcp.example.com and pass the Authorization header through.
• Behind a load balancer or gateway on another machine, keep --transport https (a self-signed certificate is fine), list in --public-name the host name the balancer sends as Host, and have it forward Authorization. Its health probe can use GET /healthz, which needs no token and returns only {"status": "ok"} (vmware-policy ≥ 1.23.0).
• Send traceparent or X-Request-ID with each request to have it stored on the audit row; vmware-audit log --correlation-id ID then finds the calls behind one platform request.
• The audit log records each caller as token: . Calls naming different targets run in parallel; calls that name no target run one at a time, so name the target when several people share a server.
• Everyone who can reach the endpoint acts with this server's account. Tokens identify callers; they grant nothing on the platform. Run one endpoint per privilege level.
• Several people or roles on one endpoint: run vmware-audit roles enable once, then give each token a role (vmware-audit token create NAME --role reader, or a role in roles.yaml naming tools and targets; vmware-policy ≥ 1.24.0). A role limits what the token may call on this endpoint; it cannot grant more than the account has. See vmware-policy's README, "Roles for network callers".

Offer only read tools, plus the writes you choose:

vmware-debug mcp --expose read --allow-write close_case

or: VMWARE_DEBUG_MCP_EXPOSE=read VMWARE_DEBUG_MCP_ALLOW_WRITE=close_case vmware-debug mcp

Tools not offered do not appear in the client's tool list. A bad value or an unknown write tool stops the server (exit 2). This limits what clients are offered; it is not authorization, so the account itself should be least-privilege.

Details: skills/vmware-debug/references/setup-guide.md ("Serving MCP over HTTPS", "Limiting which tools are offered").

License

MIT.