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/vmware-skills/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

uv tool install vmware-pilot==2.0.0
vmware-pilot mcp          # start the MCP server (stdio)

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: create_workflow_from_template("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: create_workflow_from_template("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
→ If the apply fails, nothing is undone automatically: ask the user, then call
  vmware-aiops rollback_vm_plan(plan_id) yourself

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::clone_vm 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.

get_skill_catalog is a curated design aid, not a whitelist. It surfaces 100 hand-picked building blocks across 13 skills — a deliberate subset of what those skills expose (aiops alone has 60 tools; the catalog lists 19). A step's skill field is a free-form string handed to the calling agent, so a workflow may name any companion skill, including ones the catalog does not list — pilot itself (pilot) is used that way by built-in templates for approval gates. Use the catalog for inspiration; consult the target skill's own SKILL.md for its full tool surface.

MCP Tools (13 — 4 read, 9 write/control)

rollback and cancel_workflow preview by default. Without confirm=True they return blast_radius (steps that would be undone, left applied, or skipped) and change nothing. Show it to the user; the user has not seen the preview yet, so do not set confirm=True on your own. They refuse when the state does not allow the transition, the record cannot be read, or a step was left running/interrupted (its effect is unknown: have the user check it in the target system, then pass acknowledge_unknown_effects=True).

Template steps pass confirm=True. Destructive companion tools preview unless called with confirm=True; in every built-in template such a step comes after an approve gate, so it carries confirm=True — dispatch it as listed. A step that only returned action: preview is recorded failed, not success. | | get_workflow_status | low | State + audit log |

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.

Approval gates are mandatory in custom workflows. Every destructive step (the skill catalog marks it high/critical risk, or its name says delete/remove/…) and every step pilot cannot classify must have a require_approval step somewhere before it. Otherwise create_workflow_from_template, create_workflow and confirm_draft refuse the workflow and name the offending steps, run_workflow refuses it even with force=True, and scripts/validate_workflow.py reports an error. Medium-risk writes (create_segment, power_on_vm, …) do not require a gate.

# ~/.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: require_approval        # required: the next step changes the estate
    skill: pilot
    tool: approve
    params:
      message: "Cluster healthy. Stop replica {{replica_vm}}?"
  - action: stop_replica
    skill: aiops
    tool: power_off_vm
    params:
      vm_name: "{{replica_vm}}"
    rollback_tool: power_on_vm
    rollback_params:
      vm_name: "{{replica_vm}}"
  - action: restart_primary
    skill: aiops
    tool: power_off_vm
    params:
      vm_name: "{{primary_vm}}"

Usage Mode

Note: every workflow operation — design, plan, run, approve, rollback — is MCP-only. The vmware-pilot CLI exists to launch the server and report its version, nothing more. Other skills in the family (aiops, monitor, avi, etc.) offer full CLI and MCP modes.

CLI Quick Reference

The CLI is a launcher, not a second interface to workflows:

vmware-pilot mcp        # start the MCP server (stdio)
vmware-pilot version    # print installed version
vmware-pilot --help

# Validate a custom workflow YAML before loading (runs pilot's own gate check,
# so it needs the Python vmware-pilot is installed in)
"$(uv tool dir)/vmware-pilot/bin/python" 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, approver=...) with the correct workflow ID to continue, or cancel_workflow(workflow_id) if the approval is rejected (it previews first; call again with confirm=True once the user has seen it). 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 create_workflow_from_template

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 scripts/validate_workflow.py <path> with pilot's Python (see CLI Quick Reference)
3. A YAML file you drop in whose name matches a built-in replaces it (a warning is logged) -- rename it if that is not what you want. create_workflow and confirm_draft refuse to save a template under a built-in name
4. A file that lists but will not plan is missing an approval gate -- the create_workflow_from_template error names the step and the file

Rollback did nothing, or fails on some steps

Rollback never happens on its own: a failed step leaves the workflow failed and stops. A bare rollback(workflow_id) only previews; confirm=True acts. It only reverses steps pilot recorded as success, and on the MCP server (no dispatcher) the steps you performed from pending_dispatch stay not_executed — so rollback there reverses nothing but approval gates. Undo them yourself: call each performed step's rollback_tool with its rollback_params, last step first, after confirming with the user. Steps without a rollback_tool cannot be undone. When pilot does dispatch (an embedder supplied a dispatcher), rollback is best-effort: a failed undo does not stop the rest, and the result reports each one.

"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": "vmware-pilot",
      "args": ["mcp"]
    }
  }
}

Fallback: {"command": "uvx", "args": ["--from", "vmware-pilot==2.0.0", "vmware-pilot-mcp"]} also works, but uvx re-resolves the package against PyPI on every start and fails behind a TLS-inspecting corporate proxy (invalid peer certificate: UnknownIssuer). The installed entry point above touches the network zero times; set UV_NATIVE_TLS=true if you must use uvx.

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
• Environment scoping: policy rules can scope by environment (an optional label an opt-in deny rule may match), and skills with a config may declare environment: per target. Pilot has no targets of its own and registers no environment resolver, so its own calls are unlabeled (they match no environment-scoped rule) — its writes go to the local workflow DB, never to a VMware estate. Pilot's approval gate is a step in its own workflow: it pauses before the agent dispatches a destructive step, and the target skill then applies its own policy rules when the step runs
• View recent operations: vmware-audit log --last 20
• View denied operations: vmware-audit log --status denied
• Credential steps: vks issue_tkc_kubeconfig and issue_supervisor_kubeconfig return a live Supervisor token. Treat them as credential access, not read-only queries — never run one on your own initiative, keep it behind an approval gate (pilot gates both like a delete), write the kubeconfig to an owner-only file, and never print the token into chat or logs
• Local data is sensitive: ~/.vmware/workflows.db (pilot keeps ~/.vmware 0700 and the DB 0600) holds step params and companion-skill results, with secret-named params masked. Pilot never writes ~/.vmware/baselines/; a baseline the agent saves there is an inventory of VMs, hosts, network segments, datastores and alarms — keep it owner-only and out of chat

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

License

MIT