vmware-vdi

VMware VDI (Horizon)

Disclaimer: Community-maintained open-source project, not affiliated with, endorsed by, or sponsored by VMware, Inc., Broadcom Inc., or Omnissa, LLC. "VMware", "Horizon", and "Omnissa" are trademarks of their respective owners. Source is publicly auditable under the MIT license.

Horizon VDI intelligent operations for the VMware skill family — desktop pools, RDS farms, user sessions, desktop machines, entitlements, events/health/statistics, and instant-clone image push, through the Horizon 8 Connection Server REST API (primary; also targets the latest Omnissa Horizon, which shares the same /rest/v1 API lineage).

Companion skills: vmware-aiops (the vCenter VMs backing the desktops), vmware-monitor (read-only vSphere), vmware-nsx-security (desktop microsegmentation).

Status: v1.0.0 (beta). Endpoints are verified against the official Horizon Server API; GET-response field projections are defensive and pending validation against a live Connection Server (run vmware-vdi init on a real Horizon once to confirm). Governed by the family harness (audit + policy + teaching errors); authorization is delegated to the Horizon admin account's role.

What This Skill Does

27 MCP tools (16 read / 11 write). Reads are strictly non-destructive. Writes preview their blast radius, are double-confirmed at the CLI, and are audit-logged.

Quick Install

uv tool install vmware-vdi
vmware-vdi init      # friendly setup: connect to a Connection Server + discover your pools
vmware-vdi doctor    # verify config / credentials / connectivity

When to Use This Skill

Use vmware-vdi for the Horizon broker layer: desktop pools, RDS farms, published apps, user sessions (logoff/disconnect/message), desktop machine state (reset/maintenance/remove), entitlements, Horizon events/health/statistics, and instant-clone image push — when the context is explicitly Horizon / Omnissa / VDI / desktop-pool / RDS-farm.

Do NOT use when: the task is the underlying vCenter VM (power/snapshot/clone/migrate → vmware-aiops), read-only vSphere inventory/alarms (→ vmware-monitor), or NSX microsegmentation of the desktops (→ vmware-nsx-security). A Horizon desktop's backing VM is aiops; the session/pool/broker is vdi.

Related Skills — Skill Routing

Common Workflows

1. Help-desk: a user's desktop is stuck.

vmware-vdi session list --user alice          # find their session + state
vmware-vdi machine list --state AGENT_UNREACHABLE   # is the desktop broken?
vmware-vdi session logoff --user alice --dry-run    # preview blast radius (which sessions)
vmware-vdi session logoff --user alice        # double-confirm, then logs off + audits

Failure branch: if session list returns a teaching 404/auth error, run vmware-vdi doctor — a read-only Horizon role is enough for the reads but the account must be able to reach the Connection Server.

2. Patch night: push a new golden image to a pool.

vmware-vdi image list                         # find the base VM + snapshot
vmware-vdi pool push-image --id pool-fin --dry-run   # BLAST RADIUS: N desktops, M logged-in users
vmware-vdi pool set-enabled --id pool-fin --disable  # optional: stop new logins first
vmware-vdi pool push-image --id pool-fin      # double-confirm; returns a task
vmware-vdi task status --pool pool-fin         # track progress

Failure branch: if the preview shows logged-in users you did not expect, session send-message --user … to warn them, or push with --force-logoff only after confirming impact.

3. Onboard a group to a pool.

vmware-vdi ad-search "Finance"                # resolve the AD group → its SID
vmware-vdi entitlement add --pool pool-fin --sid 
vmware-vdi entitlement list --pool pool-fin   # verify

Failure branch: ad-search returning nothing usually means the domain in ~/.vmware-vdi/config.yaml is wrong — re-run vmware-vdi init --force.

Usage Mode

• CLI — interactive help-desk work, scripting, small/local models (lower context cost).
• MCP — agent-driven operations with structured output; run vmware-vdi mcp (an installed console script, so no uvx network re-resolve — works through enterprise TLS proxies).

MCP Tools (27 — 16 read, 11 write)

List envelope: every *_list tool returns {items, returned, limit, total, truncated, hint} — read rows from items and check truncated before concluding a listing is complete; empty items with truncated:false means checked-and-none, not a failure. Lists are fetched with server-side pagination.

Blast radius (normative): pool_push_image recreates every desktop in the pool — the highest single-call blast radius in the family. Its preview states affected-desktop and in-session-user counts before any confirm. session_logoff / machine_reset / machine_remove state their affected users/ machines and require double confirmation at the CLI.

Read/write split: 16 read-only tools ([READ] docstring marker), 11 modify state. All writes are audit-logged; destructive ones (session_logoff, machine_reset, machine_remove, pool_set_enabled disable, entitlement_remove, pool_push_image, task_cancel) require CLI double-confirmation and support --dry-run.

CLI Quick Reference

vmware-vdi init                                          # friendly setup + pool discovery
vmware-vdi health                                        # one-glance VDI health
vmware-vdi stats                                         # session concurrency statistics
vmware-vdi utilization                                   # per-pool desktop utilization
vmware-vdi session list [--user U] [--pool P] [--state CONNECTED]
vmware-vdi session logoff --user U [--dry-run]           # double-confirm
vmware-vdi machine list [--pool P] [--state AGENT_UNREACHABLE]
vmware-vdi machine reset --id M [--dry-run]              # hard reset; double-confirm
vmware-vdi machine maintenance --id M --enter|--exit
vmware-vdi pool list
vmware-vdi pool set-enabled --id P --enable|--disable
vmware-vdi pool push-image --id P [--force-logoff] [--dry-run]   # highest blast radius
vmware-vdi task status --pool P [--task T]
vmware-vdi ad-search ""                            # resolve AD SID for entitlement
vmware-vdi entitlement add|remove --pool P --sid 

Full list: references/cli-reference.md.

Troubleshooting

• Password not found. Set environment variable: VMWARE_VDI__PASSWORD — run vmware-vdi init (writes ~/.vmware-vdi/.env, 0600), or export the var manually.
• Login fails (HTTP 401/400) — check username/domain in ~/.vmware-vdi/config.yaml; Horizon authenticates against the AD domain. A local Connection Server admin leaves domain blank.
• certificate could not be verified — for a self-signed lab cert set verify_ssl: false for that target in the config.
• A write is refused with "read-only role" — that is RBAC working as designed. Point the target at a Horizon admin role with write privilege, or keep the read-only account for read commands only.
• session list --pool or a push-image preview shows 0 where you expect users — on your Horizon version a field name may differ; this is a beta known-limitation, please file an issue with the raw session_get output so the projection can be pinned.

Audit & Safety

1. Source Code — https://github.com/vmware-skills/VMware-VDI (MIT).
2. Config File Contents — config.yaml holds host/username/domain only; passwords live in ~/.vmware-vdi/.env (0600, obfuscated to b64: at rest — obfuscation, not encryption).
3. Webhook Data Scope — none. This skill makes no outbound calls except to the configured Connection Server.
4. TLS Verification — on by default; verify_ssl: false is per-target and only for self-signed labs.
5. Prompt Injection Protection — all Connection-Server-supplied text (user names, machine/pool names, event messages) passes through vmware_policy.sanitize() (truncation + control-char stripping).
6. Least Privilege — authorization is the Horizon account's job: a read-only Horizon admin role refuses every write at the Connection Server, un-bypassably. All writes are recorded in ~/.vmware/audit.db. See references/setup-guide.md.

License

MIT