Skill: zw008/vmware-pilot (version 1.5.17)

--- name: vmware-pilot description: > Use this skill whenever the user wants to design, execute, or manage complex multi-step VMware workflows with human approval and automatic rollback. Pilot is the orchestration brain — it breaks down a user's goal into steps across multiple VMware skills (aiops, monitor, nsx, aria, vks, storage, avi), adds approval gates before destructive operations, and rolls back automatically if anything fails. Always use vmware-pilot for: "clone and test before applying to production", "VMware incident response with checkpoints", "investigate alert root cause", "set up VMware infrastructure using multiple skills", "VMware rolling restart with health checks", "baseline capture and drift detection", "rolling maintenance with AVI drain", "AKO-aware app deployment", or any VMware workflow needing approval gates or rollback. 15 built-in templates + custom YAML + AI-designed workflows from 185 available tools across 8 skills. For single VM operations use vmware-aiops, for read-only queries use vmware-monitor, for load balancer operations use vmware-avi. installer: kind: uv package: vmware-pilot allowed-tools: [Bash] metadata: {"openclaw":{"requires":{"env":["VMWARE_PILOT_CONFIG"],"bins":["vmware-pilot-mcp"]},"primaryEnv":"VMWARE_PILOT_CONFIG","homepage":"https://github.com/zw008/VMware-Pilot","emoji":"🧭","os":["macos","linux"]}} compatibility: > vmware-policy auto-installed as Python dependency (provides @vmware_tool decorator and audit logging). All workflow operations audited to ~/.vmware/audit.db. No direct vCenter/NSX credentials: Pilot is an orchestration layer that delegates to companion skills (aiops, monitor, nsx, etc.) which handle their own auth. Approval gates: Workflows pause for human review before destructive steps. Rollback automatically reverses completed steps on failure. State persistence: SQLite-backed workflow state survives restarts. No webhooks, no outbound network calls. Transitive dependencies: Only vmware-policy (audit/policy). No post-install scripts or background services. --- # 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](https://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](../vmware-aiops/SKILL.md) (VM operations) | [vmware-monitor](../vmware-monitor/SKILL.md) (monitoring) | [vmware-nsx](../vmware-nsx/SKILL.md) (networking) | [vmware-aria](../vmware-aria/SKILL.md) (metrics/alerts) | [vmware-avi](../vmware-avi/SKILL.md) (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 ```bash 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 ``` ## 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`](references/integration-patterns.md#the-dispatch-contract). ## MCP Tools (12 — 4 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 | | | `review_workflow` | low | Structural sanity check before execution (approved \| needs_revision) | | | `run_workflow` | medium | Execute next checkpoint (agent dispatches each step) | | **Control** | `approve` | high | Human approval to continue | | | `rollback` | high | Reverse completed steps | | | `get_workflow_status` | low | State + audit log | ## Built-in Templates (15) The five most-used: | Template | Steps | Approval | Skills Used | |---|---|---|---| | `clone_and_test` | 6 | Yes | aiops + monitor | | `incident_response` | 4 | Yes | monitor + aiops | | `investigate_alert` | 4 / 8 | Yes | monitor + aria (parallel-group gather + 4-criteria checkpoint, optional `deep_dive`) | | `plan_and_approve` | 3 | Yes | aiops | | `compliance_scan` | 3 | No | monitor + aria | 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. ```yaml # ~/.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: ```bash # 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. ```json { "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

path: evals/evals.json
content: {
  "skill_name": "vmware-pilot",
  "evals": [
    {
      "id": 1,
      "prompt": "I need to expand the database VM's memory from 16GB to 32GB, but test it on a clone first before applying to production",
      "expected_output": "clone_and_test workflow created with approval gate",
      "files": [],
      "expectations": [
        "Uses plan_workflow with type clone_and_test",
        "Change spec includes memory_mb: 32768",
        "Workflow has approval gate before production apply",
        "Shows workflow steps for user review"
      ]
    },
    {
      "id": 2,
      "prompt": "Design a workflow to set up a new app environment: create NSX segment, add firewall rules, deploy 3 VMs, install nginx on each",
      "expected_output": "Custom multi-skill workflow with approval gates",
      "files": [],
      "expectations": [
        "Uses design_workflow or create_workflow",
        "Steps span multiple skills: nsx, nsx-security, aiops",
        "Includes approval gate before VM deployment",
        "Shows the full workflow for user review before execution"
      ]
    },
    {
      "id": 3,
      "prompt": "There's a critical CPU alarm on prod-db-01. Run the incident response workflow to diagnose and fix it",
      "expected_output": "incident_response workflow executed with approval",
      "files": [],
      "expectations": [
        "Uses plan_workflow with type incident_response",
        "Collects alarms and events first",
        "Pauses for approval before remediation",
        "Acknowledges the alarm after approval"
      ]
    },
    {
      "id": 4,
      "prompt": "Save a reusable workflow template for rolling restart of our web cluster (web-01, web-02, web-03) with health checks between each",
      "expected_output": "rolling_restart workflow saved as template",
      "files": [],
      "expectations": [
        "Uses plan_workflow with type rolling_restart or create_workflow",
        "Includes health check between each VM restart",
        "Saves as YAML template with save_as_template=true",
        "Template is reusable for future runs"
      ]
    }
  ]
}


path: references/capabilities.md
content: # Capabilities — vmware-pilot

## MCP Tools (11)

| # | Tool | Risk | Category | Description |
|---|------|------|----------|-------------|
| 1 | `get_skill_catalog` | low | Discovery | List all available skills and tools for workflow design |
| 2 | `list_workflows` | low | Discovery | List built-in + custom templates and active workflows |
| 3 | `design_workflow` | low | Design | Natural language goal → draft workflow for review |
| 4 | `update_draft` | medium | Design | Edit draft workflow steps, name, or description |
| 5 | `confirm_draft` | medium | Design | Finalize draft → state changes to PENDING |
| 6 | `plan_workflow` | medium | Execute | Create workflow from built-in/custom template |
| 7 | `create_workflow` | medium | Execute | Create custom workflow from step list |
| 8 | `run_workflow` | medium | Execute | Execute workflow, pauses at approval gates |
| 9 | `approve` | high | Control | Human approval to continue past approval gate |
| 10 | `rollback` | high | Control | Reverse completed steps in reverse order |
| 11 | `get_workflow_status` | low | Control | Query workflow state, audit log, diff report |

---

## Built-in Templates (14)

| # | Template | Steps | Approval | Skills Used | Risk |
|---|----------|-------|----------|-------------|------|
| 1 | `clone_and_test` | 6 | Yes | aiops, monitor | Medium |
| 2 | `incident_response` | 4 | Yes | monitor, aiops | Medium |
| 3 | `plan_and_approve` | 3 | Yes | aiops | High |
| 4 | `compliance_scan` | 3 | No | monitor, aria | Low |
| 5 | `network_segment_setup` | 2-6 | Yes | nsx, nsx-security | Medium |
| 6 | `vks_cluster_deploy` | 4 | Yes | vks | Medium |
| 7 | `rolling_restart` | 2+3n | Yes | aiops, monitor | Medium |
| 8 | `capacity_expansion` | 5 | Yes | aria, aiops, monitor | Medium |
| 9 | `disaster_recovery` | 5 | Yes | aiops, monitor, nsx | High |
| 10 | `patch_deployment` | 1+3n | Yes | aiops, monitor | Medium |
| 11 | `storage_expansion` | 6 | Yes | storage | Medium |
| 12 | `baseline_capture` | 1-5 | No | monitor, nsx, storage | Low |
| 13 | `baseline_audit` | 2-5 | No | monitor, nsx, storage, aria | Low |
| 14 | `baseline_remediate` | 3+n | Yes | varies | High |

---

## Orchestrated Skills (8)

Pilot does not call VMware APIs directly. It delegates to these skills:

| Skill | Package | Tools | Domain |
|-------|---------|:-----:|--------|
| vmware-aiops | `vmware-aiops` | 34 | VM lifecycle, deployment, guest ops, clusters |
| vmware-monitor | `vmware-monitor` | 7 | Read-only inventory, alarms, events |
| vmware-nsx | `vmware-nsx-mgmt` | 32 | NSX segments, gateways, NAT, routing, IPAM |
| vmware-nsx-security | `vmware-nsx-security` | 20 | DFW policies/rules, security groups, traceflow |
| vmware-aria | `vmware-aria` | 27 | Aria Ops metrics, alerts, capacity, anomalies |
| vmware-vks | `vmware-vks` | 20 | Tanzu Supervisor, Namespaces, TKC clusters |
| vmware-storage | `vmware-storage` | 11 | Datastores, iSCSI, vSAN |
| vmware-avi | `vmware-avi` | 29 | AVI load balancing, pool members, AKO K8s ops |

**Total**: 185 tools across 8 skills (+ 11 pilot tools + 5 harness tools = 201 tools)

---

## Workflow States

```
DRAFT -> PENDING -> RUNNING -> AWAITING_APPROVAL -> RUNNING -> COMPLETED
                        |                                        |
                        +-> FAILED --(rollback)--> ROLLING_BACK  |
                        |                                        |
                        +-> BLOCKED_BY_POLICY                    |
                        |                                        |
                        +-> MONITORING ---> COMMITTING ----------+
```

| State | Description |
|-------|-------------|
| `draft` | AI is designing steps (editable via update_draft) |
| `pending` | Finalized, ready to execute via run_workflow |
| `running` | Currently executing steps sequentially |
| `awaiting_approval` | Paused at an approval gate |
| `monitoring` | Watching for anomalies during test phase |
| `committing` | Applying tested changes to production |
| `rolling_back` | Undoing completed steps in reverse order |
| `completed` | All steps finished successfully |
| `failed` | A step failed (rollback may be available) |
| `blocked_by_policy` | Blocked by vmware-policy rule |

---

## Key Features

### Approval Gates
Pause execution for human review before destructive operations. Workflows can have multiple approval gates. Each gate requires an explicit `approve()` call to continue.

### Automatic Rollback
When a step fails, pilot offers to reverse all completed steps that have `rollback_tool` defined. Rollback executes in reverse order (last completed step first). Best-effort: if one rollback fails, remaining rollbacks still execute.

### State Persistence
All workflow state is stored in SQLite at `~/.vmware/workflows.db` (WAL mode). Workflows survive MCP server restarts and can be resumed.

### Custom Templates
Drop YAML files in `~/.vmware/workflows/` for instant availability. Supports `{{variable}}` placeholders filled from params at runtime. Hot-reloaded without server restart.

### Interactive Design Mode
1. `design_workflow(goal)` creates a draft
2. `update_draft(id, steps)` edits the draft
3. `confirm_draft(id)` finalizes for execution
4. `run_workflow(id)` executes with approval gates

### Policy Integration
All operations audited via vmware-policy `@vmware_tool` decorator. Policy rules in `~/.vmware/rules.yaml` can deny operations based on maintenance windows, risk levels, or custom rules.


path: references/cli-reference.md
content: # CLI Reference — vmware-pilot

vmware-pilot is an **MCP-only** server. It does not provide a standalone CLI binary.
All workflow operations are performed via MCP tool calls through an AI agent or MCP client.

---

## MCP Server Launch

```bash
# Recommended: via uvx (isolated environment)
uvx --from vmware-pilot vmware-pilot-mcp

# Alternative: via pip install
pip install vmware-pilot
vmware-pilot-mcp
```

The server runs on **stdio** transport and exposes 11 MCP tools.

---

## MCP Tool Reference

### Discovery Tools

#### get_skill_catalog

Get available skills and tools for workflow design.

```
get_skill_catalog()
→ {aiops: {tools: {...}}, monitor: {...}, nsx: {...}, ...}
```

#### list_workflows

List built-in and custom templates, plus active workflows.

```
list_workflows()
→ {templates: [...], active_workflows: [...]}
```

### Design Tools

#### design_workflow

Create a draft workflow from natural language description.

```
design_workflow(
    goal="Migrate app01 to new network with firewall",
    constraints="approval before destructive steps"
)
→ {workflow_id: "wf-...", state: "draft", next_step: "..."}
```

#### update_draft

Edit a draft workflow's name, description, or steps.

```
update_draft(
    workflow_id="wf-...",
    name="app_migration",
    steps=[{action: "...", skill: "...", tool: "...", params: {...}}]
)
→ {workflow_id: "wf-...", steps: [...]}
```

#### confirm_draft

Finalize a draft workflow for execution (DRAFT -> PENDING).

```
confirm_draft(
    workflow_id="wf-...",
    save_as_template=True
)
→ {workflow_id: "wf-...", state: "pending"}
```

### Execution Tools

#### plan_workflow

Create a workflow from a built-in or custom template.

```
plan_workflow(
    workflow_type="clone_and_test",
    params={target_vm: "db01", change_spec: {memory_mb: 32768}}
)
→ {workflow_id: "wf-...", steps: [...]}
```

Available types: `clone_and_test`, `incident_response`, `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`.

#### create_workflow

Create a custom workflow directly from a step list.

```
create_workflow(
    name="quick_restart",
    description="Restart with health check",
    steps=[...],
    save_as_template=False
)
→ {workflow_id: "wf-...", steps: [...]}
```

#### run_workflow

Execute a planned workflow. Pauses at approval gates.

```
run_workflow(workflow_id="wf-...")
→ {state: "awaiting_approval", current_step: {...}}
```

### Control Tools

#### approve

Human approval to continue past an approval gate.

```
approve(
    workflow_id="wf-...",
    approver="[REDACTED_SECRET]"
)
→ {state: "running", ...}
```

#### rollback

Abort and reverse completed steps in reverse order.

```
rollback(workflow_id="wf-...")
→ {state: "failed", rollback_results: [...]}
```

#### get_workflow_status

Query workflow state, diff report, and audit log.

```
get_workflow_status(workflow_id="wf-...")
→ {state: "completed", steps: [...], audit_log: [...]}
```

---

## Helper Scripts

### validate_workflow.py

Validate a custom YAML workflow template before use.

```bash
python3 scripts/validate_workflow.py ~/.vmware/workflows/my_workflow.yaml
```

Checks:
- All referenced skills exist in the catalog
- Tool names are recognized
- Approval gates are placed before destructive steps
- Step structure has required fields

### list_available_tools.py

Browse all available skills and tools for workflow design.

```bash
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
```

---

## Audit Log (via vmware-policy)

```bash
vmware-audit log --last 20          # Recent operations
vmware-audit log --status denied    # Denied by policy
vmware-audit log --tool approve     # Filter by tool
```

---

## Custom Workflow YAML Format

```yaml
name: my_workflow
description: Human-readable description
steps:
  - action: check_health
    skill: monitor
    tool: get_alarms
    params:
      target: "{{target}}"

  - action: require_approval
    skill: pilot
    tool: approve
    params:
      message: "Proceed with changes?"

  - action: apply_change
    skill: aiops
    tool: vm_power_off
    params:
      vm_name: "{{vm_name}}"
    rollback_tool: vm_power_on
    rollback_params:
      vm_name: "{{vm_name}}"
```

Place in `~/.vmware/workflows/` with `.yaml` extension. Hot-reloaded without restart.


path: references/setup-guide.md
content: # Setup Guide — vmware-pilot

## Prerequisites

- Python 3.10+
- `vmware-policy` package (auto-installed as dependency)
- At least one companion skill installed (aiops, monitor, nsx, etc.) for workflows to delegate to

## Installation

### Via uv (Recommended)

```bash
uv tool install vmware-pilot
```

### Via pip

```bash
pip install vmware-pilot

# China mainland mirror
pip install vmware-pilot -i https://pypi.tuna.tsinghua.edu.cn/simple
```

### Verify Installation

```bash
# Start the MCP server (exits immediately if all imports succeed)
uvx --from vmware-pilot vmware-pilot-mcp
```

---

## MCP Configuration

### Claude Code

Add to your Claude Code MCP config:

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

### Cursor / VS Code Copilot

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

### Goose

```yaml
extensions:
  vmware-pilot:
    name: vmware-pilot
    type: stdio
    cmd: uvx
    args:
      - --from
      - vmware-pilot
      - vmware-pilot-mcp
```

---

## Configuration

Pilot itself requires **no vCenter/NSX/AVI credentials**. It is a pure orchestrator that delegates all infrastructure calls to companion skills.

### Workflow Database

Workflows are persisted to `~/.vmware/workflows.db` (SQLite, WAL mode). Created automatically on first use.

### Custom Templates Directory

```bash
mkdir -p ~/.vmware/workflows
```

Drop YAML workflow templates here. Hot-reloaded without server restart.

### Policy Rules (Optional)

vmware-policy rules at `~/.vmware/rules.yaml` apply to all pilot operations:

```yaml
# Example: deny destructive operations outside maintenance window
rules:
  - name: maintenance_window
    match:
      risk_level: [high, critical]
    deny_unless:
      time_range: "02:00-06:00"
      timezone: "Asia/Shanghai"
```

### Audit Database

All tool calls are logged to `~/.vmware/audit.db` via vmware-policy. View with:

```bash
vmware-audit log --last 20
vmware-audit log --status denied
```

---

## Companion Skills Setup

For pilot to execute workflows, the relevant companion skills must be installed and configured:

| Skill | Install | Config Location |
|-------|---------|-----------------|
| vmware-aiops | `uv tool install vmware-aiops` | `~/.vmware-aiops/config.yaml` |
| vmware-monitor | `uv tool install vmware-monitor` | `~/.vmware-monitor/config.yaml` |
| vmware-nsx | `uv tool install vmware-nsx-mgmt` | `~/.vmware-nsx/config.yaml` |
| vmware-nsx-security | `uv tool install vmware-nsx-security` | `~/.vmware-nsx-security/config.yaml` |
| vmware-aria | `uv tool install vmware-aria` | `~/.vmware-aria/config.yaml` |
| vmware-vks | `uv tool install vmware-vks` | `~/.vmware-vks/config.yaml` |
| vmware-storage | `uv tool install vmware-storage` | `~/.vmware-storage/config.yaml` |
| vmware-avi | `uv tool install vmware-avi` | `~/.vmware-avi/config.yaml` |

Each skill has its own `doctor` command to verify connectivity:

```bash
vmware-aiops doctor
vmware-monitor doctor
vmware-avi doctor
# etc.
```

---

## Security

### Source Code

[github.com/zw008/VMware-Pilot](https://github.com/zw008/VMware-Pilot) — MIT license.

### Config File Contents

Pilot has no config file of its own. No credentials stored.

### TLS Verification

Not applicable to pilot directly. TLS settings are managed by each companion skill.

### Prompt Injection Protection

All text from VMware/NSX/AVI APIs passes through `_sanitize()` in each companion skill (truncation to 500 chars + C0/C1 control character removal).

### Least Privilege

Pilot itself needs no privileges. Each companion skill should use a service account with minimum required permissions.

### Audit Trail

Every tool call is logged to `~/.vmware/audit.db` with timestamp, tool name, parameters, result, and risk level.

---

## AI Platform Compatibility

| Platform | Transport | Status |
|----------|-----------|--------|
| Claude Code | stdio | Supported |
| Cursor | stdio | Supported |
| VS Code Copilot | stdio | Supported |
| Goose | stdio | Supported |
| Continue.dev | stdio | Supported |
| Ollama (local) | stdio | Supported (MCP client required) |

---

## Troubleshooting

### vmware-policy not found

```bash
pip install vmware-policy
# or
uv pip install vmware-policy
```

vmware-policy is a declared dependency and should install automatically with pilot.

### SQLite "database is locked"

The workflow database uses WAL mode for concurrent access. If you see lock errors, ensure only one MCP server instance is running, or increase the connection timeout.

### Custom template YAML parse error

Validate your template:

```bash
python3 scripts/validate_workflow.py ~/.vmware/workflows/my_workflow.yaml
```

Common issues: incorrect indentation, missing required fields (action, skill, tool, params), invalid YAML syntax.


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)