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

Quick Install

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

When to Use This Skill

Related Skills — Skill Routing

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

Dispatch Contract (Important)

Pilot is a Dispatcher, not an Executor. It generates plans, tracks state, gates on approvals — it does NOT call companion skills' MCP tools itself. The calling AI agent is responsible for invoking vmware-aiops::vm_clone etc. when pilot's run_workflow returns a step description.

This is intentional v2-style architecture: pilot's context stays small, state is always on disk, and there are no persistent agent threads. Full contract details: see references/integration-patterns.md.

MCP Tools (12 — 4 read, 8 write/control)

Built-in Templates (15)

The five most-used:

Full list: clone_and_test, incident_response, investigate_alert, plan_and_approve, compliance_scan, network_segment_setup, vks_cluster_deploy, rolling_restart, capacity_expansion, disaster_recovery, patch_deployment, storage_expansion, baseline_capture, baseline_audit, baseline_remediate. See references/templates.md for full details.

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

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