Case 04400

VMware Pilot

Disclaimer: This is a community-maintained open-source project and is not affiliated with, endorsed by, or sponsored by VMware, Inc. or Broadcom Inc. "VMware" is a trademark of Broadcom. Source code is publicly auditable at github.com/zw008/VMware-Pilot under the MIT license.

Multi-step workflow orchestration for VMware MCP skills — design, approve, execute, rollback.

Companion Skills: vmware-aiops (VM operations) | vmware-monitor (monitoring) | vmware-nsx (networking) | vmware-aria (metrics/alerts) | vmware-avi (load balancing/AKO)

What This Skill Does

Capability	Description
Workflow Design	Natural language goal → AI designs steps from 8 skills' 185 tools
Approval Gates	Pause execution for human review before destructive operations
State Persistence	SQLite-backed, survives restarts, supports resume from checkpoint
Rollback	Reverse completed steps in order if workflow fails
Custom Templates	Save workflows as YAML for reuse, hot-reload without restart
Compliance Scans	Read-only health/capacity/anomaly checks across skills

Quick Install

pip install vmware-pilot
# or
uvx --from vmware-pilot vmware-pilot-mcp

When to Use This Skill

Scenario	Use Pilot?	Why
"Clone VM, test, then apply to prod"	Yes	Multi-step + approval
"Power on a VM"	No, use aiops	Single operation
"Set up app network + firewall + VMs"	Yes	Cross-skill orchestration
"Check cluster health"	No, use monitor/aria	Single read-only query
"Diagnose and fix an alert"	Yes	incident_response template
"Run compliance check"	Yes	compliance_scan template
"Drain server, patch, restore traffic"	Yes	Cross-skill: avi drain + aiops patch
"Deploy app with AKO ingress"	Yes	Cross-skill: aiops + vks + avi
"Check pool member health"	No, use avi	Single read-only query

Related Skills — Skill Routing

User Intent	Recommended Skill
VM lifecycle (power, clone, deploy)	vmware-aiops (uv tool install vmware-aiops)
Read-only monitoring	vmware-monitor (uv tool install vmware-monitor)
NSX networking (segments, gateways, NAT)	vmware-nsx (uv tool install vmware-nsx-mgmt)
NSX security (DFW, groups)	vmware-nsx-security (uv tool install vmware-nsx-security)
Aria metrics/alerts/capacity	vmware-aria (uv tool install vmware-aria)
Tanzu Kubernetes (Supervisor/TKC)	vmware-vks (uv tool install vmware-vks)
Storage (iSCSI, vSAN, datastores)	vmware-storage (uv tool install vmware-storage)
Load balancing, VS, pool, AKO	vmware-avi (uv tool install vmware-avi)
Audit log query	vmware-policy (vmware-audit CLI)
Multi-step orchestration	vmware-pilot (this skill)

Common Workflows

1. Design a Custom Workflow (Interactive)

User: "I need to set up a new app environment with networking and VMs"

AI calls: get_skill_catalog()          → see available tools
AI calls: design_workflow(goal="...")   → create draft
AI calls: update_draft(id, steps=[...]) → fill in steps
User reviews and confirms
AI calls: confirm_draft(id, save_as_template=True)
AI calls: run_workflow(id)             → execute with approval gates

2. Clone-and-Test (Built-in Template)

AI calls: plan_workflow("clone_and_test", {
    target_vm: "db01",
    change_spec: {memory_mb: 32768},
    target: "vcenter-prod"
})
AI calls: run_workflow(workflow_id)
→ Clone → Apply → Monitor → [Approval Gate] → Commit → Cleanup

3. Batch Operations with Approval

AI calls: plan_workflow("plan_and_approve", {
    operations: [
        {action: "power_off", vm_name: "db01"},
        {action: "revert_snapshot", vm_name: "db01", snapshot_name: "baseline"},
        {action: "power_on", vm_name: "db01"}
    ]
})
→ Create Plan → [Approval Gate] → Execute Plan (with auto-rollback on failure)

4. Rolling Maintenance with AVI Drain

Drain traffic from a pool member via AVI, patch the server, then restore traffic:

1. vmware-avi pool disable <pool> <server>     # drain traffic from pool member
2. vmware-avi analytics <vs>                    # verify drain complete (0 active connections)
3. vmware-aiops vm guest-exec <vm> --cmd "apt-get upgrade -y"   # patch the server
4. vmware-avi pool enable <pool> <server>       # restore traffic to pool member
5. vmware-avi pool members <pool>               # verify health status is green

5. AKO-Aware Application Deployment

Deploy a backend VM, create a K8s namespace, and wire up AKO Ingress to the AVI Controller:

1. vmware-aiops deploy ova <image> --name <vm>  # deploy backend VM
2. vmware-vks namespace create <ns>             # create K8s namespace
3. kubectl apply -f ingress.yaml                # create Ingress with AKO annotations
4. vmware-avi ako ingress check <ns>            # validate AKO annotations are correct
5. vmware-avi ako sync status                   # verify VS created on AVI Controller

MCP Tools (11 — 3 read, 8 write/control)

Category	Tool	Risk	Description
Discovery	get_skill_catalog	low	Available skills and tools for design
	list_workflows	low	Built-in + custom templates
Design	design_workflow	low	Natural language → draft
	update_draft	medium	Edit draft steps
	confirm_draft	medium	Finalize draft → ready to execute
Execute	plan_workflow	medium	Create from template
	create_workflow	medium	One-step custom creation
	run_workflow	medium	Execute (pauses at approval)
Control	approve	high	Human approval to continue
	rollback	high	Reverse completed steps
	get_workflow_status	low	State + audit log

Built-in Templates (4)

Template	Steps	Approval	Skills Used
clone_and_test	6	Yes	aiops + monitor
incident_response	4	Yes	monitor + aiops
plan_and_approve	3	Yes	aiops
compliance_scan	3	No	monitor + aria

Custom Templates

Drop YAML files in ~/.vmware/workflows/ — pilot auto-loads them.

# ~/.vmware/workflows/restart_cluster.yaml
name: restart_cluster
description: Rolling restart of database cluster
steps:
  - action: check_health
    skill: monitor
    tool: get_alarms
    params:
      target: "{{target}}"
  - action: stop_replica
    skill: aiops
    tool: vm_power_off
    params:
      vm_name: "{{replica_vm}}"
    rollback_tool: vm_power_on
    rollback_params:
      vm_name: "{{replica_vm}}"
  - action: require_approval
    skill: pilot
    tool: approve
    params:
      message: "Replica stopped. Proceed?"
  - action: restart_primary
    skill: aiops
    tool: vm_power_off
    params:
      vm_name: "{{primary_vm}}"

Usage Mode

Scenario	Recommended	Why
Local/small models (Ollama, Qwen)	MCP	Structured JSON I/O for multi-step state
Cloud models (Claude, GPT-4o)	MCP	Design mode needs structured tool calls
CI/CD pipeline orchestration	MCP	Programmatic plan/approve/run cycle
Quick template listing	CLI	vmware-pilot-mcp is MCP-only; use MCP client

Note: vmware-pilot is MCP-only (no standalone CLI). All interactions go through MCP tool calls. Other skills in the family (aiops, monitor, avi, etc.) offer both CLI and MCP modes.

CLI Quick Reference

vmware-pilot is an MCP-only server (no standalone CLI binary). Interact via MCP tool calls:

# Start the MCP server
uvx --from vmware-pilot vmware-pilot-mcp

# Validate a custom workflow YAML before loading
python3 scripts/validate_workflow.py ~/.vmware/workflows/my_workflow.yaml

# List available tools across all skills (design helper)
python3 scripts/list_available_tools.py          # all skills
python3 scripts/list_available_tools.py aiops    # specific skill
python3 scripts/list_available_tools.py --json   # JSON output

# View audit logs (via vmware-policy)
vmware-audit log --last 20
vmware-audit log --status denied

Full CLI reference for companion skills: see references/cli-reference.md

Troubleshooting

Workflow stuck in "awaiting_approval"

Call approve(workflow_id) with the correct workflow ID to continue, or rollback(workflow_id) to abort. If the MCP session was lost, reconnect and call get_workflow_status(workflow_id) to see the current state -- workflows persist in SQLite and survive restarts.

"Unknown workflow type" error from plan_workflow

The template name is case-sensitive. Use list_workflows() to see all available built-in and custom template names. Custom templates must be valid YAML in ~/.vmware/workflows/.

Custom YAML template not appearing

1. Verify the file is in ~/.vmware/workflows/ with a .yaml extension
2. Check YAML syntax -- run python3 scripts/validate_workflow.py <path> to validate
3. Template names must be unique -- a custom template cannot shadow a built-in name

Rollback fails on some steps

Not all steps are reversible. Steps without rollback_tool defined are skipped during rollback. Pilot uses best-effort rollback: if one rollback step fails, it continues with remaining steps and reports which succeeded and which failed.

"Workflow cannot be run" state error

A workflow can only be run from pending or running states. If it is in draft, call confirm_draft() first. If it is in completed or failed, create a new workflow -- completed workflows cannot be re-run.

vmware-policy dependency missing

Pilot requires vmware-policy for the @vmware_tool decorator and audit logging. It is declared as a dependency in pyproject.toml and should install automatically. If missing, run pip install vmware-policy or reinstall pilot.

Setup

No vCenter credentials needed — pilot orchestrates other skills that handle connections.

{
  "mcpServers": {
    "vmware-pilot": {
      "command": "uvx",
      "args": ["--from", "vmware-pilot", "vmware-pilot-mcp"]
    }
  }
}

Audit & Safety

All operations are automatically audited via vmware-policy (@vmware_tool decorator):

• Every tool call logged to ~/.vmware/audit.db (SQLite, framework-agnostic)
• Policy rules enforced via ~/.vmware/rules.yaml (deny rules, maintenance windows, risk levels)
• Risk classification: each tool tagged as low/medium/high/critical
• View recent operations: vmware-audit log --last 20
• View denied operations: vmware-audit log --status denied

vmware-policy is automatically installed as a dependency — no manual setup needed.

License

MIT