{"id":"c6090e12-85dc-4759-be23-77e63b55d433","entityType":"agent","slug":"clawhub-zw008-vmware-nsx","name":"vmware-nsx","canonicalUrl":"https://www.xpersona.co/agent/clawhub-zw008-vmware-nsx","canonicalPath":"/agent/clawhub-zw008-vmware-nsx","generatedAt":"2026-10-09T16:25:47.988Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T04:35:55.093Z","emptyReason":null},"description":"Use this skill when the user needs to inspect or manage VMware NSX networking through NSX Manager — segments, Tier-0/Tier-1 gateways, NAT, static routes/BGP, and IP pools. Directly handles: list and inspect segments, gateways, NAT rules, routes and IP pools; check transport node, edge cluster and manager health; find a VM's segment. Changes (create/update/delete segments, Tier-1 gateways, NAT rules, static routes, IP pools, Tier-0 BGP) only when the user explicitly asks for that change. Use this skill for \"create segment\", \"set up gateway\", \"create NAT rule\", \"check network health\", \"troubleshoot connectivity\" when the context is explicitly NSX, NSX-T, or NSX Manager. Do NOT use for networking outside NSX, DFW firewall rules or security groups (use vmware-nsx-security), vSphere distributed port groups or host VMkernel adapters (use vmware-aiops), VM lifecycle (use vmware-aiops), or AVI/ALB load balancing (use vmware-avi). For multi-step workflows use vmware-pilot.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 4.9K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s171xgnmqse0nqvgqvqnaq5f9183kyre:vmware-nsx","sourceUrl":"https://clawhub.ai/zw008/vmware-nsx","homepage":"https://clawhub.ai/zw008/skills/vmware-nsx","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/zw008/vmware-nsx","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/zw008/skills/vmware-nsx","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":48,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"vmware-nsx technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T04:35:55.093Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T04:35:55.093Z","emptyReason":null},"stars":null,"forks":null,"downloads":4919,"packageName":null,"latestVersion":"1.11.0","tractionLabel":"4.9K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T04:35:55.092Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T04:35:55.093Z","lastCrawledAt":"2026-10-09T04:35:55.092Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T04:35:55.092Z","lastVerifiedAt":null,"highlights":[{"version":"1.11.0","createdAt":"2026-09-20T14:52:04.988Z","changelog":"MCP instructions now name the configured targets and how to choose one; a config that cannot be read says so instead of falling silent.","fileCount":8,"zipByteSize":33861},{"version":"1.10.0","createdAt":"2026-09-19T03:55:23.906Z","changelog":"Destructive MCP tools preview by default (confirm=False) and state their blast radius; confirm=True refuses on blockers or unreadable measurements. Requires vmware-policy>=1.17.0.","fileCount":8,"zipByteSize":33927},{"version":"1.9.1","createdAt":"2026-09-15T06:05:07.778Z","changelog":"CLI reads are audited under their MCP tool names; every CLI command declares what it reaches (needs vmware-policy 1.15.0)","fileCount":8,"zipByteSize":32885},{"version":"1.9.0","createdAt":"2026-09-12T00:19:03.975Z","changelog":"A Tier-1 gateway or segment that cannot be deleted is refused before anything is touched, with every blocker named, instead of failing inside NSX after success-shaped output. create_ip_pool reports a partial failure as a failure. CLI writes are authorised and audited under their MCP tool names.","fileCount":8,"zipByteSize":32945},{"version":"1.8.16","createdAt":"2026-08-31T07:24:33.619Z","changelog":"one answer per .env, on every platform","fileCount":8,"zipByteSize":30515},{"version":"1.8.15","createdAt":"2026-08-31T00:34:45.007Z","changelog":"fix: run the suite on a non-UTF-8 machine, and stop one skill answering for another","fileCount":8,"zipByteSize":30553},{"version":"1.8.14","createdAt":"2026-08-30T15:53:04.519Z","changelog":"See RELEASE_NOTES.md for v1.8.14","fileCount":8,"zipByteSize":30623},{"version":"1.8.13","createdAt":"2026-08-30T15:18:32.657Z","changelog":"Second-round fixes from the 2026-08-30 VCF 9.1 re-test; vmware-policy floor raised to 1.11.0 (the engine no longer fails open when rules.yaml cannot be read).","fileCount":8,"zipByteSize":30560}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s171xgnmqse0nqvgqvqnaq5f9183kyre:vmware-nsx","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s171xgnmqse0nqvgqvqnaq5f9183kyre:vmware-nsx` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/zw008/vmware-nsx before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-vmware-nsx/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-vmware-nsx/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-vmware-nsx/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-zw008-vmware-nsx/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-zw008-vmware-nsx/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-zw008-vmware-nsx/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T16:25:47.984Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-vmware-nsx/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-vmware-nsx/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-vmware-nsx/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-vmware-nsx/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T04:35:55.093Z","emptyReason":null},"readme":"Skill: vmware-nsx\n\nOwner: zw008\n\nSummary: Use this skill when the user needs to inspect or manage VMware NSX networking through NSX Manager — segments, Tier-0/Tier-1 gateways, NAT, static routes/BGP, and IP pools. Directly handles: list and inspect segments, gateways, NAT rules, routes and IP pools; check transport node, edge cluster and manager health; find a VM's segment. Changes (create/update/delete segments, Tier-1 gateways, NAT rules, static routes, IP pools, Tier-0 BGP) only when the user explicitly asks for that change. Use this skill for \"create segment\", \"set up gateway\", \"create NAT rule\", \"check network health\", \"troubleshoot connectivity\" when the context is explicitly NSX, NSX-T, or NSX Manager. Do NOT use for networking outside NSX, DFW firewall rules or security groups (use vmware-nsx-security), vSphere distributed port groups or host VMkernel adapters (use vmware-aiops), VM lifecycle (use vmware-aiops), or AVI/ALB load balancing (use vmware-avi). For multi-step workflows use vmware-pilot.\n\nTags: latest:1.11.0\n\nVersion history:\n\nv1.11.0 | 2026-09-20T14:52:04.988Z | user\n\nMCP instructions now name the configured targets and how to choose one; a config that cannot be read says so instead of falling silent.\n\nv1.10.0 | 2026-09-19T03:55:23.906Z | user\n\nDestructive MCP tools preview by default (confirm=False) and state their blast radius; confirm=True refuses on blockers or unreadable measurements. Requires vmware-policy>=1.17.0.\n\nv1.9.1 | 2026-09-15T06:05:07.778Z | user\n\nCLI reads are audited under their MCP tool names; every CLI command declares what it reaches (needs vmware-policy 1.15.0)\n\nv1.9.0 | 2026-09-12T00:19:03.975Z | user\n\nA Tier-1 gateway or segment that cannot be deleted is refused before anything is touched, with every blocker named, instead of failing inside NSX after success-shaped output. create_ip_pool reports a partial failure as a failure. CLI writes are authorised and audited under their MCP tool names.\n\nv1.8.16 | 2026-08-31T07:24:33.619Z | user\n\none answer per .env, on every platform\n\nv1.8.15 | 2026-08-31T00:34:45.007Z | user\n\nfix: run the suite on a non-UTF-8 machine, and stop one skill answering for another\n\nv1.8.14 | 2026-08-30T15:53:04.519Z | user\n\nSee RELEASE_NOTES.md for v1.8.14\n\nv1.8.13 | 2026-08-30T15:18:32.657Z | user\n\nSecond-round fixes from the 2026-08-30 VCF 9.1 re-test; vmware-policy floor raised to 1.11.0 (the engine no longer fails open when rules.yaml cannot be read).\n\nv1.8.12 | 2026-08-30T09:34:45.427Z | user\n\nParameter descriptions now reach the MCP JSON schema (0% -> 100% coverage); additionalProperties closed; vmware-policy floor raised to 1.10.0.\n\nv1.8.11 | 2026-08-30T07:50:08.153Z | user\n\nTen list tools gain limit/offset/next_offset; limit=0 and negatives rejected instead of silently mangled; verify_ssl:false no longer needs an undeclared urllib3; doctor reads the config the tools read.\n\nv1.8.10 | 2026-08-28T02:55:59.897Z | user\n\nFixes the server's self-reported version and the advertised tool count; adds a Claude Code plugin manifest.\n\nv1.8.9 | 2026-08-01T03:11:39.762Z | user\n\nMoved to vmware-skills GitHub org; MCP Registry namespace → io.github.vmware-skills. Links updated.\n\nv1.8.8 | 2026-07-21T15:43:49.175Z | user\n\nCLI writes now route through the shared guard()+audit_call() core via @guarded, exactly like the MCP tools (HLD I-1/I-8). Requires vmware-policy>=1.8.8.\n\nv1.8.7 | 2026-07-21T11:39:59.727Z | user\n\nRemove read-only switch and approval tiers; read/write authz delegated to RBAC. Plus accumulated fixes since 1.8.5.\n\nv1.8.5 | 2026-07-20T13:04:29.956Z | user\n\nA failure that is returned is now audited as a failure, and certificate/URL detail no longer reaches the agent. Both fixes v1.8.4 announced were incomplete.\n\nv1.8.4 | 2026-07-20T08:25:54.910Z | user\n\nTeaching error messages, domain exceptions no longer redacted on the way to the agent, and tool descriptions that state when to use each tool and what to call next.\n\nv1.8.3 | 2026-07-20T03:46:20.407Z | user\n\nPer-target username can now come from an env var, resolved per access like the password; documented credential variables corrected against what each repo's code actually reads\n\nv1.8.2 | 2026-07-19T18:04:56.329Z | user\n\nMCP server moved into the package namespace — fixes two skills in one environment silently overwriting each other's server; agent-guardrails.md for local/small models now ships in every skill\n\nv1.8.1 | 2026-07-19T11:31:58.349Z | user\n\nRead-only mode now documented on every surface that teaches it (SKILL.md, setup-guide, capabilities) and reported by doctor\n\nv1.8.0 | 2026-07-19T09:46:04.136Z | user\n\nRead-only mode (13 write tools withheld), list-result envelope, declared environments; capabilities.md rewritten against the live registry — 11 non-existent tools removed, 6 real ones documented\n\nv1.7.5 | 2026-07-13T07:17:02.540Z | user\n\ndead-code cleanup; family version alignment\n\nv1.7.4 | 2026-07-13T04:52:19.013Z | user\n\nFamily version alignment to 1.7.4 (substantive change this cycle is in vmware-monitor: host-check boundary read batching).\n\nv1.7.3 | 2026-07-03T00:48:40.649Z | user\n\nFamily version alignment (v1.7.3)\n\nv1.7.2 | 2026-07-02T14:31:10.391Z | user\n\nPaginate list ops + bound port-status/segment-scan N+1\n\nv1.7.1 | 2026-07-02T10:52:57.763Z | user\n\nFamily version alignment with v1.7.1 (AIops/Monitor large-inventory scale fix, issue #31).\n\nv1.7.0 | 2026-06-27T01:01:35.097Z | user\n\nguided init wizard + form-body auth teaching\n\nv1.6.1 | 2026-06-24T00:00:58.991Z | user\n\nv1.6.1 .env password b64 obfuscation\n\nv1.6.0 | 2026-06-22T09:17:22.794Z | user\n\nv1.6.0 trust architecture: undo tokens + governance harness (budget/audit/risk-tiers)\n\nv1.5.39 | 2026-06-22T00:42:19.258Z | user\n\nv1.5.39: AIops snapshot-delete async + honest timeout (token-burn fix), Storage browse timeout fix; others version-aligned\n\nv1.5.38 | 2026-06-12T06:59:28.043Z | user\n\nbacklog finish: cli/server split\n\nv1.5.37 | 2026-06-12T01:58:19.868Z | user\n\nbacklog: IP-pool lifecycle, tier-0 routes, faster VM lookup\n\nv1.5.36 | 2026-06-11T23:21:49.218Z | user\n\ncentralized HTTP error translation + SKILL.md accuracy\n\nv1.5.35 | 2026-06-10T00:45:06.726Z | user\n\nSecurity hardening: safe error handling, TLS/path/permission fixes\n\nv1.5.32 | 2026-06-08T02:47:31.135Z | user\n\nv1.5.32: response parsing fixed vs official NSX 4.2 SDK + spec-conformance CI\n\nv1.5.30 | 2026-06-07T13:23:14.020Z | user\n\nv1.5.30: fix 4 broken gateway/route/pool tools (MCP+CLI) + Glama TDQS description rewrite\n\nv1.5.29 | 2026-05-29T02:19:51.620Z | user\n\nFamily version alignment (no NSX-specific changes since v1.5.28)\n\nv1.5.28 | 2026-05-20T10:00:14.985Z | user\n\nFix subclass() arg 1 must be a class in goose/old-mcp environments. v1.5.25-1.5.27 only addressed PEP 604 X|None -> Optional[X] but kept 'from __future__ import annotations'; under mcp 1.10-1.13 FastMCP's issubclass() on string annotations crashed server load. This release removes the future import. CLAUDE.md pitfall #33 updated.\n\nv1.5.27 | 2026-05-20T06:57:09.007Z | user\n\nLoosen Python requirement to >= 3.10 (was >=3.11). v1.5.25/26 PEP 604 fix already enables 3.10 at runtime; this release lifts pip download/install block.\n\nv1.5.26 | 2026-05-20T06:17:20.462Z | user\n\nMCP server Python 3.10 compatibility (踩坑 #33): PEP 604 X|None → Optional[X] in tool signatures; mcp_cmd Python version guard; mcp[cli]>=1.10\n\nv1.5.23 | 2026-05-19T02:58:25.360Z | user\n\nVCF 9.0 / 9.1 compatibility declared. README version-compat tables updated. Added Official Broadcom References (VCF Python SDK, REST APIs, CLI tools).\n\nv1.5.22 | 2026-05-08T23:25:11.400Z | user\n\nv1.5.22 family alignment for Smithery rollout\n\nv1.5.21 | 2026-05-08T23:20:36.539Z | user\n\nv1.5.21 family alignment + python-multipart 0.0.27\n\nv1.5.20 | 2026-05-08T22:39:57.386Z | user\n\nv1.5.20 family alignment + MCP Registry mcp-name markers\n\nv1.5.19 | 2026-05-06T04:03:23.176Z | user\n\nv1.5.19 — yjs review fixes: NSX CLI subcommand imports (CRITICAL), VKS delete_tkc_cluster ApiClient leak, Harden Twin snapshot_id indexes + LEFT JOIN report, Policy approval gate + singleton lock; py3.11+ requirement; family_smoke recursive subcommand smoke.\n\nv1.5.18 | 2026-05-02T12:12:02.089Z | user\n\nv1.5.18 — family alignment + tooling normalization. Migrated dev deps to [dependency-groups] (PEP 735); added regression eval suite (tests/eval/regression/) catching v1.5.x release blockers.\n\nv1.5.17 | 2026-05-01T11:47:05.858Z | user\n\nv1.5.17 - Family alignment with vmware-pilot v1.5.17 (review_workflow + investigate_alert) and vmware-policy v1.5.17 (L5 pattern matcher). No source changes in this skill.\n\nv1.5.16 | 2026-05-01T03:31:17.831Z | user\n\nv1.5.16 - Enterprise Harness Engineering alignment: 5-level automation taxonomy (L1-L5) in capabilities.md, expert judgment encoded into Common Workflows pre-flight sections, causal-chain investigation protocol shared across aria/monitor/aiops, family version bump.\n\nv1.5.15 | 2026-04-29T18:29:35.990Z | user\n\nv1.5.15: single-command MCP entry point (vmware-nsx mcp), verify_ssl default true. Legacy entry point kept for backward compat.\n\nv1.5.14 | 2026-04-21T12:20:47.108Z | user\n\nv1.5.14: code review fixes by @yjs-2026 + Snyk E005 disclaimer\n\nv1.5.12 | 2026-04-17T10:05:22.535Z | user\n\nSecurity & bug fixes from @yjs-2026 code review\n\nArchive index:\n\nArchive v1.11.0: 8 files, 33861 bytes\n\nFiles: evals/evals.json (1283b), references/agent-guardrails.md (9098b), references/capabilities.md (20638b), references/cli-reference.md (12335b), references/setup-guide.md (15589b), skill-card.md (2614b), SKILL.md (23976b), _meta.json (130b)\n\nFile v1.11.0:SKILL.md\n\n---\nname: vmware-nsx\ndescription: >\n Use this skill when the user needs to inspect or manage VMware NSX networking through NSX Manager — segments, Tier-0/Tier-1 gateways, NAT, static routes/BGP, and IP pools.\n Directly handles: list and inspect segments, gateways, NAT rules, routes and IP pools; check transport node, edge cluster and manager health; find a VM's segment. Changes (create/update/delete segments, Tier-1 gateways, NAT rules, static routes, IP pools, Tier-0 BGP) only when the user explicitly asks for that change.\n Use this skill for \"create segment\", \"set up gateway\", \"create NAT rule\", \"check network health\", \"troubleshoot connectivity\" when the context is explicitly NSX, NSX-T, or NSX Manager.\n Do NOT use for networking outside NSX, DFW firewall rules or security groups (use vmware-nsx-security), vSphere distributed port groups or host VMkernel adapters (use vmware-aiops), VM lifecycle (use vmware-aiops), or AVI/ALB load balancing (use vmware-avi).\n For multi-step workflows use vmware-pilot.\ninstaller:\n kind: uv\n package: vmware-nsx-mgmt\nallowed-tools:\n - Bash\nmetadata: {\"openclaw\":{\"requires\":{\"anyBins\":[\"vmware-nsx\",\"uvx\"]},\"optional\":{\"env\":[\"VMWARE_NSX_CONFIG\",\"VMWARE_NSX__PASSWORD\",\"VMWARE_NSX__USERNAME\",\"VMWARE_AUDIT_APPROVED_BY\"],\"bins\":[\"vmware-policy\"]},\"homepage\":\"https://github.com/vmware-skills/VMware-NSX\",\"emoji\":\"🌐\",\"os\":[\"macos\",\"linux\"]}}\ncompatibility: >\n vmware-policy auto-installed as Python dependency (provides @vmware_tool decorator and audit logging). All write operations audited to ~/.vmware/audit.db.\n Credentials: Each NSX Manager target requires a per-target password env var in ~/.vmware-nsx/.env following the pattern VMWARE_NSX__PASSWORD. Username/password session auth only (client-certificate auth is not implemented). Passwords are never logged or echoed.\n Write operations: CLI write commands require double confirmation and support --dry-run. The five MCP delete tools preview by default — without confirm=True they return the blast radius and change nothing, and confirm=True is refused while a blocker remains (attached ports, Tier-1 dependents, allocated IPs) or a read failed. Other MCP write tools execute when called and are audit-logged, so the agent must call them only on the user's explicit request; ~/.vmware/rules.yaml deny rules can block them per environment.\n VMWARE_AUDIT_APPROVED_BY is an optional attestation recorded in the audit row; it is not a gate and does not carry credentials.\n No webhooks, no outbound network calls, no guest operations. Local only: stdio MCP + NSX Policy API (HTTPS 443).\n SSL bypass: verify_ssl is on by default; trust a private CA via the SSL_CERT_FILE env var; verify_ssl false only for isolated labs with self-signed certs.\n Transitive dependencies: Only vmware-policy (audit/policy). No post-install scripts or background services.\n---\n\n# VMware NSX\n\n> **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\" and \"NSX\" are trademarks of Broadcom. Source code is publicly auditable at [github.com/vmware-skills/VMware-NSX](https://github.com/vmware-skills/VMware-NSX) under the MIT license.\n\nVMware NSX networking management — 33 MCP tools for segments, gateways, NAT, routing, and IPAM.\n\n> Domain-focused networking skill for NSX-T / NSX 4.x Policy API.\n> **Companion skills**: [vmware-nsx-security](https://github.com/vmware-skills/VMware-NSX-Security) (DFW/firewall), [vmware-aiops](https://github.com/vmware-skills/VMware-AIops) (VM lifecycle), [vmware-monitor](https://github.com/vmware-skills/VMware-Monitor) (read-only monitoring), [vmware-storage](https://github.com/vmware-skills/VMware-Storage) (iSCSI/vSAN), [vmware-vks](https://github.com/vmware-skills/VMware-VKS) (Tanzu Kubernetes), [vmware-aria](https://github.com/vmware-skills/VMware-Aria) (metrics/alerts/capacity), [vmware-avi](https://github.com/vmware-skills/VMware-AVI) (AVI/ALB/AKO), [vmware-harden](https://github.com/vmware-skills/VMware-Harden) (compliance baselines).\n> | [vmware-pilot](../vmware-pilot/SKILL.md) (workflow orchestration) | [vmware-policy](../vmware-policy/SKILL.md) (audit/policy)\n\n## What This Skill Does\n\n| Category | Tools | Count | Read / Write |\n|----------|-------|:-----:|:------------:|\n| **Segments** | list, get details, create, update, delete | 5 | 2R / 3W |\n| **Tier-0 Gateways** | list, get details, BGP neighbors, configure BGP | 4 | 3R / 1W |\n| **Tier-1 Gateways** | list, get details, create, update, delete | 5 | 2R / 3W |\n| **NAT** | list rules, create rule, delete rule | 3 | 1R / 2W |\n| **Static Routes** | list, create, delete | 3 | 1R / 2W |\n| **IP Pools** | list, get usage, create pool, delete pool | 4 | 2R / 2W |\n| **Fabric Inventory** | transport zones, transport nodes, edge clusters | 3 | 3R / 0W |\n| **Health** | NSX alarms, transport node status, edge cluster status, manager status | 4 | 4R / 0W |\n| **Troubleshooting** | logical port status, VM-to-segment lookup | 2 | 2R / 0W |\n\n**Total**: 33 tools (20 read-only + 13 write)\n\n## Quick Install\n\n```bash\nuv tool install vmware-nsx-mgmt==1.11.0\nvmware-nsx init # guided setup: writes config + .env (chmod 600, password grep-safe), then verifies\nvmware-nsx doctor\n```\n\n## When to Use This Skill\n\n- List, create, or modify NSX segments (overlay / VLAN-backed)\n- Create or manage Tier-0 / Tier-1 gateways\n- Configure NAT rules (SNAT, DNAT, reflexive)\n- View or add static routes, check BGP neighbors\n- Manage IP pools and subnet allocations\n- Check NSX alarms, transport node health, edge cluster status\n- Find which segment a VM is connected to\n- Troubleshoot logical port status\n\nUse it only when the request is explicitly about NSX (NSX-T / NSX 4.x, NSX Manager). **Writes only on request**: call a create/update/delete tool, NAT/route/IP-pool change, or Tier-0 BGP change only when the user has explicitly asked for that specific change — never as a side step of a read, health check, or troubleshooting task. Diagnose with read tools first and propose the change instead.\n\n**Use companion skills for**:\n- Distributed firewall, security groups, DFW rules, IDS/IPS → `vmware-nsx-security`\n- vSphere distributed port groups, host VMkernel adapters → `vmware-aiops`\n- VM lifecycle, deployment, guest ops → `vmware-aiops`\n- vSphere inventory, health, alarms, events → `vmware-monitor`\n- Storage: iSCSI, vSAN, datastores → `vmware-storage`\n- Tanzu Kubernetes → `vmware-vks`\n- Load balancing, AVI/ALB, AKO, Ingress → `vmware-avi`\n\n## Related Skills — Skill Routing\n\n| User Intent | Recommended Skill |\n|-------------|-------------------|\n| NSX networking: segments, gateways, NAT, routing, IPAM | **vmware-nsx** ← this skill |\n| NSX security: DFW rules, security groups, IDS/IPS | **vmware-nsx-security** |\n| Read-only vSphere monitoring, alarms, events | **vmware-monitor** |\n| VM lifecycle, deployment, guest ops | **vmware-aiops** |\n| vSphere distributed port groups, host VMkernel adapters | **vmware-aiops** |\n| Storage: iSCSI, vSAN, datastores | **vmware-storage** |\n| Tanzu Kubernetes (vSphere 8.x+) | **vmware-vks** |\n| Aria Ops: metrics, alerts, capacity planning | **vmware-aria** |\n| Multi-step workflows with approval | **vmware-pilot** |\n| Compliance baselines (CIS / 等保 / PCI-DSS), drift detection, LLM remediation advisor | **vmware-harden** (`uv tool install vmware-harden`) |\n| Load balancer, AVI, ALB, AKO, Ingress | **vmware-avi** (`uv tool install vmware-avi`) |\n| Audit log query | **vmware-policy** (`vmware-audit` CLI) |\n\n## Common Workflows\n\n### Create an App Network (Segment + T1 Gateway + NAT)\n\n**Pre-flight (judgment, not blind sequence)**:\n- Subnet conflict check: scan `inventory list-segments` and `networking list-ip-pools` for any overlap with the proposed CIDR. Overlapping subnets cause asymmetric routing or silent blackholing — NSX will not warn you.\n- Edge cluster capacity: confirm chosen `--edge-cluster` is healthy (`inventory list-edge-clusters` + `health edge-cluster-status `) and not at SR (Service Router) limit. A fully-loaded edge cluster will accept the T1 creation but routing will fail.\n- T0 uplink: the parent T0 must already be configured with BGP/static routes upstream — otherwise SNAT works internally but external traffic goes nowhere.\n- NAT IP: `--translated` IP must be from a routable address pool announced by T0; using a random IP creates a half-working network.\n- **Always `--dry-run` first** — once a segment is attached to running VMs, deleting it requires detaching every port.\n\n**Steps**:\n1. `vmware-nsx gateway create-tier1 app-t1 --name app-t1 --edge-cluster --tier0 --dry-run` → review, then run for real\n2. `vmware-nsx segment create app-web-seg --name app-web-seg --tz --subnet `\n3. `vmware-nsx nat create-rule --tier1 app-t1 --rule-id snat-1 --action SNAT --source --translated `\n4. Verify end-to-end: `inventory list-segments`, `networking list-nat-rules app-t1`, AND test with a VM attached to the new segment\n5. **On failure**: a connection error or HTTP error prints a single teaching line (e.g. 403 → check NSX role privileges; 404 → run the matching list command for the exact ID). Run `vmware-nsx doctor` to verify connectivity and credentials, fix, and re-run the failed step — earlier completed steps are idempotent PUTs and safe to re-apply.\n\n### Check Network Health\n\n**Judgment**: don't just enumerate health endpoints — correlate them. The order below maps cause to symptom: if manager is down, transport nodes will look down too (false positive); fix top-down.\n\n1. `vmware-nsx health manager-status` — if **any** manager node is `DEGRADED` or `DOWN`, stop here and resolve before trusting downstream signals\n2. `vmware-nsx inventory list-transport-nodes` then `health transport-node-status ` for any node not `UP` — flag nodes down ≥ 5 min; transient blips are normal\n3. `vmware-nsx inventory list-edge-clusters` then `health edge-cluster-status ` — verify SR placement is balanced; one edge holding 80% of SRs is a single point of failure\n4. `vmware-nsx health alarms --severity HIGH` (repeat with `CRITICAL`) — severity filter is exact-match, not \"and above\"\n5. Cross-check with `vmware-monitor` for vSphere host events — a host losing connection to vCenter often masquerades as an NSX problem\n\n### Troubleshoot VM Connectivity\n\n**Judgment**: connectivity failures happen at one of three layers. Identify which layer first, then drill — don't probe randomly.\n\n- **Layer 1 — VM-to-segment**: VM has no segment, wrong vNIC, or port admin-down → `troubleshoot vm-segment` + `troubleshoot port-status`\n- **Layer 2 — segment-to-gateway**: segment not attached to T1, T1 not connected to T0 → `inventory get-tier1` shows no Tier-0 path\n- **Layer 3 — gateway-to-upstream**: T0 BGP/static missing or SNAT not configured → `networking bgp-neighbors`, `networking list-nat-rules`\n\n**Steps** (stop as soon as the failing layer is identified):\n1. Layer 1: `troubleshoot vm-segment my-vm-01` → if no port, check vSphere vNIC binding first\n2. Layer 1: `troubleshoot port-status ` → admin-down or DFW-blocked? If DFW, jump to vmware-nsx-security\n3. Layer 2: `inventory get-tier1 app-t1` → Tier-0 path present and route advertisement enabled? If not, T1↔T0 link broken\n4. Layer 3: `networking bgp-neighbors tier0-gw` → all neighbors `ESTABLISHED`? Flapping → upstream issue\n5. Layer 3: `networking list-nat-rules app-t1` → SNAT rule covers the source CIDR? Mis-typed CIDR is the most common cause\n\n### Multi-Target Operations\n\nAll commands accept `--target ` to operate against a specific NSX Manager from your config (default: the first target in config.yaml), e.g. `vmware-nsx inventory list-segments --target nsx-prod`.\n\n## Usage Mode\n\n| Scenario | Recommended | Why |\n|----------|:-----------:|-----|\n| Local/small models (Ollama, Qwen) | **CLI** | ~2K tokens vs ~8K for MCP |\n| Cloud models (Claude, GPT-4o) | Either | MCP gives structured JSON I/O |\n| Automated pipelines | **MCP** | Type-safe parameters, structured output |\n\n## MCP Tools (33 — 20 read, 13 write)\n\nAll MCP tools accept an optional `target` parameter to select which NSX Manager to connect to.\n\n| Category | Tool | Type | Description |\n|----------|------|:----:|-------------|\n| Segment | `list_segments` | Read | List all segments with type, subnet, admin state, port count |\n| | `get_segment` | Read | Get segment details including ports and subnet config |\n| | `create_segment` | Write | Create overlay or VLAN segment with subnet and gateway |\n| | `update_segment` | Write | Update segment properties (name, subnets, gateway link) |\n| | `delete_segment` | Write | Delete a segment; refuses (listing port ids) while ports are attached |\n| Tier-0 GW | `list_tier0_gateways` | Read | List Tier-0 gateways with HA mode and transit subnets |\n| | `get_tier0_gateway` | Read | Get Tier-0 details: HA mode, failover, transit subnets |\n| | `get_bgp_neighbors` | Read | List BGP neighbor sessions with state, ASN, prefixes |\n| | `configure_tier0_bgp` | Write | Configure BGP (local AS, ECMP, inter-SR iBGP) on a Tier-0 |\n| Tier-1 GW | `list_tier1_gateways` | Read | List Tier-1 gateways with linked Tier-0 and route advertisement |\n| | `get_tier1_gateway` | Read | Get Tier-1 details: Tier-0 link, route advertisement |\n| | `create_tier1_gateway` | Write | Create Tier-1 gateway with edge cluster and Tier-0 link |\n| | `update_tier1_gateway` | Write | Update Tier-1 properties (route advertisement, Tier-0 link) |\n| | `delete_tier1_gateway` | Write | Delete a Tier-1 gateway; refuses (listing blocking ids) while segments, NAT rules, routes, interfaces or VPN / DNS / LB services remain |\n| NAT | `list_nat_rules` | Read | List NAT rules on a Tier-1 gateway |\n| | `create_nat_rule` | Write | Create SNAT/DNAT/reflexive NAT rule on a gateway |\n| | `delete_nat_rule` | Write | Delete a NAT rule |\n| Static Routes | `list_static_routes` | Read | List static routes on a Tier-1 gateway |\n| | `create_static_route` | Write | Add a static route with network and next-hop |\n| | `delete_static_route` | Write | Remove a static route |\n| IP Pools | `list_ip_pools` | Read | List IP pools with usage summary |\n| | `get_ip_pool_usage` | Read | Show allocation usage for a pool |\n| | `create_ip_pool` | Write | Create a new IP address pool with allocation ranges |\n| | `delete_ip_pool` | Write | Permanently delete an IP address pool; refuses while IPs are allocated |\n| Fabric | `list_transport_zones` | Read | List transport zones with type (OVERLAY/VLAN) |\n| | `list_transport_nodes` | Read | List transport nodes with node type and status |\n| | `list_edge_clusters` | Read | List edge clusters with member count and deployment type |\n| Health | `list_nsx_alarms` | Read | List active NSX alarms filtered by severity |\n| | `get_transport_node_status` | Read | Transport node connectivity and config status |\n| | `get_edge_cluster_status` | Read | Edge cluster member status and failover config |\n| | `get_nsx_manager_status` | Read | NSX Manager cluster health and node roles |\n| Troubleshoot | `get_logical_port_status` | Read | Realized state of all ports on a segment |\n| | `get_segment_port_for_vm` | Read | Find which segment a VM is connected to by display name |\n\nWrite tools require explicit parameters and are audit-logged. The five `delete_*` tools preview by default: without `confirm=True` they return `blast_radius` (what would be removed, `blockers`, `unmeasured`) and change nothing. Show it to the user and pass `confirm=True` only after they decide; it is refused while a blocker remains or a read failed. Other MCP write tools execute directly — call one only after the user has explicitly asked for that change.\n\n### List results are envelopes — read `truncated` before you summarise\n\nEvery list-returning tool above returns `{items, returned, limit, total, truncated, hint}`, not a bare array. Rows live under `items`: empty `items` with `truncated: false` means the query genuinely matched nothing — report that, not a tool failure. `truncated: true` means `items` is not the whole collection — never call it complete. It does **not** mean more rows can be fetched: it stays true on the last page. Page with `next_offset`, stopping when it is `null`; `hint` says which situation you are in. Field semantics, `total` sourcing, and an example payload: `references/capabilities.md`.\n\n## Local & Small Models\n\nRunning with local or small models? See [`references/agent-guardrails.md`](references/agent-guardrails.md) for explicit operating rules that keep tool calls reliable.\n\n## CLI Quick Reference\n\n```bash\n# Inventory (read-only)\nvmware-nsx inventory list-segments [--target ]\nvmware-nsx inventory get-segment \nvmware-nsx inventory list-tier0s\nvmware-nsx inventory get-tier0 \nvmware-nsx inventory list-tier1s\nvmware-nsx inventory get-tier1 \nvmware-nsx inventory list-transport-zones\nvmware-nsx inventory list-transport-nodes\nvmware-nsx inventory list-edge-clusters\n\n# Networking (read-only)\nvmware-nsx networking list-nat-rules \nvmware-nsx networking bgp-neighbors \nvmware-nsx networking list-static-routes \nvmware-nsx networking list-ip-pools\nvmware-nsx networking ip-pool-usage \n\n# Segment management (write; full option lists in references/cli-reference.md)\nvmware-nsx segment create --name --tz [--vlan|--subnet] [--dry-run]\nvmware-nsx segment update [--name|--subnet] [--dry-run]\nvmware-nsx segment delete [--dry-run]\n\n# Gateway management (write)\nvmware-nsx gateway create-tier1 --name [--tier0|--edge-cluster] [--dry-run]\nvmware-nsx gateway update-tier1 [--name|--tier0|--advertise] [--dry-run]\nvmware-nsx gateway delete-tier1 [--dry-run]\nvmware-nsx gateway configure-tier0-bgp --local-as [--ecmp] [--dry-run]\n\n# NAT (write)\nvmware-nsx nat create-rule --tier1 --rule-id --action SNAT --source --translated [--dry-run]\nvmware-nsx nat delete-rule --tier1 --rule-id [--dry-run]\n\n# Static routes (write)\nvmware-nsx route create-static --tier1 --route-id --network --next-hop [--dry-run]\nvmware-nsx route delete-static --tier1 --route-id [--dry-run]\n\n# IP pools (write)\nvmware-nsx ip-pool create --name --start --end --cidr [--dry-run]\n\n# Health & Troubleshooting (read-only)\nvmware-nsx health alarms [--severity CRITICAL]\nvmware-nsx health transport-node-status \nvmware-nsx health edge-cluster-status \nvmware-nsx health manager-status\nvmware-nsx troubleshoot port-status \nvmware-nsx troubleshoot vm-segment \n\n# Diagnostics\nvmware-nsx doctor [--skip-auth]\n```\n\n> Full CLI reference with all options and output formats: see `references/cli-reference.md`\n\n## Troubleshooting\n\n### \"Segment not found\" when querying\n\nSegment display names and Policy API IDs can differ. Use `vmware-nsx inventory list-segments` to get the exact ID. The Policy API uses the segment `id` field, not `display_name`. Common mistakes: using the display name with spaces instead of the hyphenated ID.\n\n### NAT rule creation fails with \"gateway not found\"\n\nNAT rules are created on Tier-1 gateways (or Tier-0 for some topologies). Verify the gateway name with `vmware-nsx inventory list-tier1s`. The gateway must have an edge cluster assigned for NAT to function.\n\n### BGP neighbor shows \"Connect\" or \"Active\" state\n\nThe BGP session is not established. Common causes:\n1. Peer IP unreachable from the edge node — check physical uplinks and VLAN config\n2. ASN mismatch — compare local and remote ASN in `bgp-neighbors` output\n3. Firewall blocking TCP 179 — check edge node firewall rules (not NSX DFW)\n4. MD5 password mismatch — verify authentication settings on both sides\n\n### Transport node status \"degraded\"\n\nA transport node in degraded state has partial connectivity. Steps:\n1. Check `vmware-nsx health transport-nodes` for the specific failure reason\n2. Common cause: tunnel endpoint (TEP) unreachable — verify underlay MTU (minimum 1600 for Geneve)\n3. Check NTP sync between NSX Manager and transport nodes\n4. If recently upgraded, verify the host switch config matches NSX Manager expectations\n\n### \"Password not found\" error\n\nThe password environment variable is missing. Variable names follow the pattern `VMWARE_NSX__PASSWORD` where hyphens become underscores. Example: target `nsx-prod` needs `VMWARE_NSX_NSX_PROD_PASSWORD`. Check your `~/.vmware-nsx/.env` file.\n\n## Safety\n\n- **Read-heavy**: 20 of 33 tools are read-only (list, get, status, health, troubleshoot)\n- **Audit logging**: All operations logged to `~/.vmware/audit.db` (SQLite WAL, via vmware-policy) with timestamp, user, target, operation, parameters, and result\n- **Double confirmation**: CLI write commands require two separate confirmation prompts before executing\n- **Dry-run mode**: All CLI write commands support `--dry-run` to preview API calls without executing (MCP deletes preview unless `confirm=True`; other MCP writes execute directly and are audit-logged)\n- **Dependency checks**: Segment delete refuses while ports are attached. Tier-1 delete first checks (read-only) for attached or Tier-1-scoped segments, NAT rules, static routes, service interfaces, extra locale-services, IPsec / L2 VPN services, a DNS forwarder and attached LB services; while any remain it refuses, deletes nothing and lists their ids (`--dry-run` runs the same check). Only a clean gateway has its default locale-service removed and is then deleted. IP pool delete (MCP) refuses while addresses are allocated\n- **Input validation**: resource IDs restricted to letters, digits, `-` and `_`; NAT action checked against the allowed set; required fields checked (translated address for SNAT/DNAT/REFLEXIVE, CIDR + ranges per IP-pool subnet). CIDR/IP syntax and gateway existence are not checked client-side — they are left to NSX Manager's own API validation\n- **Prompt injection defense**: NSX object names returned from the API are sanitized via `_sanitize()` — strips control characters, truncates to 500 chars\n- **Credential safety**: Passwords loaded only from environment variables (`.env` file), never from `config.yaml`\n- **No firewall operations**: Cannot create, modify, or delete DFW rules, security groups, or IDS/IPS policies — that scope belongs to `vmware-nsx-security`\n\n## Setup\n\n```bash\nuv tool install vmware-nsx-mgmt==1.11.0\nvmware-nsx init # writes ~/.vmware-nsx/config.yaml + .env (chmod 600), then verifies\nvmware-nsx doctor\n```\n\n> All tools are automatically audited via vmware-policy. Audit logs: `vmware-audit log --last 20`\n\n> Full setup guide with multi-target config, MCP server setup, and Docker: see `references/setup-guide.md`\n\n## Architecture\n\n```\nUser (natural language)\n |\nAI Agent (Claude Code / Goose / Cursor)\n | reads SKILL.md\nvmware-nsx CLI or MCP server (stdio transport)\n | NSX Policy API (REST/JSON over HTTPS)\nNSX Manager\n |\nSegments / Gateways / NAT / Routes / IP Pools / Transport Nodes\n```\n\n## Audit & Safety\n\nAll operations are automatically audited via vmware-policy (`@vmware_tool` decorator):\n- Every tool call logged to `~/.vmware/audit.db` (SQLite, framework-agnostic)\n- Policy rules enforced via `~/.vmware/rules.yaml` (deny rules, maintenance windows, risk levels)\n- Risk classification: each tool tagged as low/medium/high/critical\n- View recent operations: `vmware-audit log --last 20`\n- View denied operations: `vmware-audit log --status denied`\n\nvmware-policy is automatically installed as a dependency — no manual setup needed.\n\n## License\n\nMIT — [github.com/vmware-skills/VMware-NSX](https://github.com/vmware-skills/VMware-NSX)\n\nFile v1.11.0:_meta.json\n\n{\n \"ownerId\": \"kn7b067awq2s97bn3d7p5qfhw5827pxc\",\n \"slug\": \"vmware-nsx\",\n \"version\": \"1.11.0\",\n \"publishedAt\": 1789915924988\n}\n\nFile v1.11.0:references/agent-guardrails.md\n\n# Operating vmware-nsx with a local / small model\n\nClaude-class models drive this skill without special instruction. Smaller and\nlocally-hosted models — Llama 3.3 70B, Qwen, Mistral, and similar, served\nthrough Goose, Ollama, or OpenShift AI — need explicit operating rules to call\ntools reliably.\n\nThis page exists because an operator wrote those rules by hand first. The\nguardrails below are adapted, with thanks, from the working configuration\n[@juanpf-ha](https://github.com/juanpf-ha) developed while running\nvmware-monitor and vmware-aria against a production vSphere estate with Llama\n3.3 70B FP8 on an on-prem H100\n([VMware-AIops#31](https://github.com/vmware-skills/VMware-AIops/issues/31)). The\ncross-skill rules are identical across this family; the parts below marked\nvmware-nsx are specific to this skill.\n\nvmware-nsx exposes 33 MCP tools, 13 of which change state. Network writes fail\ndifferently from other writes: deleting a segment or reconfiguring a Tier-0's\nBGP does not error, it disconnects things — often something other than the\nobject the model was looking at.\n\n> **Disclaimer**: This is a community-maintained open-source project and is\n> **not affiliated with, endorsed by, or sponsored by VMware, Inc. or Broadcom\n> Inc.** \"VMware\" and \"vSphere\" are trademarks of Broadcom.\n\n---\n\n## First: the rules you no longer need to write\n\nSeveral guardrails from the original configuration are now enforced by the\nskill itself. Prompt instructions are advisory — a model can ignore them.\nThese are structural, so it cannot.\n\n| Guardrail you would otherwise prompt for | Now enforced by |\n|---|---|\n| \"Warn me if a segment still has workloads on it before deleting\" | **`delete_segment` checks the ports first** and refuses, deleting nothing, while any is attached (it names them). The check runs server-side, not in the prompt. |\n| \"Show me what a delete would remove before it happens\" | **The five delete tools preview by default.** Without `confirm=True` they return `blast_radius` and delete nothing; `confirm=True` is refused while a blocker remains or a read failed. |\n| \"Use explicit limits for queries that may return large amounts of data\" | **The list envelope.** Every list-returning tool returns `{items, returned, limit, total, truncated, hint}`, so the model reads truncation instead of guessing at it. `truncated: true` means `items` is not the whole collection; `next_offset` (null on the last page) is what a paging loop stops on, and the `hint` says which of the two you are looking at. |\n| \"If a listing came back empty, say so rather than claiming the call failed\" | Same envelope. Empty `items` with `truncated: false` means the query genuinely matched nothing — a stated result, not a silence the model has to interpret. |\n| \"Log every state change you make\" | **The `@vmware_tool` decorator.** Every write is recorded to `~/.vmware/audit.db` before the model sees the result, and policy rules are evaluated ahead of execution. |\n| \"Block state-changing writes against a production target\" | **Policy.** An opt-in environment-scoped `deny` rule in `~/.vmware/rules.yaml` matches a target's `environment:` label and refuses matching writes before execution. |\n\n---\n\n## The system prompt\n\nEverything below still benefits from being stated explicitly. Copy this into\nyour agent's instruction block.\n\n```text\n## Tool use\n\n- Always call an MCP tool before answering any question about the current NSX\n environment. Never answer from memory or assumption.\n- Never describe a tool call, and never output a JSON example, instead of\n executing the tool. If you intend to call a tool, call it.\n- If a tool fails, report the actual error text. Do not complete the answer\n with assumptions about what the result would have been.\n- Use explicit limits on queries that may return large amounts of data. Do not\n request unlimited results unless the user asks for them.\n- Every tool accepts an optional target. When more than one NSX Manager is\n configured, name the target explicitly rather than relying on the default.\n\n## Skill routing\n\n- vmware-nsx: segments, Tier-0 and Tier-1 gateways, BGP, NAT, static routes,\n IP pools, transport zones and nodes, edge clusters, NSX alarms.\n- vmware-nsx-security: DFW policies and rules, security groups, VM tags,\n IDS/IPS, Traceflow. Firewall work is not this skill.\n- vmware-monitor: read-only vCenter inventory, hosts, alarms, events.\n- vmware-aiops: VM lifecycle.\n- vmware-avi: load balancing, virtual services, pools, AKO.\n- vmware-pilot: multi-step workflows that need approval gates.\n\n## Data fidelity\n\n- Never invent segments, gateways, routes, pools, IP addresses or ASNs. If a\n tool did not return it, it does not exist for this answer.\n- Preserve the exact admin state, realization state, BGP session state and\n status values the tools return. Do not translate, normalise, or prettify\n enum values.\n- Report IP addresses, prefixes and ASNs exactly as returned. Never reformat,\n abbreviate or infer a subnet mask.\n- If a requested field was not returned, show it as \"not available\". Do not\n infer it from other fields.\n- Preserve the original order and the full set of fields when the user asks\n for specific ones.\n- When a response is long, report every item it contains. If a result is\n truncated, the tool says so explicitly — report the truncation rather than\n describing the visible subset as the whole.\n\n## Analysis discipline\n\n- Separate observed data from interpretation. State which is which.\n- Do not claim a connectivity, routing or capacity problem unless the tool\n output contains explicit supporting evidence. A BGP session in Connect state\n is an observation; the cause of it is not.\n- Avoid generic recommendations that are not directly supported by the results.\n\n## Identifiers and writes in vmware-nsx\n\n- A segment's display name and its Policy API id are different strings. Resolve\n the id with list_segments before acting on a segment; never derive one from\n the other.\n- NAT rules and static routes live on a gateway. Confirm the gateway with\n list_tier1_gateways before creating a rule on it.\n- Before proposing delete_segment, call get_segment and report the connected\n port count. delete_segment refuses while ports are attached, so name what\n must be detached first rather than retrying.\n- Call a delete_* tool without confirm first and show the user its\n blast_radius. Pass confirm=True only after the user has seen it and said\n yes — an earlier \"delete it\" was said before they saw what it removes.\n- configure_tier0_bgp changes routing for everything behind that Tier-0. Treat\n it as estate-wide, not object-scoped, and say so.\n```\n\n---\n\n## Known failure modes on small models\n\nObserved with Llama 3.3 70B FP8 (Goose, on-prem H100), and useful as a\nchecklist when evaluating any local model against these skills:\n\n| Symptom | Mitigation |\n|---|---|\n| Describes a tool call, or emits a JSON example, instead of executing it | The \"never describe a tool call\" rule above. Also check your harness is not echoing tool schemas into context — models imitate the nearest format they see. |\n| Long tool responses: omits items, or reports \"no data returned\" when data was present | Ask for explicit limits so responses stay small. Check the envelope's `truncated` / `returned` / `total` fields rather than trusting the model's summary — a \"no data\" claim is checkable against `returned`. |\n| Adds generic recommendations unsupported by results | The \"analysis discipline\" rules. BGP and MTU output attract invented advice more than most — hold it to the evidence. |\n| Drops requested fields or reorders results | State the required fields and ordering in the request itself, not only in the system prompt. |\n| Multi-tool workflows take 30–50s end to end | Prefer the tools that answer a whole question in one call: `get_segment_port_for_vm` finds a VM's segment directly, `get_ip_pool_usage` gives allocation without enumerating pools, and `get_nsx_manager_status` covers cluster health in one round trip. |\n| Uses a segment's display name where the Policy API id is required | The identifier rule above. The failure reads as \"segment not found\", which a model tends to interpret as a missing object rather than a wrong key. |\n| Invents or reformats an IP address, prefix length or ASN | The \"report exactly as returned\" rule. In this skill a plausible-looking wrong prefix is worse than no answer. |\n| Proposes a deletion without checking what is attached | Require a `get_segment` port count first. The tool warns, but the model should have looked before it asked. |\n| Silently falls back to the default target in a multi-manager estate | Name the target in the request. |\n\n## Reporting results\n\nLocal-model compatibility is an explicit design constraint for this family, and\nthe evidence base is small. If you evaluate a model against this skill —\nQwen, Mistral, Granite, or anything else — a report of what worked and what did\nnot is genuinely useful:\n[github.com/vmware-skills/VMware-NSX/issues](https://github.com/vmware-skills/VMware-NSX/issues).\n\nFile v1.11.0:references/capabilities.md\n\n# Capabilities\n\nDetailed capability reference for `vmware-nsx`.\n\n## Automation Level Reference\n\nEach operation is classified by autonomy level per the Enterprise Harness Engineering framework:\n\n| Level | Meaning | Agent autonomy | Examples in this skill |\n|:-:|---|---|---|\n| **L1** | Read-only, raw data | Always auto-run | `list_segments`, `get_segment`, `list_tier0_gateways`, `list_tier1_gateways`, `list_nat_rules`, `list_ip_pools`, `list_static_routes`, alarms/health queries |\n| **L2** | Read + analysis / recommendation | Always auto-run | `get_bgp_neighbors`, `get_segment_port_for_vm`, `get_ip_pool_usage`, `get_logical_port_status` — correlation and utilization summaries over raw data |\n| **L3** | Single write — user must approve | Only when the user explicitly asked for that change; CLI adds double-confirm + optional `--dry-run`; the five MCP deletes preview by default and act only with `confirm=True`; segment delete refuses while ports are attached; Tier-1 delete refuses while anything still depends on the gateway; IP pool delete refuses while addresses are allocated | `create_segment`, `delete_segment`, `create_nat_rule`, `update_tier1_gateway`, `create_ip_pool`, `configure_tier0_bgp`, static route mutations |\n| **L4** | Multi-step plan / apply workflow | Plan generation auto; apply gated by user approval | *(roadmap — multi-segment rollout plans, gateway HA failover sequences)* |\n| **L5** | Auto-remediation from learned pattern | Pattern library only; requires `risk:low` + `reversible:true` + `repeatable:true` | *(roadmap — candidates: stale segment cleanup, transport-node refresh)* |\n\n**Notes**:\n- L1/L2 tools are always safe for agents to call without confirmation.\n- L3 tools always pass through the `@vmware_tool` decorator: policy check (`~/.vmware/rules.yaml` deny rules, per environment) → execute → audit log. The CLI's double-confirm and `--dry-run` do not apply to MCP calls.\n- **MCP deletes preview by default** (`delete_segment`, `delete_tier1_gateway`, `delete_nat_rule`, `delete_static_route`, `delete_ip_pool`). A call without `confirm=True` reads what the delete would remove and returns `{\"action\": \"preview\", \"blast_radius\": {...}}`, deleting nothing. `blast_radius` names the object and what it measured — a segment's gateway, subnets, `port_count`/`port_ids`; a Tier-1's `tier0_path`, the `default` locale-service and edge cluster it removes, and its `dependents` by kind; a NAT rule's gateway, action, match and translation; a route's gateway, network and next hops; a pool's `pool_usage`, `allocation_count` (Policy ip-allocations), `realized_allocation_count` (NSX's `pool_usage.allocated_ip_allocations`, which also counts addresses Policy does not list, e.g. TEP pools) and `allocated_ips` — plus `blockers` and `unmeasured`. `confirm=True` re-measures and is refused, deleting nothing, while a blocker remains (attached ports, any Tier-1 dependent, allocated IPs) or while any of those reads failed (`unmeasured` non-empty); the refusal is `{\"error\", \"hint\", \"blast_radius\"}`. Show the preview to the user; set `confirm=True` only after they decide — not because they asked for the delete before seeing it. The preview is logged to the skill audit log as `preview`, not `ok`.\n- For DFW/security rules see [vmware-nsx-security](https://github.com/vmware-skills/VMware-NSX-Security).\n\n## API Coverage\n\nvmware-nsx uses the **NSX Policy API** (not the Management API) for all operations. The Policy API provides a declarative, intent-based interface that is the recommended path for NSX-T 3.x and NSX 4.x.\n\n### Policy API vs Management API\n\n| Aspect | Policy API (used by this skill) | Management API (not used) |\n|--------|--------------------------------|--------------------------|\n| Endpoint prefix | `/policy/api/v1/` | `/api/v1/` |\n| Model | Declarative, intent-based | Imperative, realized-state |\n| Object IDs | User-defined string IDs | System-generated UUIDs |\n| Hierarchy | Infra → Tier-0 → Tier-1 → Segment | Flat namespace |\n| Transaction support | Hierarchical API (PATCH entire tree) | Individual API calls |\n| Recommended by VMware | Yes (primary API since NSX-T 3.0) | Deprecated for new development |\n\n**Why Policy API?** The Policy API allows setting desired state declaratively. NSX Manager reconciles realized state automatically. This is safer for automation — you describe what you want, NSX figures out how to get there.\n\n## Tool Capabilities by Category\n\nThe tables below list **every** MCP tool this skill exposes — 33 total (20 read, 13 write).\nTool names are exactly as registered on the MCP server; endpoints and methods are taken\nfrom the corresponding `vmware_nsx/ops/` implementation. Anything not listed here does\nnot exist.\n\nClassification follows each tool's `[READ]`/`[WRITE]` docstring marker; see README.\n\n### Segments (5 tools — 2 read, 3 write)\n\n| Capability | Tool | API Endpoint | Method |\n|------------|------|-------------|--------|\n| List all segments | `list_segments` | `/policy/api/v1/infra/segments` | GET |\n| Get segment details (includes its ports) | `get_segment` | `/policy/api/v1/infra/segments/{id}` + `/ports` | GET |\n| Create segment | `create_segment` | `/policy/api/v1/infra/segments/{id}` | PUT |\n| Update segment | `update_segment` | `/policy/api/v1/infra/segments/{id}` | PATCH |\n| Delete segment | `delete_segment` | Pre-check (GET): `/policy/api/v1/infra/segments/{id}` (identity, gateway, subnets) and `/policy/api/v1/infra/segments/{id}/ports` — refuses, listing port ids, while any is attached. Then `/policy/api/v1/infra/segments/{id}` | GET, DELETE |\n\n**Note**: there is no standalone segment-port listing tool. Ports are returned by\n`get_segment` (attached ports + total count) and, with realized state, by\n`get_logical_port_status`.\n\n**Segment types supported**:\n- Overlay segments (Geneve encapsulation, requires overlay transport zone)\n- VLAN-backed segments (requires VLAN transport zone + VLAN ID)\n\n**Segment features**:\n- Subnet configuration (gateway CIDR)\n- DHCP configuration (static bindings, relay)\n- Connectivity to Tier-1 gateways\n- Tags and metadata\n- Admin state management\n\n### Tier-0 Gateways (4 tools — 3 read, 1 write)\n\n| Capability | Tool | API Endpoint | Method |\n|------------|------|-------------|--------|\n| List Tier-0 gateways | `list_tier0_gateways` | `/policy/api/v1/infra/tier-0s` | GET |\n| Get Tier-0 details | `get_tier0_gateway` | `/policy/api/v1/infra/tier-0s/{id}` | GET |\n| BGP config + neighbor status | `get_bgp_neighbors` | `/policy/api/v1/infra/tier-0s/{id}/locale-services`, then `.../{ls}/bgp`, `.../{ls}/bgp/neighbors`, `.../{ls}/bgp/neighbors/status` | GET |\n| Configure BGP on a Tier-0 | `configure_tier0_bgp` | `/policy/api/v1/infra/tier-0s/{id}/locale-services/{ls}/bgp` | PATCH |\n\n**Note**: Tier-0 gateways cannot be created or deleted by this skill — that is a high-impact\ninfrastructure operation normally done during initial NSX deployment. The only Tier-0 write\ntool is `configure_tier0_bgp` (local AS, ECMP, inter-SR iBGP on an existing locale-service).\nThere is **no** Tier-0 or Tier-1 route-table tool; use `list_static_routes` for configured\nstatic routes and `get_bgp_neighbors` for learned-route peering state.\n\n### Tier-1 Gateways (5 tools — 2 read, 3 write)\n\n| Capability | Tool | API Endpoint | Method |\n|------------|------|-------------|--------|\n| List Tier-1 gateways | `list_tier1_gateways` | `/policy/api/v1/infra/tier-1s` | GET |\n| Get Tier-1 details | `get_tier1_gateway` | `/policy/api/v1/infra/tier-1s/{id}` | GET |\n| Create Tier-1 | `create_tier1_gateway` | `/policy/api/v1/infra/tier-1s/{id}`, plus `.../locale-services/default` when an edge cluster is given | PUT |\n| Update Tier-1 | `update_tier1_gateway` | `/policy/api/v1/infra/tier-1s/{id}` | PATCH |\n| Delete Tier-1 | `delete_tier1_gateway` | Pre-check (GET) of `/policy/api/v1/infra/tier-1s/{id}` (identity) — refuses, listing ids, if any remain: `/policy/api/v1/infra/segments` and `/policy/api/v1/infra/lb-services` (by `connectivity_path`); under `.../tier-1s/{id}/`: `segments`, `nat/USER/nat-rules`, `static-routes`, `locale-services` (any but `default`), `locale-services/default/interfaces`, `ipsec-vpn-services`, `l2vpn-services`, `dns-forwarder`. A 404 means none; any other read error aborts without deleting. Then `.../locale-services/default` (best effort), then `/policy/api/v1/infra/tier-1s/{id}` | GET, DELETE |\n\n**Route advertisement types**:\n- `TIER1_CONNECTED` — Connected subnets\n- `TIER1_NAT` — NAT IP addresses\n- `TIER1_STATIC_ROUTES` — Static routes\n- `TIER1_LB_VIP` — Load balancer VIPs\n- `TIER1_LB_SNAT` — Load balancer SNAT IPs\n- `TIER1_DNS_FORWARDER_IP` — DNS forwarder IPs\n- `TIER1_IPSEC_LOCAL_ENDPOINT` — IPSec local endpoints\n\n### NAT (3 tools — 1 read, 2 write)\n\n| Capability | Tool | API Endpoint | Method |\n|------------|------|-------------|--------|\n| List NAT rules | `list_nat_rules` | `/policy/api/v1/infra/tier-1s/{id}/nat/USER/nat-rules` | GET |\n| Create NAT rule | `create_nat_rule` | `/policy/api/v1/infra/tier-1s/{id}/nat/USER/nat-rules/{rule}` | PUT |\n| Delete NAT rule | `delete_nat_rule` | Blast radius (GET): walks `/policy/api/v1/infra/tier-1s/{id}/nat/USER/nat-rules` for the rule. Then `/policy/api/v1/infra/tier-1s/{id}/nat/USER/nat-rules/{rule}` | GET, DELETE |\n\n**No get/update NAT tool**: read a single rule by listing the gateway's rules and filtering\nclient-side; change a rule by re-issuing `create_nat_rule` with the same `rule_id` (the\nPolicy API PUT is an idempotent upsert).\n\n**NAT action types**:\n- `SNAT` — Source NAT (outbound traffic)\n- `DNAT` — Destination NAT (inbound traffic)\n- `REFLEXIVE` — Stateless bidirectional NAT\n- `NO_SNAT` — Exempt from SNAT\n- `NO_DNAT` — Exempt from DNAT\n\n**Tier-1 only**: the NAT tools address `/tier-1s/` exclusively — the gateway id parameter is\n`tier1_id` and the path is not switched by gateway type. Tier-0 NAT is not reachable through\nthis skill.\n\n### Static Routes (3 tools — 1 read, 2 write)\n\n| Capability | Tool | API Endpoint | Method |\n|------------|------|-------------|--------|\n| List static routes | `list_static_routes` | `/policy/api/v1/infra/tier-{0,1}s/{id}/static-routes` | GET |\n| Create static route | `create_static_route` | `/policy/api/v1/infra/tier-{0,1}s/{id}/static-routes/{route}` | PUT |\n| Delete static route | `delete_static_route` | Blast radius (GET): walks `/policy/api/v1/infra/tier-{0,1}s/{id}/static-routes` for the route. Then `/policy/api/v1/infra/tier-{0,1}s/{id}/static-routes/{route}` | GET, DELETE |\n\nUnlike NAT, these three do select `tier-0s` or `tier-1s` from the gateway type argument.\n\n### IP Pools (4 tools — 2 read, 2 write)\n\n| Capability | Tool | API Endpoint | Method |\n|------------|------|-------------|--------|\n| List pools | `list_ip_pools` | `/policy/api/v1/infra/ip-pools` | GET |\n| Get allocations for one pool | `get_ip_pool_usage` | `/policy/api/v1/infra/ip-pools/{id}/ip-allocations` | GET |\n| Create pool (with one static subnet) | `create_ip_pool` | `/policy/api/v1/infra/ip-pools/{id}`, then `.../ip-subnets/{subnet}` | PUT |\n| Delete pool | `delete_ip_pool` | Blast radius (GET): walks `/policy/api/v1/infra/ip-pools` for the pool, then `/policy/api/v1/infra/ip-pools/{id}/ip-allocations` — refuses, listing addresses, while any is allocated; also refuses while the pool's `pool_usage.allocated_ip_allocations` is above zero or unreadable. Then `/policy/api/v1/infra/ip-pools/{id}` | GET, DELETE |\n\n**Note**: subnet creation is not a separate tool — `create_ip_pool` writes the pool and its\none static subnet + allocation range in a single call. It is two PUTs, not atomic: if the\nsubnet PUT fails, the pool exists without it and the call returns a top-level `error` saying\nso (audited as a failure), with the cleanup — `delete_ip_pool`, then create again.\n\n**IP pool use cases**:\n- TEP (Tunnel Endpoint) IP assignment\n- SNAT IP pool for gateways\n- Load balancer VIP pools\n- Custom automation IP management\n\n### Fabric Inventory (3 tools — 3 read, 0 write)\n\n| Capability | Tool | API Endpoint | Method |\n|------------|------|-------------|--------|\n| List transport zones | `list_transport_zones` | `/policy/api/v1/infra/sites/default/enforcement-points/default/transport-zones` | GET |\n| List transport nodes | `list_transport_nodes` | `/api/v1/transport-nodes` | GET |\n| List edge clusters | `list_edge_clusters` | `/api/v1/edge-clusters` | GET |\n\n### Health (4 tools — 4 read, 0 write)\n\n| Capability | Tool | API Endpoint | Method |\n|------------|------|-------------|--------|\n| NSX alarms at one severity | `list_nsx_alarms` | `/api/v1/alarms` | GET |\n| Transport node status | `get_transport_node_status` | `/api/v1/transport-nodes/{id}/status` | GET |\n| Edge cluster status | `get_edge_cluster_status` | `/api/v1/edge-clusters/{id}/status` | GET |\n| Manager cluster status | `get_nsx_manager_status` | `/api/v1/cluster/status` | GET |\n\n### Troubleshooting (2 tools — 2 read, 0 write)\n\n| Capability | Tool | API Endpoint | Method |\n|------------|------|-------------|--------|\n| Realized state of all ports on a segment | `get_logical_port_status` | `/policy/api/v1/infra/segments/{id}` + `/ports`, then `/ports/{port}/state` per port | GET |\n| VM-to-segment lookup by display name | `get_segment_port_for_vm` | `/api/v1/fabric/virtual-machines`, `/api/v1/fabric/vifs`, then `/policy/api/v1/search/query` (falls back to scanning `/policy/api/v1/infra/segments/{id}/ports`) | GET |\n\n**Note**: Health and troubleshooting tools use a mix of Policy API and Management API endpoints. The Management API is used where the Policy API does not yet expose equivalent realized-state or status information (alarms, transport node status, fabric VM/VIF discovery).\n\n### Tool Count Summary\n\n| Category | Tools | Read | Write |\n|----------|:-----:|:----:|:-----:|\n| Segments | 5 | 2 | 3 |\n| Tier-0 Gateways | 4 | 3 | 1 |\n| Tier-1 Gateways | 5 | 2 | 3 |\n| NAT | 3 | 1 | 2 |\n| Static Routes | 3 | 1 | 2 |\n| IP Pools | 4 | 2 | 2 |\n| Fabric Inventory | 3 | 3 | 0 |\n| Health | 4 | 4 | 0 |\n| Troubleshooting | 2 | 2 | 0 |\n| **Total** | **33** | **20** | **13** |\n\n## NSX Version Compatibility\n\n| NSX Version | Support Level | Notes |\n|-------------|--------------|-------|\n| NSX 9.1 | Full | Policy API supported. Note: VDS 7.0+ required (N-VDS removed in NSX 9). |\n| NSX 9.0 | Full | Policy API supported. Note: bare-metal agent / physical-server L2 overlay removed. |\n| NSX 4.2.x | Full | Latest, all features supported |\n| NSX 4.1.x | Full | All features supported |\n| NSX 4.0.x | Full | Policy API v1 fully available |\n| NSX-T 3.2.x | Full | Policy API mature, all features work |\n| NSX-T 3.1.x | Full | Minor differences in route table API response format |\n| NSX-T 3.0.x | Compatible | IP pool subnet API introduced here; older formats handled |\n| NSX-T 2.5.x | Limited | Policy API available but incomplete; some tools may fail |\n| NSX-V (6.x) | Not supported | Completely different API (SOAP-based). Use legacy tools |\n\n### VCF (VMware Cloud Foundation) Compatibility\n\n| VCF Version | Bundled NSX | Support |\n|-------------|-------------|---------|\n| VCF 9.1 | NSX 9.1 | Full |\n| VCF 9.0 | NSX 9.0 | Full |\n| VCF 5.2 | NSX 4.2.x | Full |\n| VCF 5.1 | NSX 4.1.x | Full |\n| VCF 5.0 | NSX 4.0.x | Full |\n| VCF 4.5 | NSX-T 3.2.x | Full |\n| VCF 4.4 | NSX-T 3.2.x | Full |\n| VCF 4.3 | NSX-T 3.1.x | Full |\n\n## Scope Boundaries\n\n### What This Skill Does\n\n- Network infrastructure: segments, gateways, routing, NAT, IPAM\n- Network health: alarms, transport nodes, edge clusters, manager status\n- Network troubleshooting: port status, VM-to-segment mapping\n\n### What This Skill Does NOT Do\n\n| Capability | Responsible Skill |\n|------------|-------------------|\n| Distributed Firewall (DFW) rules | `vmware-nsx-security` |\n| Security groups and policies | `vmware-nsx-security` |\n| IDS/IPS configuration | `vmware-nsx-security` |\n| URL filtering | `vmware-nsx-security` |\n| Service insertion / east-west security | `vmware-nsx-security` |\n| VM lifecycle (power, deploy, guest ops) | `vmware-aiops` |\n| vSphere inventory and health | `vmware-monitor` |\n| Storage (datastores, iSCSI, vSAN) | `vmware-storage` |\n| Tanzu Kubernetes | `vmware-vks` |\n| Load balancing | Future skill or NSX ALB |\n| VPN (IPSec / L2VPN) | Future skill |\n| NSX Intelligence / Network Detection and Response | Future skill |\n\n## Rate Limiting and Pagination\n\n- NSX Policy API supports pagination via `cursor` and `page_size` parameters\n- Default page size: 1000 objects (configurable)\n- List operations automatically paginate through all results\n- NSX Manager has built-in rate limiting; the skill respects `429 Too Many Requests` responses with automatic backoff\n- Recommendation: for environments with >500 segments or >200 gateways, use targeted `get` operations instead of `list`\n\n### List Result Envelope\n\nEvery list-returning tool wraps its rows in the family envelope\n(`vmware_policy.paginated`) rather than returning a bare array, so an agent can\ntell a complete answer from page one instead of guessing (VMware-AIops issue\n#31). Keys: `items`, `returned`, `limit`, `total`, `truncated`, `hint` — always\nall six, with explicit `null` where a value is unknown — plus the `next_offset`\nextra. Example payload:\n\n```json\n{\n \"items\": [ ... ],\n \"returned\": 50,\n \"limit\": 50,\n \"total\": 412,\n \"truncated\": true,\n \"next_offset\": 50,\n \"hint\": \"Showing rows 0-49 of 412. Continue at offset 50 for the next page, or narrow the query with a filter.\"\n}\n```\n\n`next_offset` is the stop signal, and `truncated` is not. `truncated` answers\n\"is `items` the whole collection?\", which is still `true` on the last page of a\nwalk — rows 400-411 of 412 are not 412 rows. A loop driven by `truncated` never\nterminates; a loop driven by `next_offset is null` ends on the last page.\n\n`hint` is written for that same distinction. Mid-walk it names the offset to\npass back; on the last page it says there is no next page, and on a page past\nthe end it says the offset is past the end and to start again at 0. It never\ntells you to raise a limit that cannot return another row.\n\n`total` is the collection's `result_count` from the NSX ListResult. It is read\nfrom the pages `get_all` already fetched (via `CollectionTotal`), so it costs no\nextra round trip, and it stays `null` — never inferred — when the API omits the\nfield.\n\n| Tool | Bound | `total` source |\n|------|-------|---------------|\n| `list_segments` | `limit` (default 50) | `result_count` on `/policy/api/v1/infra/segments` |\n| `list_tier0_gateways` | `limit` (default 50) | `result_count` on `/policy/api/v1/infra/tier-0s` |\n| `list_tier1_gateways` | `limit` (default 50) | `result_count` on `/policy/api/v1/infra/tier-1s` |\n| `list_transport_zones` | `limit` (default 50) | `result_count` on the enforcement-point transport-zones path |\n| `list_transport_nodes` | `limit` (default 50) | `result_count` on `/api/v1/transport-nodes` |\n| `list_edge_clusters` | `limit` (default 50) | `result_count` on `/api/v1/edge-clusters` |\n| `list_nat_rules` | `limit` (default 50) | `result_count` on the Tier-1's `/nat/USER/nat-rules` |\n| `list_static_routes` | `limit` (default 50) | `result_count` on the gateway's `/static-routes` |\n| `list_ip_pools` | `limit` (default 50) | `result_count` on `/policy/api/v1/infra/ip-pools` |\n| `list_nsx_alarms` | none — every alarm at the severity | `result_count` on `/api/v1/alarms`; exceeds `returned` only when the 1000-item client backstop cut the walk short |\n\nBecause `total` is normally present, a page filled exactly to the limit is\nrecognised as complete when it matches the collection size, rather than being\nconservatively flagged truncated. When `total` is `null` (older APIs that omit\n`result_count`), a page filled exactly to the limit is conservatively flagged\ntruncated and may in fact be complete. CLI commands unwrap `items` and print\nthe rows; the envelope is the MCP/library contract.\n\n## Authentication\n\nThe skill authenticates to NSX Manager using HTTP Basic Authentication over HTTPS. This is the standard authentication method for the NSX Policy API.\n\n**Supported authentication methods**:\n- Local NSX Manager credentials (admin user)\n- vIDM-backed credentials (when NSX Manager is integrated with Identity Manager)\n- Principal Identity certificates (configure `cert_path` and `key_path` in config.yaml instead of password)\n\n**Session management**: Each API call creates an independent HTTPS request with Basic Auth headers. No persistent sessions are maintained, which simplifies connection pooling and avoids session timeout issues.\n\nFile v1.11.0:references/cli-reference.md\n\n# CLI Reference\n\nComplete command reference for the `vmware-nsx` CLI. Command groups:\n`inventory`, `networking`, `health`, `troubleshoot` (read-only) and\n`segment`, `gateway`, `nat`, `route`, `ip-pool` (write), plus `doctor`,\n`mcp`, and `mcp-config`.\n\n## Global Options\n\nAll commands accept these options:\n\n| Option | Description |\n|--------|-------------|\n| `--target`, `-t ` | Target name from `~/.vmware-nsx/config.yaml` (defaults to the configured default target) |\n| `--config`, `-c ` | Override config file path |\n| `--help` | Show command help |\n\nWrite commands additionally accept:\n\n| Option | Description |\n|--------|-------------|\n| `--dry-run` | Print the API call that would be made without executing it |\n\n**Error handling**: operational failures (connection refused, HTTP 4xx/5xx\nfrom NSX Manager, missing config) print a single red `Error: ...` line with\na remediation hint and exit with code 1 — no Python traceback.\n\n---\n\n## Inventory Commands (read-only)\n\n### `inventory list-segments`\n\nList all network segments with type, subnet, admin state, and port count.\n\n```bash\nvmware-nsx inventory list-segments\nvmware-nsx inventory list-segments --target nsx-prod\n```\n\n### `inventory get-segment`\n\nGet detailed info for a specific segment.\n\n```bash\nvmware-nsx inventory get-segment app-web-seg\n```\n\n| Argument | Required | Description |\n|----------|:--------:|-------------|\n| `segment_id` | Yes | Segment ID (Policy API ID, not display name) |\n\n### `inventory list-tier0s`\n\nList all Tier-0 gateways with HA mode and transit subnets.\n\n```bash\nvmware-nsx inventory list-tier0s\n```\n\n### `inventory get-tier0`\n\nGet detailed info for a Tier-0 gateway.\n\n```bash\nvmware-nsx inventory get-tier0 tier0-gw\n```\n\n### `inventory list-tier1s`\n\nList all Tier-1 gateways with linked Tier-0 path and route advertisement.\n\n```bash\nvmware-nsx inventory list-tier1s\n```\n\n### `inventory get-tier1`\n\nGet detailed info for a Tier-1 gateway.\n\n```bash\nvmware-nsx inventory get-tier1 app-t1\n```\n\n### `inventory list-transport-zones`\n\nList all transport zones with type (OVERLAY / VLAN).\n\n```bash\nvmware-nsx inventory list-transport-zones\n```\n\n### `inventory list-transport-nodes`\n\nList all transport nodes with node type and status.\n\n```bash\nvmware-nsx inventory list-transport-nodes\n```\n\n### `inventory list-edge-clusters`\n\nList all edge clusters with member count and deployment type.\n\n```bash\nvmware-nsx inventory list-edge-clusters\n```\n\n---\n\n## Networking Commands (read-only)\n\n### `networking list-nat-rules`\n\nList NAT rules on a Tier-1 gateway.\n\n```bash\nvmware-nsx networking list-nat-rules app-t1\n```\n\n| Argument | Required | Description |\n|----------|:--------:|-------------|\n| `tier1_id` | Yes | Tier-1 gateway ID |\n\n### `networking bgp-neighbors`\n\nShow BGP neighbors for a Tier-0 gateway, including realized session state,\nremote ASN, hold/keep-alive timers, and prefix counts.\n\n```bash\nvmware-nsx networking bgp-neighbors tier0-gw\n```\n\n| Argument | Required | Description |\n|----------|:--------:|-------------|\n| `tier0_id` | Yes | Tier-0 gateway ID |\n\n### `networking list-static-routes`\n\nList static routes on a Tier-1 gateway.\n\n```bash\nvmware-nsx networking list-static-routes app-t1\n```\n\n### `networking list-ip-pools`\n\nList all IP address pools with usage summary.\n\n```bash\nvmware-nsx networking list-ip-pools\n```\n\n### `networking ip-pool-usage`\n\nShow IP pool allocation usage.\n\n```bash\nvmware-nsx networking ip-pool-usage pool-01\n```\n\n| Argument | Required | Description |\n|----------|:--------:|-------------|\n| `pool_id` | Yes | IP pool ID |\n\n---\n\n## Health Commands (read-only)\n\n### `health alarms`\n\nShow active NSX alarms at one severity (exact match, not \"and above\").\n\n```bash\nvmware-nsx health alarms\nvmware-nsx health alarms --severity CRITICAL\n```\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `--severity` | `MEDIUM` | Exact severity filter: LOW, MEDIUM, HIGH, CRITICAL |\n\n### `health transport-node-status`\n\nCheck status of a specific transport node.\n\n```bash\nvmware-nsx health transport-node-status \n```\n\n### `health edge-cluster-status`\n\nCheck status of an edge cluster.\n\n```bash\nvmware-nsx health edge-cluster-status \n```\n\n### `health manager-status`\n\nShow NSX Manager cluster status.\n\n```bash\nvmware-nsx health manager-status\n```\n\n---\n\n## Troubleshoot Commands (read-only)\n\n### `troubleshoot port-status`\n\nCheck realized state of all ports on a segment.\n\n```bash\nvmware-nsx troubleshoot port-status app-web-seg\n```\n\n| Argument | Required | Description |\n|----------|:--------:|-------------|\n| `segment_id` | Yes | Segment ID |\n\n### `troubleshoot vm-segment`\n\nFind which segment a VM is attached to (lookup by display name).\n\n```bash\nvmware-nsx troubleshoot vm-segment my-vm-01\n```\n\n| Argument | Required | Description |\n|----------|:--------:|-------------|\n| `vm_display_name` | Yes | VM display name as shown in vSphere |\n\n---\n\n## Segment Management (write)\n\nAll write commands require **double confirmation** and support `--dry-run`.\n\n### `segment create`\n\nCreate a new overlay or VLAN-backed segment.\n\n```bash\nvmware-nsx segment create app-web-seg --name \"App Web\" --tz --subnet 10.10.1.1/24\n\n# VLAN-backed; --vlan accepts single IDs, lists, and ranges\nvmware-nsx segment create vlan-seg --name \"VLAN seg\" --tz --vlan '100-200' --dry-run\n```\n\n| Argument/Option | Required | Description |\n|-----------------|:--------:|-------------|\n| `segment_id` | Yes | Segment ID |\n| `--name` | Yes | Display name |\n| `--tz` | Yes | Transport zone path |\n| `--vlan` | No | VLAN ID(s): `'100'`, `'100,200'`, or range `'100-200'` (ranges are passed to NSX as range strings, not expanded) |\n| `--subnet` | No | Gateway CIDR, e.g. `192.168.1.1/24` |\n| `--dry-run` | No | Preview without executing |\n\n### `segment update`\n\nUpdate an existing segment's display name and/or subnet.\n\n```bash\nvmware-nsx segment update app-web-seg --name \"New Name\"\nvmware-nsx segment update app-web-seg --subnet 10.10.2.1/24 --dry-run\n```\n\n| Option | Description |\n|--------|-------------|\n| `--name` | New display name |\n| `--subnet` | New gateway CIDR |\n\n### `segment delete`\n\nDelete a segment (destructive). Refuses — exit code 1, nothing deleted,\nattached port ids printed — while any port is attached. `--dry-run` runs the\nsame read-only port check and shows whether a real run would be refused.\n\n```bash\nvmware-nsx segment delete app-web-seg --dry-run\nvmware-nsx segment delete app-web-seg\n```\n\n---\n\n## Gateway Management (write)\n\n### `gateway create-tier1`\n\nCreate a new Tier-1 gateway.\n\n```bash\nvmware-nsx gateway create-tier1 app-t1 --name \"App T1\" --tier0 /infra/tier-0s/tier0-gw --edge-cluster \n```\n\n| Argument/Option | Required | Description |\n|-----------------|:--------:|-------------|\n| `tier1_id` | Yes | Tier-1 gateway ID |\n| `--name` | Yes | Display name |\n| `--tier0` | No | Tier-0 gateway path to link |\n| `--edge-cluster` | No | Edge cluster path |\n| `--advertise` | No | Route advertisement types, comma-separated (e.g. `TIER1_CONNECTED,TIER1_NAT`) |\n\n### `gateway update-tier1`\n\nUpdate an existing Tier-1 gateway.\n\n```bash\nvmware-nsx gateway update-tier1 app-t1 --advertise TIER1_CONNECTED,TIER1_NAT\n```\n\n| Option | Description |\n|--------|-------------|\n| `--name` | New display name |\n| `--tier0` | New Tier-0 path |\n| `--advertise` | Route advertisement types |\n\n### `gateway delete-tier1`\n\nDelete a Tier-1 gateway (destructive). Checks first and refuses — exit code 1,\nnothing deleted, blocking ids printed — while segments, NAT rules, static\nroutes, service interfaces, extra locale-services, or VPN / DNS forwarder / LB\nservices still depend on it. `--dry-run` runs the same read-only check and\nshows what blocks. When clear, removes the default locale-service, then the\ngateway.\n\n```bash\nvmware-nsx gateway delete-tier1 app-t1 --dry-run\nvmware-nsx gateway delete-tier1 app-t1\n```\n\n### `gateway configure-tier0-bgp`\n\nConfigure BGP settings (local AS, ECMP, inter-SR iBGP) on a Tier-0 gateway.\nBGP neighbor creation is a separate Policy API object and is not exposed —\nuse `networking bgp-neighbors` to inspect neighbors.\n\n```bash\nvmware-nsx gateway configure-tier0-bgp tier0-gw --local-as 65001 --ecmp\n```\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `--local-as` | (required) | Local AS number |\n| `--enabled/--disabled` | enabled | Enable or disable BGP |\n| `--ecmp/--no-ecmp` | ecmp | Enable ECMP for BGP routes |\n| `--inter-sr-ibgp/--no-inter-sr-ibgp` | enabled | Enable inter-SR iBGP |\n| `--locale-service` | `default` | Locale-service identifier |\n\n---\n\n## NAT Management (write)\n\n### `nat create-rule`\n\nCreate a NAT rule on a Tier-1 gateway.\n\n```bash\nvmware-nsx nat create-rule --tier1 app-t1 --rule-id snat-1 --action SNAT --source 10.10.1.0/24 --translated 203.0.113.10\n```\n\n| Option | Required | Default | Description |\n|--------|:--------:|---------|-------------|\n| `--tier1` | Yes | - | Tier-1 gateway ID |\n| `--rule-id` | Yes | - | NAT rule ID |\n| `--action` | No | `DNAT` | NAT action: SNAT, DNAT, REFLEXIVE |\n| `--source` | No | - | Source network CIDR |\n| `--destination` | No | - | Destination network CIDR |\n| `--translated` | No | `\"\"` | Translated network/IP |\n\n### `nat delete-rule`\n\nDelete a NAT rule (destructive).\n\n```bash\nvmware-nsx nat delete-rule --tier1 app-t1 --rule-id snat-1 --dry-run\nvmware-nsx nat delete-rule --tier1 app-t1 --rule-id snat-1\n```\n\n---\n\n## Route Management (write)\n\n### `route create-static`\n\nCreate a static route on a Tier-1 gateway.\n\n```bash\nvmware-nsx route create-static --tier1 app-t1 --route-id r1 --network 10.0.0.0/8 --next-hop 10.10.1.254\n```\n\n| Option | Required | Description |\n|--------|:--------:|-------------|\n| `--tier1` | Yes | Tier-1 gateway ID |\n| `--route-id` | Yes | Static route ID |\n| `--network` | Yes | Destination CIDR |\n| `--next-hop` | Yes | Next hop IP address |\n\n### `route delete-static`\n\nDelete a static route (destructive).\n\n```bash\nvmware-nsx route delete-static --tier1 app-t1 --route-id r1\n```\n\n---\n\n## IP Pool Management (write)\n\n### `ip-pool create`\n\nCreate a new IP address pool with one allocation range. If NSX rejects the\nsubnet, the pool is left without it: the command prints why and how to clean up\n(`vmware-nsx ip-pool delete `, then create again) and exits 1.\n\n```bash\nvmware-nsx ip-pool create pool-01 --name \"App Pool\" --start 192.168.1.10 --end 192.168.1.100 --cidr 192.168.1.0/24 --gateway 192.168.1.1\n```\n\n| Option | Required | Description |\n|--------|:--------:|-------------|\n| `--name` | Yes | Display name |\n| `--start` | Yes | Start IP address |\n| `--end` | Yes | End IP address |\n| `--cidr` | Yes | Subnet CIDR |\n| `--gateway` | No | Gateway IP |\n\n### `ip-pool delete`\n\nDelete an IP address pool (destructive — double-confirm; supports `--dry-run`).\n\n```bash\nvmware-nsx ip-pool delete pool-01 --dry-run\nvmware-nsx ip-pool delete pool-01\n```\n\n| Option | Required | Description |\n|--------|:--------:|-------------|\n| `--dry-run` | No | Preview the DELETE without performing it |\n\n---\n\n## Diagnostics & MCP\n\n### `doctor`\n\nCheck environment, config, connectivity, and NSX Manager status.\nExits 0 when healthy, 1 otherwise.\n\n```bash\nvmware-nsx doctor\nvmware-nsx doctor --skip-auth # skip the NSX authentication check (faster)\n```\n\n### `mcp`\n\nStart the MCP server (stdio transport). Single-command entry point for MCP\nclients — equivalent to the legacy `vmware-nsx-mcp` console script, and\npreferred in enterprise networks because it does not re-resolve PyPI.\n\n```bash\nvmware-nsx mcp\n```\n\n### `mcp-config generate / install / list`\n\nGenerate or install MCP server configuration for local AI agents\n(goose, cursor, claude-code, continue, vscode-copilot, localcowork, mcp-agent).\n\n```bash\nvmware-nsx mcp-config list\nvmware-nsx mcp-config generate --agent goose\nvmware-nsx mcp-config install --agent claude-code --yes\n```\n\n---\n\n## Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| `0` | Success |\n| `1` | Operation failed or doctor check failed |\n| `2` | MCP server started on unsupported Python (< 3.10) |\n\n## Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `VMWARE_NSX_CONFIG` | Override config file path (used by MCP server) |\n| `VMWARE_NSX__PASSWORD` | Password for a target (e.g., `VMWARE_NSX_NSX_PROD_PASSWORD`) |\n\nFile v1.11.0:references/setup-guide.md\n\n# Setup Guide\n\nComplete setup and security guide for `vmware-nsx`.\n\n## Prerequisites\n\n- Python 3.10+\n- NSX-T 3.0+ or NSX 4.x Manager\n- Network access to NSX Manager on port 443 (HTTPS)\n- NSX Manager credentials with appropriate role (minimum: `network_engineer` for read-only, `enterprise_admin` for write operations)\n\n## Installation\n\n### Via uv (recommended)\n\n```bash\nuv tool install vmware-nsx-mgmt==1.11.0\n```\n\n### Via pip\n\n```bash\npip install vmware-nsx-mgmt==1.11.0\n```\n\n### From source\n\n```bash\ngit clone --branch v1.11.0 https://github.com/vmware-skills/VMware-NSX.git\ncd VMware-NSX\npip install -e .\n```\n\n## Configuration\n\n### 1. Create config directory\n\n```bash\nmkdir -p ~/.vmware-nsx\n```\n\n### 2. Create config.yaml\n\n```bash\ncp config.example.yaml ~/.vmware-nsx/config.yaml\n```\n\nEdit `~/.vmware-nsx/config.yaml`:\n\n```yaml\ntargets:\n nsx-prod: # Target name (used in CLI --target flag)\n host: nsx-mgr.example.com # NSX Manager hostname or IP (or VIP for cluster)\n username: svc-nsx # NSX Manager service account (least privilege)\n port: 443\n verify_ssl: true # The default. Keep it on for any real environment\n environment: production # Which environment this is — see below\n\n nsx-lab: # Isolated lab only\n host: 10.0.0.100\n username: admin\n port: 443\n verify_ssl: false # Lab NSX Manager with its factory self-signed cert\n environment: lab\n\ndefault_target: nsx-prod\n```\n\n`targets` is a mapping keyed by target name. `default_target` is used when `--target` is not specified; without it, every command must name a target.\n\n**TLS verification**: `verify_ssl` defaults to `true` when omitted. If NSX Manager's certificate is issued by a private/enterprise CA, keep `verify_ssl: true` and point the `SSL_CERT_FILE` environment variable at a PEM bundle that contains that CA (or `SSL_CERT_DIR` at a hashed CA directory) — in your shell, or in the MCP server's `env` block. `SSL_CERT_FILE` replaces the default trust store for that process, so include any other CAs it needs. `verify_ssl: false` disables certificate and hostname checks entirely; use it only for an isolated lab NSX Manager, never for a production target.\n\n**`environment` (optional label)**: policy scopes its rules by this value, so an environment-scoped `deny` rule in `~/.vmware/rules.yaml` can match on it — for example, to freeze state-changing writes on `production`. Any label you like works (`production`, `staging`, `lab`, `dc2-prod`); the target's *name* is not used for it. A target with no label is simply not matched by such a rule. Read-only operations are never affected either way. Run `vmware-audit policy` to see the rules currently in force.\n\n**NSX Manager cluster**: Use the cluster VIP as the `host` value. The VIP automatically routes to the active manager node.\n\n### 3. Create .env for credentials\n\nPasswords are **never stored in config.yaml**. They must be set as environment variables via the `.env` file.\n\n```bash\necho \"VMWARE_NSX_NSX_PROD_PASSWORD=your_password\" > ~/.vmware-nsx/.env\necho \"VMWARE_NSX_NSX_LAB_PASSWORD=lab_password\" >> ~/.vmware-nsx/.env\nchmod 600 ~/.vmware-nsx/.env\n```\n\n**Naming convention**: `VMWARE_NSX__PASSWORD` where `` is the target `name` from config.yaml, uppercased, with hyphens replaced by underscores.\n\nExamples:\n| Target name | Environment variable |\n|-------------|---------------------|\n| `nsx-prod` | `VMWARE_NSX_NSX_PROD_PASSWORD` |\n| `nsx-lab` | `VMWARE_NSX_NSX_LAB_PASSWORD` |\n| `nsx01` | `VMWARE_NSX_NSX01_PASSWORD` |\n\n### 4. Verify setup\n\n```bash\nvmware-nsx doctor\n```\n\nThis runs six checks: config file, .env file, targets, network connectivity, authentication, and MCP server module.\n\nUse `--skip-auth` if NSX Manager is temporarily unreachable:\n\n```bash\nvmware-nsx doctor --skip-auth\n```\n\n## MCP Server Configuration\n\n> **v1.5.15+ recommends the single-command form `vmware-nsx mcp`.** Pre-1.5.15 used\n> `vmware-nsx-mcp`, which still works (backward compatible) but the new form\n> reuses the already-installed `vmware-nsx` binary on PATH and avoids any PyPI\n> re-resolve / TLS-proxy issues.\n\n### Claude Code / Claude Desktop\n\nAdd to your MCP config (`~/.claude.json` or Claude Desktop settings):\n\n```json\n{\n \"mcpServers\": {\n \"vmware-nsx\": {\n \"command\": \"vmware-nsx\",\n \"args\": [\"mcp\"],\n \"env\": {\n \"VMWARE_NSX_CONFIG\": \"~/.vmware-nsx/config.yaml\"\n }\n }\n }\n}\n```\n\n### Cursor\n\nAdd to Cursor MCP settings:\n\n```json\n{\n \"mcpServers\": {\n \"vmware-nsx\": {\n \"command\": \"vmware-nsx\",\n \"args\": [\"mcp\"],\n \"env\": {\n \"VMWARE_NSX_CONFIG\": \"~/.vmware-nsx/config.yaml\"\n }\n }\n }\n}\n```\n\n### Goose\n\nAdd to `~/.config/goose/config.yaml`:\n\n```yaml\nextensions:\n vmware-nsx:\n type: stdio\n cmd: vmware-nsx\n args: [mcp]\n env:\n VMWARE_NSX_CONFIG: \"~/.vmware-nsx/config.yaml\"\n```\n\n### VS Code Copilot\n\nAdd to `.vscode/mcp.json`:\n\n```json\n{\n \"servers\": {\n \"vmware-nsx\": {\n \"type\": \"stdio\",\n \"command\": \"vmware-nsx\",\n \"args\": [\"mcp\"],\n \"env\": {\n \"VMWARE_NSX_CONFIG\": \"~/.vmware-nsx/config.yaml\"\n }\n }\n }\n}\n```\n\n### Continue\n\nAdd to `~/.continue/config.yaml`:\n\n```yaml\nmcpServers:\n - name: vmware-nsx\n command: vmware-nsx\n args: [mcp]\n env:\n VMWARE_NSX_CONFIG: ~/.vmware-nsx/config.yaml\n```\n\n### Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| `invalid peer certificate: UnknownIssuer` (uvx) | Corporate TLS proxy not trusted by uv's bundled cert store. Use `vmware-nsx mcp` instead, or `export UV_NATIVE_TLS=true` |\n| `command not found: vmware-nsx` | Run `uv tool update-shell` then re-source your shell rc, or use the absolute path returned by `which vmware-nsx-mcp` |\n\n### Docker\n\n```bash\ndocker compose up -d\n```\n\nOr run manually:\n\n```bash\ndocker run -d \\\n -v ~/.vmware-nsx:/root/.vmware-nsx:ro \\\n -e VMWARE_NSX_CONFIG=/root/.vmware-nsx/config.yaml \\\n vmware-nsx\n```\n\n### Password obfuscation at rest\n\nOn first load, any plaintext `*_PASSWORD` value in `.env` is automatically\nrewritten to a grep-safe `b64:` form and decoded transparently at\nruntime, so a casual `grep` of the file no longer reveals the password. Values\nare read and written through python-dotenv's own parser, so the stored secret\nnever drifts from what you configured (quotes, inline comments, and trailing\nwhitespace are handled correctly).\n\n> **This is obfuscation, not encryption.** Anyone who can read the file can\n> still decode it. For real secrecy at rest, do not store the password in `.env`\n> at all — inject it from a secret manager (HashiCorp Vault, CyberArk, AWS\n> Secrets Manager, or a Kubernetes Secret) into the `*_PASSWORD` environment\n> variable at process start. The code reads the env var either way.\n\n## Read-Only Operation\n\nTo run the agent read-only, give it a read-only NSX service account (RBAC).\n\n## Security Details\n\n> **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\" and \"NSX\" are trademarks of Broadcom.\n\n### Credential Safety\n\n- Passwords are **only loaded from environment variables** (via `.env` file), never from `config.yaml`\n- The `.env` file permissions are checked at startup; a warning is logged if permissions are wider than `600` (owner read/write only)\n- The `doctor` command verifies `.env` permissions and reports failures\n\n### Authentication\n\nAuthentication is username/password against the NSX session-create API. Credentials are\nform-body encoded, so passwords containing special characters are handled correctly.\nPer-target passwords come from `~/.vmware-nsx/.env` (`VMWARE_NSX__PASSWORD`).\n\n> Principal Identity / client-certificate authentication is not currently implemented.\n\n### Audit Logging\n\nAll operations are logged to `~/.vmware/audit.db` (SQLite WAL mode, via vmware-policy).\n\nEach audit entry records:\n- **timestamp**: UTC ISO 8601\n- **target**: Which NSX Manager was acted on\n- **operation**: What was done (e.g., `create_segment`, `delete_nat_rule`, `query`)\n- **resource**: What resource was affected (segment ID, gateway ID, rule ID)\n- **parameters**: Full parameter set passed to the operation\n- **before_state / after_state**: State snapshots (when available)\n- **result**: Operation outcome\n- **user**: OS username who initiated the operation\n\nExample audit entry:\n\n```json\n{\n \"timestamp\": \"2026-03-26T10:30:00+00:00\",\n \"target\": \"nsx-prod\",\n \"operation\": \"create_segment\",\n \"resource\": \"app-web-seg\",\n \"parameters\": {\"name\": \"app-web-seg\", \"gateway\": \"app-t1\", \"subnet\": \"10.10.1.1/24\", \"transport_zone\": \"tz-overlay\"},\n \"before_state\": null,\n \"after_state\": {\"id\": \"app-web-seg\", \"type\": \"OVERLAY\", \"admin_state\": \"UP\"},\n \"result\": \"Segment 'app-web-seg' created successfully.\",\n \"user\": \"admin\"\n}\n```\n\nRead-only operations are also logged with `operation: \"query\"` for complete traceability.\n\n### Double Confirmation on Write Operations\n\nCLI write commands require two separate confirmation prompts before executing:\n\n1. First prompt: \"Confirm #1: ''?\" (default: No)\n2. Second prompt: \"Confirm #2: This is irreversible. ''?\" (default: No)\n\nBoth must be answered `y` for the operation to proceed. This applies to all CLI create, update, and delete commands. The five MCP delete tools preview by default: without `confirm=True` they return the blast radius and delete nothing, and `confirm=True` is refused while a blocker remains or a read failed. Other MCP write tools execute when called (and are audit-logged), so the agent must call them only after the user has explicitly asked for that change. Use `~/.vmware/rules.yaml` deny rules to block writes on environments such as `production`.\n\n### Dry-Run Mode\n\nAll write commands support `--dry-run` to preview what would happen without making changes:\n\n```bash\nvmware-nsx segment create app-web-seg --name app-web-seg --tz --subnet 10.10.1.1/24 --dry-run\n\nvmware-nsx nat create-rule --tier1 app-t1 --rule-id snat-1 --action SNAT --source 10.10.1.0/24 --translated 172.16.0.10 --dry-run\n```\n\nDry-run prints the target, the API call it would make and its parameters (for updates and deletes, also the object's current state), then exits without changing anything.\n\n### Dependency Checks\n\n- **Segment delete**: Checks for attached ports. If any port is still attached (VMs or router interfaces), the operation is refused — there is no override; detach the ports first\n- **Tier-1 gateway delete**: Checks first, read-only: segments attached by `connectivity_path` and Tier-1-scoped segments, NAT rules, static routes, service interfaces on the `default` locale-service, locale-services other than `default`, IPsec / L2 VPN services, a DNS forwarder, and LB services attached to it. While any remain it refuses, deletes nothing and lists their ids; a read that fails with anything but 404 also refuses. `--dry-run` runs the same check. Only a clean gateway has its `default` locale-service and then itself deleted\n- **NAT/route operations**: Gateway existence is not pre-checked client-side; NSX Manager's API response decides\n\n### Prompt Injection Defense\n\nNSX object names (segments, gateways, rules) returned from the NSX API are sanitized before output via the `_sanitize()` function:\n\n- Strips C0/C1 control characters (U+0000-U+0008, U+000B, U+000C, U+000E-U+001F, U+007F-U+009F)\n- Preserves newlines and tabs\n- Truncates to 500 characters maximum\n\nThis prevents malicious object names from injecting prompts when the data flows to downstream LLM agents.\n\n### Input Validation\n\n- **Segment/gateway/rule/pool IDs**: Must match `^[A-Za-z0-9_-]+$` (no spaces, slashes, or dots), checked before any API call\n- **NAT actions**: Validated against the allowed set (SNAT, DNAT, REFLEXIVE, NO_SNAT, NO_DNAT, NAT64); SNAT/DNAT/REFLEXIVE also require a translated address\n- **IP pool subnets**: Each subnet must carry `cidr` and `allocation_ranges`\n- **Static route next hops**: At least one required, each as `{\"ip_address\": ...}`\n- **CIDR / IP / VLAN syntax and range checks**: Not done client-side — left to NSX Manager's own API validation\n\n### Transport Security\n\n- The MCP server uses **stdio transport** (local only) — no network listener is opened\n- NSX Manager connections use HTTPS on port 443 by default\n- SSL certificate verification is on by default (`verify_ssl: true` when the key is omitted) and can be turned off per target\n- **Production**: keep `verify_ssl: true`. For a private-CA certificate, set the `SSL_CERT_FILE` (PEM bundle) or `SSL_CERT_DIR` environment variable — there is no per-target CA-path setting in config.yaml. Reserve `verify_ssl: false` for isolated labs\n\n### What This Skill Cannot Do\n\nThis skill has **no firewall or security operations**. It cannot:\n- Create, modify, or delete DFW (Distributed Firewall) rules\n- Manage security groups or security policies\n- Configure IDS/IPS\n- Manage URL filtering rules\n- Configure service insertion\n\nFor security operations, use `vmware-nsx-security`.\n\n## Multi-Target Setup\n\nYou can configure multiple NSX Manager targets and switch between them:\n\n```yaml\ntargets:\n nsx-prod:\n host: nsx-prod-vip.example.com\n username: svc-automation\n port: 443\n verify_ssl: true # private CA: export SSL_CERT_FILE=/etc/pki/tls/certs/nsx-ca-bundle.pem\n environment: production\n\n nsx-staging:\n host: nsx-staging.example.com\n username: svc-automation\n port: 443\n verify_ssl: true\n environment: staging\n\n nsx-lab: # isolated lab only\n host: 10.0.1.100\n username: admin\n port: 443\n verify_ssl: false # factory self-signed cert\n environment: lab\n\ndefault_target: nsx-prod\n```\n\n```bash\n# Uses default_target (nsx-prod)\nvmware-nsx inventory list-segments\n\n# Explicitly target staging\nvmware-nsx inventory list-segments --target nsx-staging\n\n# Target lab\nvmware-nsx health alarms --target nsx-lab\n```\n\n## NSX Manager Roles\n\nRecommended role assignments for the service account used by this skill:\n\n| Use Case | NSX Role | Capabilities |\n|----------|---------|-------------|\n| Read-only monitoring | `network_engineer` (read-only) | List/get all objects, health, troubleshoot |\n| Network automation | `network_engineer` | Create/modify segments, T1 gateways, NAT, routes, IP pools |\n| Full operations | `enterprise_admin` | All operations including T0 modifications |\n\n**Least privilege**: For monitoring-only deployments, use a read-only role. Write tools will return permission errors, but all read operations work.\n\n## File Locations\n\n| File | Purpose |\n|------|---------|\n| `~/.vmware-nsx/config.yaml` | Connection targets and settings |\n| `~/.vmware-nsx/.env` | Passwords (chmod 600) |\n| `~/.vmware/audit.db` | Operation audit trail (SQLite WAL, via vmware-policy) |\n\n## Combining with Other VMware Skills\n\nvmware-nsx can run alongside other VMware MCP skills simultaneously:\n\n```json\n{\n \"mcpServers\": {\n \"vmware-nsx\": {\n \"command\": \"vmware-nsx\",\n \"args\": [\"mcp\"],\n \"env\": { \"VMWARE_NSX_CONFIG\": \"~/.vmware-nsx/config.yaml\" }\n },\n \"vmware-nsx-security\": {\n \"command\": \"vmware-nsx-security\",\n \"args\": [\"mcp\"],\n \"env\": { \"VMWARE_NSX_SECURITY_CONFIG\": \"~/.vmware-nsx-security/config.yaml\" }\n },\n \"vmware-monitor\": {\n \"command\": \"vmware-monitor\",\n \"args\": [\"mcp\"],\n \"env\": { \"VMWARE_MONITOR_CONFIG\": \"~/.vmware-monitor/config.yaml\" }\n }\n }\n}\n```\n\nFile v1.11.0:skill-card.md\n\n## Description:\n\nUse this skill to inspect or manage VMware NSX networking through NSX Manager, including segments, Tier-0 and Tier-1 gateways, NAT, static routes, BGP, IP pools, health checks, and VM-to-segment troubleshooting.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[zw008](https://clawhub.ai/user/zw008)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nNetwork, virtualization, and platform engineers use this skill to inspect VMware NSX inventory and health, troubleshoot connectivity, and make explicit user-approved NSX networking changes. It is intended for NSX Manager environments where agents may need read access by default and controlled write access for segments, gateways, NAT, routing, BGP, and IP pools.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can make high-impact NSX networking changes, including segment, gateway, NAT, static route, IP pool, and Tier-0 BGP updates.\n\nMitigation: Use least-privilege or read-only NSX credentials by default and require explicit human approval before any non-read operation.\n\nRisk: Delete operations can disrupt workloads or remove dependent network configuration.\n\nMitigation: Review dry-run or MCP delete previews first; only confirm deletion after blockers, blast radius, and attached resources are understood.\n\nRisk: Production credentials and TLS settings can expose sensitive infrastructure if handled loosely.\n\nMitigation: Keep TLS verification enabled, use a private CA through SSL_CERT_FILE when needed, and store production passwords in a secret manager when available.\n\n## Reference(s):\n\n- [VMware NSX skill homepage](https://github.com/vmware-skills/VMware-NSX)\n- [Agent guardrails](references/agent-guardrails.md)\n- [Capabilities](references/capabilities.md)\n- [CLI reference](references/cli-reference.md)\n- [Setup guide](references/setup-guide.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown with inline shell commands and structured MCP guidance]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include NSX inventory summaries, health findings, troubleshooting steps, dry-run previews, and explicit change instructions.]\n\n## Skill Version(s):\n\n1.11.0 (source: ClawHub release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.11.0:evals/evals.json\n\n{\n \"skill_name\": \"vmware-nsx\",\n \"evals\": [\n {\n \"id\": 1,\n \"prompt\": \"Create a new app network: segment app-web on 10.10.1.0/24 with a Tier-1 gateway and SNAT to 172.16.0.10\",\n \"expected_output\": \"Segment, gateway, and NAT rule created\",\n \"files\": [],\n \"expectations\": [\n \"Uses create_segment with correct subnet\",\n \"Uses create_tier1_gateway\",\n \"Uses create_nat_rule with SNAT action and correct IPs\"\n ]\n },\n {\n \"id\": 2,\n \"prompt\": \"List all network segments and check if any transport nodes are down\",\n \"expected_output\": \"Segment list and transport node health\",\n \"files\": [],\n \"expectations\": [\n \"Uses list_segments for segment inventory\",\n \"Uses list_transport_nodes or get_transport_node_status for health\",\n \"Reports unhealthy nodes clearly\"\n ]\n },\n {\n \"id\": 3,\n \"prompt\": \"Troubleshoot why VM app-01 can't reach the internet - check its segment, gateway, and NAT\",\n \"expected_output\": \"Network path analysis from VM to internet\",\n \"files\": [],\n \"expectations\": [\n \"Uses get_segment_port_for_vm to find VM's segment\",\n \"Checks gateway configuration\",\n \"Checks NAT rules on the Tier-1 gateway\"\n ]\n }\n ]\n}\n\nArchive v1.10.0: 8 files, 33927 bytes\n\nFiles: evals/evals.json (1283b), references/agent-guardrails.md (9098b), references/capabilities.md (20638b), references/cli-reference.md (12335b), references/setup-guide.md (15589b), skill-card.md (2781b), SKILL.md (23976b), _meta.json (130b)\n\nFile v1.10.0:SKILL.md\n\n---\nname: vmware-nsx\ndescription: >\n Use this skill when the user needs to inspect or manage VMware NSX networking through NSX Manager — segments, Tier-0/Tier-1 gateways, NAT, static routes/BGP, and IP pools.\n Directly handles: list and inspect segments, gateways, NAT rules, routes and IP pools; check transport node, edge cluster and manager health; find a VM's segment. Changes (create/update/delete segments, Tier-1 gateways, NAT rules, static routes, IP pools, Tier-0 BGP) only when the user explicitly asks for that change.\n Use this skill for \"create segment\", \"set up gateway\", \"create NAT rule\", \"check network health\", \"troubleshoot connectivity\" when the context is explicitly NSX, NSX-T, or NSX Manager.\n Do NOT use for networking outside NSX, DFW firewall rules or security groups (use vmware-nsx-security), vSphere distributed port groups or host VMkernel adapters (use vmware-aiops), VM lifecycle (use vmware-aiops), or AVI/ALB load balancing (use vmware-avi).\n For multi-step workflows use vmware-pilot.\ninstaller:\n kind: uv\n package: vmware-nsx-mgmt\nallowed-tools:\n - Bash\nmetadata: {\"openclaw\":{\"requires\":{\"anyBins\":[\"vmware-nsx\",\"uvx\"]},\"optional\":{\"env\":[\"VMWARE_NSX_CONFIG\",\"VMWARE_NSX__PASSWORD\",\"VMWARE_NSX__USERNAME\",\"VMWARE_AUDIT_APPROVED_BY\"],\"bins\":[\"vmware-policy\"]},\"homepage\":\"https://github.com/vmware-skills/VMware-NSX\",\"emoji\":\"🌐\",\"os\":[\"macos\",\"linux\"]}}\ncompatibility: >\n vmware-policy auto-installed as Python dependency (provides @vmware_tool decorator and audit logging). All write operations audited to ~/.vmware/audit.db.\n Credentials: Each NSX Manager target requires a per-target password env var in ~/.vmware-nsx/.env following the pattern VMWARE_NSX__PASSWORD. Username/password session auth only (client-certificate auth is not implemented). Passwords are never logged or echoed.\n Write operations: CLI write commands require double confirmation and support --dry-run. The five MCP delete tools preview by default — without confirm=True they return the blast radius and change nothing, and confirm=True is refused while a blocker remains (attached ports, Tier-1 dependents, allocated IPs) or a read failed. Other MCP write tools execute when called and are audit-logged, so the agent must call them only on the user's explicit request; ~/.vmware/rules.yaml deny rules can block them per environment.\n VMWARE_AUDIT_APPROVED_BY is an optional attestation recorded in the audit row; it is not a gate and does not carry credentials.\n No webhooks, no outbound network calls, no guest operations. Local only: stdio MCP + NSX Policy API (HTTPS 443).\n SSL bypass: verify_ssl is on by default; trust a private CA via the SSL_CERT_FILE env var; verify_ssl false only for isolated labs with self-signed certs.\n Transitive dependencies: Only vmware-policy (audit/policy). No post-install scripts or background services.\n---\n\n# VMware NSX\n\n> **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\" and \"NSX\" are trademarks of Broadcom. Source code is publicly auditable at [github.com/vmware-skills/VMware-NSX](https://github.com/vmware-skills/VMware-NSX) under the MIT license.\n\nVMware NSX networking management — 33 MCP tools for segments, gateways, NAT, routing, and IPAM.\n\n> Domain-focused networking skill for NSX-T / NSX 4.x Policy API.\n> **Companion skills**: [vmware-nsx-security](https://github.com/vmware-skills/VMware-NSX-Security) (DFW/firewall), [vmware-aiops](https://github.com/vmware-skills/VMware-AIops) (VM lifecycle), [vmware-monitor](https://github.com/vmware-skills/VMware-Monitor) (read-only monitoring), [vmware-storage](https://github.com/vmware-skills/VMware-Storage) (iSCSI/vSAN), [vmware-vks](https://github.com/vmware-skills/VMware-VKS) (Tanzu Kubernetes), [vmware-aria](https://github.com/vmware-skills/VMware-Aria) (metrics/alerts/capacity), [vmware-avi](https://github.com/vmware-skills/VMware-AVI) (AVI/ALB/AKO), [vmware-harden](https://github.com/vmware-skills/VMware-Harden) (compliance baselines).\n> | [vmware-pilot](../vmware-pilot/SKILL.md) (workflow orchestration) | [vmware-policy](../vmware-policy/SKILL.md) (audit/policy)\n\n## What This Skill Does\n\n| Category | Tools | Count | Read / Write |\n|----------|-------|:-----:|:------------:|\n| **Segments** | list, get details, create, update, delete | 5 | 2R / 3W |\n| **Tier-0 Gateways** | list, get details, BGP neighbors, configure BGP | 4 | 3R / 1W |\n| **Tier-1 Gateways** | list, get details, create, update, delete | 5 | 2R / 3W |\n| **NAT** | list rules, create rule, delete rule | 3 | 1R / 2W |\n| **Static Routes** | list, create, delete | 3 | 1R / 2W |\n| **IP Pools** | list, get usage, create pool, delete pool | 4 | 2R / 2W |\n| **Fabric Inventory** | transport zones, transport nodes, edge clusters | 3 | 3R / 0W |\n| **Health** | NSX alarms, transport node status, edge cluster status, manager status | 4 | 4R / 0W |\n| **Troubleshooting** | logical port status, VM-to-segment lookup | 2 | 2R / 0W |\n\n**Total**: 33 tools (20 read-only + 13 write)\n\n## Quick Install\n\n```bash\nuv tool install vmware-nsx-mgmt==1.10.0\nvmware-nsx init # guided setup: writes config + .env (chmod 600, password grep-safe), then verifies\nvmware-nsx doctor\n```\n\n## When to Use This Skill\n\n- List, create, or modify NSX segments (overlay / VLAN-backed)\n- Create or manage Tier-0 / Tier-1 gateways\n- Configure NAT rules (SNAT, DNAT, reflexive)\n- View or add static routes, check BGP neighbors\n- Manage IP pools and subnet allocations\n- Check NSX alarms, transport node health, edge cluster status\n- Find which segment a VM is connected to\n- Troubleshoot logical port status\n\nUse it only when the request is explicitly about NSX (NSX-T / NSX 4.x, NSX Manager). **Writes only on request**: call a create/update/delete tool, NAT/route/IP-pool change, or Tier-0 BGP change only when the user has explicitly asked for that specific change — never as a side step of a read, health check, or troubleshooting task. Diagnose with read tools first and propose the change instead.\n\n**Use companion skills for**:\n- Distributed firewall, security groups, DFW rules, IDS/IPS → `vmware-nsx-security`\n- vSphere distributed port groups, host VMkernel adapters → `vmware-aiops`\n- VM lifecycle, deployment, guest ops → `vmware-aiops`\n- vSphere inventory, health, alarms, events → `vmware-monitor`\n- Storage: iSCSI, vSAN, datastores → `vmware-storage`\n- Tanzu Kubernetes → `vmware-vks`\n- Load balancing, AVI/ALB, AKO, Ingress → `vmware-avi`\n\n## Related Skills — Skill Routing\n\n| User Intent | Recommended Skill |\n|-------------|-------------------|\n| NSX networking: segments, gateways, NAT, routing, IPAM | **vmware-nsx** ← this skill |\n| NSX security: DFW rules, security groups, IDS/IPS | **vmware-nsx-security** |\n| Read-only vSphere monitoring, alarms, events | **vmware-monitor** |\n| VM lifecycle, deployment, guest ops | **vmware-aiops** |\n| vSphere distributed port groups, host VMkernel adapters | **vmware-aiops** |\n| Storage: iSCSI, vSAN, datastores | **vmware-storage** |\n| Tanzu Kubernetes (vSphere 8.x+) | **vmware-vks** |\n| Aria Ops: metrics, alerts, capacity planning | **vmware-aria** |\n| Multi-step workflows with approval | **vmware-pilot** |\n| Compliance baselines (CIS / 等保 / PCI-DSS), drift detection, LLM remediation advisor | **vmware-harden** (`uv tool install vmware-harden`) |\n| Load balancer, AVI, ALB, AKO, Ingress | **vmware-avi** (`uv tool install vmware-avi`) |\n| Audit log query | **vmware-policy** (`vmware-audit` CLI) |\n\n## Common Workflows\n\n### Create an App Network (Segment + T1 Gateway + NAT)\n\n**Pre-flight (judgment, not blind sequence)**:\n- Subnet conflict check: scan `inventory list-segments` and `networking list-ip-pools` for any overlap with the proposed CIDR. Overlapping subnets cause asymmetric routing or silent blackholing — NSX will not warn you.\n- Edge cluster capacity: confirm chosen `--edge-cluster` is healthy (`inventory list-edge-clusters` + `health edge-cluster-status `) and not at SR (Service Router) limit. A fully-loaded edge cluster will accept the T1 creation but routing will fail.\n- T0 uplink: the parent T0 must already be configured with BGP/static routes upstream — otherwise SNAT works internally but external traffic goes nowhere.\n- NAT IP: `--translated` IP must be from a routable address pool announced by T0; using a random IP creates a half-working network.\n- **Always `--dry-run` first** — once a segment is attached to running VMs, deleting it requires detaching every port.\n\n**Steps**:\n1. `vmware-nsx gateway create-tier1 app-t1 --name app-t1 --edge-cluster --tier0 --dry-run` → review, then run for real\n2. `vmware-nsx segment create app-web-seg --name app-web-seg --tz --subnet `\n3. `vmware-nsx nat create-rule --tier1 app-t1 --rule-id snat-1 --action SNAT --source --translated `\n4. Verify end-to-end: `inventory list-segments`, `networking list-nat-rules app-t1`, AND test with a VM attached to the new segment\n5. **On failure**: a connection error or HTTP error prints a single teaching line (e.g. 403 → check NSX role privileges; 404 → run the matching list command for the exact ID). Run `vmware-nsx doctor` to verify connectivity and credentials, fix, and re-run the failed step — earlier completed steps are idempotent PUTs and safe to re-apply.\n\n### Check Network Health\n\n**Judgment**: don't just enumerate health endpoints — correlate them. The order below maps cause to symptom: if manager is down, transport nodes will look down too (false positive); fix top-down.\n\n1. `vmware-nsx health manager-status` — if **any** manager node is `DEGRADED` or `DOWN`, stop here and resolve before trusting downstream signals\n2. `vmware-nsx inventory list-transport-nodes` then `health transport-node-status ` for any node not `UP` — flag nodes down ≥ 5 min; transient blips are normal\n3. `vmware-nsx inventory list-edge-clusters` then `health edge-cluster-status ` — verify SR placement is balanced; one edge holding 80% of SRs is a single point of failure\n4. `vmware-nsx health alarms --severity HIGH` (repeat with `CRITICAL`) — severity filter is exact-match, not \"and above\"\n5. Cross-check with `vmware-monitor` for vSphere host events — a host losing connection to vCenter often masquerades as an NSX problem\n\n### Troubleshoot VM Connectivity\n\n**Judgment**: connectivity failures happen at one of three layers. Identify which layer first, then drill — don't probe randomly.\n\n- **Layer 1 — VM-to-segment**: VM has no segment, wrong vNIC, or port admin-down → `troubleshoot vm-segment` + `troubleshoot port-status`\n- **Layer 2 — segment-to-gateway**: segment not attached to T1, T1 not connected to T0 → `inventory get-tier1` shows no Tier-0 path\n- **Layer 3 — gateway-to-upstream**: T0 BGP/static missing or SNAT not configured → `networking bgp-neighbors`, `networking list-nat-rules`\n\n**Steps** (stop as soon as the failing layer is identified):\n1. Layer 1: `troubleshoot vm-segment my-vm-01` → if no port, check vSphere vNIC binding first\n2. Layer 1: `troubleshoot port-status ` → admin-down or DFW-blocked? If DFW, jump to vmware-nsx-security\n3. Layer 2: `inventory get-tier1 app-t1` → Tier-0 path present and route advertisement enabled? If not, T1↔T0 link broken\n4. Layer 3: `networking bgp-neighbors tier0-gw` → all neighbors `ESTABLISHED`? Flapping → upstream issue\n5. Layer 3: `networking list-nat-rules app-t1` → SNAT rule covers the source CIDR? Mis-typed CIDR is the most common cause\n\n### Multi-Target Operations\n\nAll commands accept `--target ` to operate against a specific NSX Manager from your config (default: the first target in config.yaml), e.g. `vmware-nsx inventory list-segments --target nsx-prod`.\n\n## Usage Mode\n\n| Scenario | Recommended | Why |\n|----------|:-----------:|-----|\n| Local/small models (Ollama, Qwen) | **CLI** | ~2K tokens vs ~8K for MCP |\n| Cloud models (Claude, GPT-4o) | Either | MCP gives structured JSON I/O |\n| Automated pipelines | **MCP** | Type-safe parameters, structured output |\n\n## MCP Tools (33 — 20 read, 13 write)\n\nAll MCP tools accept an optional `target` parameter to select which NSX Manager to connect to.\n\n| Category | Tool | Type | Description |\n|----------|------|:----:|-------------|\n| Segment | `list_segments` | Read | List all segments with type, subnet, admin state, port count |\n| | `get_segment` | Read | Get segment details including ports and subnet config |\n| | `create_segment` | Write | Create overlay or VLAN segment with subnet and gateway |\n| | `update_segment` | Write | Update segment properties (name, subnets, gateway link) |\n| | `delete_segment` | Write | Delete a segment; refuses (listing port ids) while ports are attached |\n| Tier-0 GW | `list_tier0_gateways` | Read | List Tier-0 gateways with HA mode and transit subnets |\n| | `get_tier0_gateway` | Read | Get Tier-0 details: HA mode, failover, transit subnets |\n| | `get_bgp_neighbors` | Read | List BGP neighbor sessions with state, ASN, prefixes |\n| | `configure_tier0_bgp` | Write | Configure BGP (local AS, ECMP, inter-SR iBGP) on a Tier-0 |\n| Tier-1 GW | `list_tier1_gateways` | Read | List Tier-1 gateways with linked Tier-0 and route advertisement |\n| | `get_tier1_gateway` | Read | Get Tier-1 details: Tier-0 link, route advertisement |\n| | `create_tier1_gateway` | Write | Create Tier-1 gateway with edge cluster and Tier-0 link |\n| | `update_tier1_gateway` | Write | Update Tier-1 properties (route advertisement, Tier-0 link) |\n| | `delete_tier1_gateway` | Write | Delete a Tier-1 gateway; refuses (listing blocking ids) while segments, NAT rules, routes, interfaces or VPN / DNS / LB services remain |\n| NAT | `list_nat_rules` | Read | List NAT rules on a Tier-1 gateway |\n| | `create_nat_rule` | Write | Create SNAT/DNAT/reflexive NAT rule on a gateway |\n| | `delete_nat_rule` | Write | Delete a NAT rule |\n| Static Routes | `list_static_routes` | Read | List static routes on a Tier-1 gateway |\n| | `create_static_route` | Write | Add a static route with network and next-hop |\n| | `delete_static_route` | Write | Remove a static route |\n| IP Pools | `list_ip_pools` | Read | List IP pools with usage summary |\n| | `get_ip_pool_usage` | Read | Show allocation usage for a pool |\n| | `create_ip_pool` | Write | Create a new IP address pool with allocation ranges |\n| | `delete_ip_pool` | Write | Permanently delete an IP address pool; refuses while IPs are allocated |\n| Fabric | `list_transport_zones` | Read | List transport zones with type (OVERLAY/VLAN) |\n| | `list_transport_nodes` | Read | List transport nodes with node type and status |\n| | `list_edge_clusters` | Read | List edge clusters with member count and deployment type |\n| Health | `list_nsx_alarms` | Read | List active NSX alarms filtered by severity |\n| | `get_transport_node_status` | Read | Transport node connectivity and config status |\n| | `get_edge_cluster_status` | Read | Edge cluster member status and failover config |\n| | `get_nsx_manager_status` | Read | NSX Manager cluster health and node roles |\n| Troubleshoot | `get_logical_port_status` | Read | Realized state of all ports on a segment |\n| | `get_segment_port_for_vm` | Read | Find which segment a VM is connected to by display name |\n\nWrite tools require explicit parameters and are audit-logged. The five `delete_*` tools preview by default: without `confirm=True` they return `blast_radius` (what would be removed, `blockers`, `unmeasured`) and change nothing. Show it to the user and pass `confirm=True` only after they decide; it is refused while a blocker remains or a read failed. Other MCP write tools execute directly — call one only after the user has explicitly asked for that change.\n\n### List results are envelopes — read `truncated` before you summarise\n\nEvery list-returning tool above returns `{items, returned, limit, total, truncated, hint}`, not a bare array. Rows live under `items`: empty `items` with `truncated: false` means the query genuinely matched nothing — report that, not a tool failure. `truncated: true` means `items` is not the whole collection — never call it complete. It does **not** mean more rows can be fetched: it stays true on the last page. Page with `next_offset`, stopping when it is `null`; `hint` says which situation you are in. Field semantics, `total` sourcing, and an example payload: `references/capabilities.md`.\n\n## Local & Small Models\n\nRunning with local or small models? See [`references/agent-guardrails.md`](references/agent-guardrails.md) for explicit operating rules that keep tool calls reliable.\n\n## CLI Quick Reference\n\n```bash\n# Inventory (read-only)\nvmware-nsx inventory list-segments [--target ]\nvmware-nsx inventory get-segment \nvmware-nsx inventory list-tier0s\nvmware-nsx inventory get-tier0 \nvmware-nsx inventory list-tier1s\nvmware-nsx inventory get-tier1 \nvmware-nsx inventory list-transport-zones\nvmware-nsx inventory list-transport-nodes\nvmware-nsx inventory list-edge-clusters\n\n# Networking (read-only)\nvmware-nsx networking list-nat-rules \nvmware-nsx networking bgp-neighbors \nvmware-nsx networking list-static-routes \nvmware-nsx networking list-ip-pools\nvmware-nsx networking ip-pool-usage \n\n# Segment management (write; full option lists in references/cli-reference.md)\nvmware-nsx segment create --name --tz [--vlan|--subnet] [--dry-run]\nvmware-nsx segment update [--name|--subnet] [--dry-run]\nvmware-nsx segment delete [--dry-run]\n\n# Gateway management (write)\nvmware-nsx gateway create-tier1 --name [--tier0|--edge-cluster] [--dry-run]\nvmware-nsx gateway update-tier1 [--name|--tier0|--advertise] [--dry-run]\nvmware-nsx gateway delete-tier1 [--dry-run]\nvmware-nsx gateway configure-tier0-bgp --local-as [--ecmp] [--dry-run]\n\n# NAT (write)\nvmware-nsx nat create-rule --tier1 --rule-id --action SNAT --source --translated [--dry-run]\nvmware-nsx nat delete-rule --tier1 --rule-id [--dry-run]\n\n# Static routes (write)\nvmware-nsx route create-static --tier1 --route-id --network --next-hop [--dry-run]\nvmware-nsx route delete-static --tier1 --route-id [--dry-run]\n\n# IP pools (write)\nvmware-nsx ip-pool create --name --start --end --cidr [--dry-run]\n\n# Health & Troubleshooting (read-only)\nvmware-nsx health alarms [--severity CRITICAL]\nvmware-nsx health transport-node-status \nvmware-nsx health edge-cluster-status \nvmware-nsx health manager-status\nvmware-nsx troubleshoot port-status \nvmware-nsx troubleshoot vm-segment \n\n# Diagnostics\nvmware-nsx doctor [--skip-auth]\n```\n\n> Full CLI reference with all options and output formats: see `references/cli-reference.md`\n\n## Troubleshooting\n\n### \"Segment not found\" when querying\n\nSegment display names and Policy API IDs can differ. Use `vmware-nsx inventory list-segments` to get the exact ID. The Policy API uses the segment `id` field, not `display_name`. Common mistakes: using the display name with spaces instead of the hyphenated ID.\n\n### NAT rule creation fails with \"gateway not found\"\n\nNAT rules are created on Tier-1 gateways (or Tier-0 for some topologies). Verify the gateway name with `vmware-nsx inventory list-tier1s`. The gateway must have an edge cluster assigned for NAT to function.\n\n### BGP neighbor shows \"Connect\" or \"Active\" state\n\nThe BGP session is not established. Common causes:\n1. Peer IP unreachable from the edge node — check physical uplinks and VLAN config\n2. ASN mismatch — compare local and remote ASN in `bgp-neighbors` output\n3. Firewall blocking TCP 179 — check edge node firewall rules (not NSX DFW)\n4. MD5 password mismatch — verify authentication settings on both sides\n\n### Transport node status \"degraded\"\n\nA transport node in degraded state has partial connectivity. Steps:\n1. Check `vmware-nsx health transport-nodes` for the specific failure reason\n2. Common cause: tunnel endpoint (TEP) unreachable — verify underlay MTU (minimum 1600 for Geneve)\n3. Check NTP sync between NSX Manager and transport nodes\n4. If recently upgraded, verify the host switch config matches NSX Manager expectations\n\n### \"Password not found\" error\n\nThe password environment variable is missing. Variable names follow the pattern `VMWARE_NSX__PASSWORD` where hyphens become underscores. Example: target `nsx-prod` needs `VMWARE_NSX_NSX_PROD_PASSWORD`. Check your `~/.vmware-nsx/.env` file.\n\n## Safety\n\n- **Read-heavy**: 20 of 33 tools are read-only (list, get, status, health, troubleshoot)\n- **Audit logging**: All operations logged to `~/.vmware/audit.db` (SQLite WAL, via vmware-policy) with timestamp, user, target, operation, parameters, and result\n- **Double confirmation**: CLI write commands require two separate confirmation prompts before executing\n- **Dry-run mode**: All CLI write commands support `--dry-run` to preview API calls without executing (MCP deletes preview unless `confirm=True`; other MCP writes execute directly and are audit-logged)\n- **Dependency checks**: Segment delete refuses while ports are attached. Tier-1 delete first checks (read-only) for attached or Tier-1-scoped segments, NAT rules, static routes, service interfaces, extra locale-services, IPsec / L2 VPN services, a DNS forwarder and attached LB services; while any remain it refuses, deletes nothing and lists their ids (`--dry-run` runs the same check). Only a clean gateway has its default locale-service removed and is then deleted. IP pool delete (MCP) refuses while addresses are allocated\n- **Input validation**: resource IDs restricted to letters, digits, `-` and `_`; NAT action checked against the allowed set; required fields checked (translated address for SNAT/DNAT/REFLEXIVE, CIDR + ranges per IP-pool subnet). CIDR/IP syntax and gateway existence are not checked client-side — they are left to NSX Manager's own API validation\n- **Prompt injection defense**: NSX object names returned from the API are sanitized via `_sanitize()` — strips control characters, truncates to 500 chars\n- **Credential safety**: Passwords loaded only from environment variables (`.env` file), never from `config.yaml`\n- **No firewall operations**: Cannot create, modify, or delete DFW rules, security groups, or IDS/IPS policies — that scope belongs to `vmware-nsx-security`\n\n## Setup\n\n```bash\nuv tool install vmware-nsx-mgmt==1.10.0\nvmware-nsx init # writes ~/.vmware-nsx/config.yaml + .env (chmod 600), then verifies\nvmware-nsx doctor\n```\n\n> All tools are automatically audited via vmware-policy. Audit logs: `vmware-audit log --last 20`\n\n> Full setup guide with multi-target config, MCP server setup, and Docker: see `references/setup-guide.md`\n\n## Architecture\n\n```\nUser (natural language)\n |\nAI Agent (Claude Code / Goose / Cursor)\n | reads SKILL.md\nvmware-nsx CLI or MCP server (stdio transport)\n | NSX Policy API (REST/JSON over HTTPS)\nNSX Manager\n |\nSegments / Gateways / NAT / Routes / IP Pools / Transport Nodes\n```\n\n## Audit & Safety\n\nAll operations are automatically audited via vmware-policy (`@vmware_tool` decorator):\n- Every tool call logged to `~/.vmware/audit.db` (SQLite, framework-agnostic)\n- Policy rules enforced via `~/.vmware/rules.yaml` (deny rules, maintenance windows, risk levels)\n- Risk classification: each tool tagged as low/medium/high/critical\n- View recent operations: `vmware-audit log --last 20`\n- View denied operations: `vmware-audit log --status denied`\n\nvmware-policy is automatically installed as a dependency — no manual setup needed.\n\n## License\n\nMIT — [github.com/vmware-skills/VMware-NSX](https://github.com/vmware-skills/VMware-NSX)\n\nFile v1.10.0:_meta.json\n\n{\n \"ownerId\": \"kn7b067awq2s97bn3d7p5qfhw5827pxc\",\n \"slug\": \"vmware-nsx\",\n \"version\": \"1.10.0\",\n \"publishedAt\": 1789790123906\n}\n\nFile v1.10.0:references/agent-guardrails.md\n\n# Operating vmware-nsx with a local / small model\n\nClaude-class models drive this skill without special instruction. Smaller and\nlocally-hosted models — Llama 3.3 70B, Qwen, Mistral, and similar, served\nthrough Goose, Ollama, or OpenShift AI — need explicit operating rules to call\ntools reliably.\n\nThis page exists because an operator wrote those rules by hand first. The\nguardrails below are adapted, with thanks, from the working configuration\n[@juanpf-ha](https://github.com/juanpf-ha) developed while running\nvmware-monitor and vmware-aria against a production vSphere estate with Llama\n3.3 70B FP8 on an on-prem H100\n([VMware-AIops#31](https://github.com/vmware-skills/VMware-AIops/issues/31)). The\ncross-skill rules are identical across this family; the parts below marked\nvmware-nsx are specific to this skill.\n\nvmware-nsx exposes 33 MCP tools, 13 of which change state. Network writes fail\ndifferently from other writes: deleting a segment or reconfiguring a Tier-0's\nBGP does not error, it disconnects things — often something other than the\nobject the model was looking at.\n\n> **Disclaimer**: This is a community-maintained open-source project and is\n> **not affiliated with, endorsed by, or sponsored by VMware, Inc. or Broadcom\n> Inc.** \"VMware\" and \"vSphere\" are trademarks of Broadcom.\n\n---\n\n## First: the rules you no longer need to write\n\nSeveral guardrails from the original configuration are now enforced by the\nskill itself. Prompt instructions are advisory — a model can ignore them.\nThese are structural, so it cannot.\n\n| Guardrail you would otherwise prompt for | Now enforced by |\n|---|---|\n| \"Warn me if a segment still has workloads on it before deleting\" | **`delete_segment` checks the ports first** and refuses, deleting nothing, while any is attached (it names them). The check runs server-side, not in the prompt. |\n| \"Show me what a delete would remove before it happens\" | **The five delete tools preview by default.** Without `confirm=True` they return `blast_radius` and delete nothing; `confirm=True` is refused while a blocker remains or a read failed. |\n| \"Use explicit limits for queries that may return large amounts of data\" | **The list envelope.** Every list-returning tool returns `{items, returned, limit, total, truncated, hint}`, so the model reads truncation instead of guessing at it. `truncated: true` means `items` is not the whole collection; `next_offset` (null on the last page) is what a paging loop stops on, and the `hint` says which of the two you are looking at. |\n| \"If a listing came back empty, say so rather than claiming the call failed\" | Same envelope. Empty `items` with `truncated: false` means the query genuinely matched nothing — a stated result, not a silence the model has to interpret. |\n| \"Log every state change you make\" | **The `@vmware_tool` decorator.** Every write is recorded to `~/.vmware/audit.db` before the model sees the result, and policy rules are evaluated ahead of execution. |\n| \"Block state-changing writes against a production target\" | **Policy.** An opt-in environment-scoped `deny` rule in `~/.vmware/rules.yaml` matches a target's `environment:` label and refuses matching writes before execution. |\n\n---\n\n## The system prompt\n\nEverything below still benefits from being stated explicitly. Copy this into\nyour agent's instruction block.\n\n```text\n## Tool use\n\n- Always call an MCP tool before answering any question about the current NSX\n environment. Never answer from memory or assumption.\n- Never describe a tool call, and never output a JSON example, instead of\n executing the tool. If you intend to call a tool, call it.\n- If a tool fails, report the actual error text. Do not complete the answer\n with assumptions about what the result would have been.\n- Use explicit limits on queries that may return large amounts of data. Do not\n request unlimited results unless the user asks for them.\n- Every tool accepts an optional target. When more than one NSX Manager is\n configured, name the target explicitly rather than relying on the default.\n\n## Skill routing\n\n- vmware-nsx: segments, Tier-0 and Tier-1 gateways, BGP, NAT, static routes,\n IP pools, transport zones and nodes, edge clusters, NSX alarms.\n- vmware-nsx-security: DFW policies and rules, security groups, VM tags,\n IDS/IPS, Traceflow. Firewall work is not this skill.\n- vmware-monitor: read-only vCenter inventory, hosts, alarms, events.\n- vmware-aiops: VM lifecycle.\n- vmware-avi: load balancing, virtual services, pools, AKO.\n- vmware-pilot: multi-step workflows that need approval gates.\n\n## Data fidelity\n\n- Never invent segments, gateways, routes, pools, IP addresses or ASNs. If a\n tool did not return it, it does not exist for this answer.\n- Preserve the exact admin state, realization state, BGP session state and\n status values the tools return. Do not translate, normalise, or prettify\n enum values.\n- Report IP addresses, prefixes and ASNs exactly as returned. Never reformat,\n abbreviate or infer a subnet mask.\n- If a requested field was not returned, show it as \"not available\". Do not\n infer it from other fields.\n- Preserve the original order and the full set of fields when the user asks\n for specific ones.\n- When a response is long, report every item it contains. If a result is\n truncated, the tool says so explicitly — report the truncation rather than\n describing the visible subset as the whole.\n\n## Analysis discipline\n\n- Separate observed data from interpretation. State which is which.\n- Do not claim a connectivity, routing or capacity problem unless the tool\n output contains explicit supporting evidence. A BGP session in Connect state\n is an observation; the cause of it is not.\n- Avoid generic recommendations that are not directly supported by the results.\n\n## Identifiers and writes in vmware-nsx\n\n- A segment's display name and its Policy API id are different strings. Resolve\n the id with list_segments before acting on a segment; never derive one from\n the other.\n- NAT rules and static routes live on a gateway. Confirm the gateway with\n list_tier1_gateways before creating a rule on it.\n- Before proposing delete_segment, call get_segment and report the connected\n port count. delete_segment refuses while ports are attached, so name what\n must be detached first rather than retrying.\n- Call a delete_* tool without confirm first and show the user its\n blast_radius. Pass confirm=True only after the user has seen it and said\n yes — an earlier \"delete it\" was said before they saw what it removes.\n- configure_tier0_bgp changes routing for everything behind that Tier-0. Treat\n it as estate-wide, not object-scoped, and say so.\n```\n\n---\n\n## Known failure modes on small models\n\nObserved with Llama 3.3 70B FP8 (Goose, on-prem H100), and useful as a\nchecklist when evaluating any local model against these skills:\n\n| Symptom | Mitigation |\n|---|---|\n| Describes a tool call, or emits a JSON example, instead of executing it | The \"never describe a tool call\" rule above. Also check your harness is not echoing tool schemas into context — models imitate the nearest format they see. |\n| Long tool responses: omits items, or reports \"no data returned\" when data was present | Ask for explicit limits so responses stay small. Check the envelope's `truncated` / `returned` / `total` fields rather than trusting the model's summary — a \"no data\" claim is checkable against `returned`. |\n| Adds generic recommendations unsupported by results | The \"analysis discipline\" rules. BGP and MTU output attract invented advice more than most — hold it to the evidence. |\n| Drops requested fields or reorders results | State the required fields and ordering in the request itself, not only in the system prompt. |\n| Multi-tool workflows take 30–50s end to end | Prefer the tools that answer a whole question in one call: `get_segment_port_for_vm` finds a VM's segment directly, `get_ip_pool_usage` gives allocation without enumerating pools, and `get_nsx_manager_status` covers cluster health in one round trip. |\n| Uses a segment's display name where the Policy API id is required | The identifier rule above. The failure reads as \"segment not found\", which a model tends to interpret as a missing object rather than a wrong key. |\n| Invents or reformats an IP address, prefix length or ASN | The \"report exactly as returned\" rule. In this skill a plausible-looking wrong prefix is worse than no answer. |\n| Proposes a deletion without checking what is attached | Require a `get_segment` port count first. The tool warns, but the model should have looked before it asked. |\n| Silently falls back to the default target in a multi-manager estate | Name the target in the request. |\n\n## Reporting results\n\nLocal-model compatibility is an explicit design constraint for this family, and\nthe evidence base is small. If you evaluate a model against this skill —\nQwen, Mistral, Granite, or anything else — a report of what worked and what did\nnot is genuinely useful:\n[github.com/vmware-skills/VMware-NSX/issues](https://github.com/vmware-skills/VMware-NSX/issues).\n\nFile v1.10.0:references/capabilities.md\n\n# Capabilities\n\nDetailed capability reference for `vmware-nsx`.\n\n## Automation Level Reference\n\nEach operation is classified by autonomy level per the Enterprise Harness Engineering framework:\n\n| Level | Meaning | Agent autonomy | Examples in this skill |\n|:-:|---|---|---|\n| **L1** | Read-only, raw data | Always auto-run | `list_segments`, `get_segment`, `list_tier0_gateways`, `list_tier1_gateways`, `list_nat_rules`, `list_ip_pools`, `list_static_routes`, alarms/health queries |\n| **L2** | Read + analysis / recommendation | Always auto-run | `get_bgp_neighbors`, `get_segment_port_for_vm`, `get_ip_pool_usage`, `get_logical_port_status` — correlation and utilization summaries over raw data |\n| **L3** | Single write — user must approve | Only when the user explicitly asked for that change; CLI adds double-confirm + optional `--dry-run`; the five MCP deletes preview by default and act only with `confirm=True`; segment delete refuses while ports are attached; Tier-1 delete refuses while anything still depends on the gateway; IP pool delete refuses while addresses are allocated | `create_segment`, `delete_segment`, `create_nat_rule`, `update_tier1_gateway`, `create_ip_pool`, `configure_tier0_bgp`, static route mutations |\n| **L4** | Multi-step plan / apply workflow | Plan generation auto; apply gated by user approval | *(roadmap — multi-segment rollout plans, gateway HA failover sequences)* |\n| **L5** | Auto-remediation from learned pattern | Pattern library only; requires `risk:low` + `reversible:true` + `repeatable:true` | *(roadmap — candidates: stale segment cleanup, transport-node refresh)* |\n\n**Notes**:\n- L1/L2 tools are always safe for agents to call without confirmation.\n- L3 tools always pass through the `@vmware_tool` decorator: policy check (`~/.vmware/rules.yaml` deny rules, per environment) → execute → audit log. The CLI's double-confirm and `--dry-run` do not apply to MCP calls.\n- **MCP deletes preview by default** (`delete_segment`, `delete_tier1_gateway`, `delete_nat_rule`, `delete_static_route`, `delete_ip_pool`). A call without `confirm=True` reads what the delete would remove and returns `{\"action\": \"preview\", \"blast_radius\": {...}}`, deleting nothing. `blast_radius` names the object and what it measured — a segment's gateway, subnets, `port_count`/`port_ids`; a Tier-1's `tier0_path`, the `default` locale-service and edge cluster it removes, and its `dependents` by kind; a NAT rule's gateway, action, match and translation; a route's gateway, network and next hops; a pool's `pool_usage`, `allocation_count` (Policy ip-allocations), `realized_allocation_count` (NSX's `pool_usage.allocated_ip_allocations`, which also counts addresses Policy does not list, e.g. TEP pools) and `allocated_ips` — plus `blockers` and `unmeasured`. `confirm=True` re-measures and is refused, deleting nothing, while a blocker remains (attached ports, any Tier-1 dependent, allocated IPs) or while any of those reads failed (`unmeasured` non-empty); the refusal is `{\"error\", \"hint\", \"blast_radius\"}`. Show the preview to the user; set `confirm=True` only after they decide — not because they asked for the delete before seeing it. The preview is logged to the skill audit log as `preview`, not `ok`.\n- For DFW/security rules see [vmware-nsx-security](https://github.com/vmware-skills/VMware-NSX-Security).\n\n## API Coverage\n\nvmware-nsx uses the **NSX Policy API** (not the Management API) for all operations. The Policy API provides a declarative, intent-based interface that is the recommended path for NSX-T 3.x and NSX 4.x.\n\n### Policy API vs Management API\n\n| Aspect | Policy API (used by this skill) | Management API (not used) |\n|--------|--------------------------------|--------------------------|\n| Endpoint prefix | `/policy/api/v1/` | `/api/v1/` |\n| Model | Declarative, intent-based | Imperative, realized-state |\n| Object IDs | User-defined string IDs | System-generated UUIDs |\n| Hierarchy | Infra → Tier-0 → Tier-1 → Segment | Flat namespace |\n| Transaction support | Hierarchical API (PATCH entire tree) | Individual API calls |\n| Recommended by VMware | Yes (primary API since NSX-T 3.0) | Deprecated for new development |\n\n**Why Policy API?** The Policy API allows setting desired state declaratively. NSX Manager reconciles realized state automatically. This is safer for automation — you describe what you want, NSX figures out how to get there.\n\n## Tool Capabilities by Category\n\nThe tables below list **every** MCP tool this skill exposes — 33 total (20 read, 13 write).\nTool names are exactly as registered on the MCP server; endpoints and methods are taken\nfrom the corresponding `vmware_nsx/ops/` implementation. Anything not listed here does\nnot exist.\n\nClassification follows each tool's `[READ]`/`[WRITE]` docstring marker; see README.\n\n### Segments (5 tools — 2 read, 3 write)\n\n| Capability | Tool | API Endpoint | Method |\n|------------|------|-------------|--------|\n| List all segments | `list_segments` | `/policy/api/v1/infra/segments` | GET |\n| Get segment details (includes its ports) | `get_segment` | `/policy/api/v1/infra/segments/{id}` + `/ports` | GET |\n| Create segment | `create_segment` | `/policy/api/v1/infra/segments/{id}` | PUT |\n| Update segment | `update_segment` | `/policy/api/v1/infra/segments/{id}` | PATCH |\n| Delete segment | `delete_segment` | Pre-check (GET): `/policy/api/v1/infra/segments/{id}` (identity, gateway, subnets) and `/policy/api/v1/infra/segments/{id}/ports` — refuses, listing port ids, while any is attached. Then `/policy/api/v1/infra/segments/{id}` | GET, DELETE |\n\n**Note**: there is no standalone segment-port listing tool. Ports are returned by\n`get_segment` (attached ports + total count) and, with realized state, by\n`get_logical_port_status`.\n\n**Segment types supported**:\n- Overlay segments (Geneve encapsulation, requires overlay transport zone)\n- VLAN-backed segments (requires VLAN transport zone + VLAN ID)\n\n**Segment features**:\n- Subnet configuration (gateway CIDR)\n- DHCP configuration (static bindings, relay)\n- Connectivity to Tier-1 gateways\n- Tags and metadata\n- Admin state management\n\n### Tier-0 Gateways (4 tools — 3 read, 1 write)\n\n| Capability | Tool | API Endpoint | Method |\n|------------|------|-------------|--------|\n| List Tier-0 gateways | `list_tier0_gateways` | `/policy/api/v1/infra/tier-0s` | GET |\n| Get Tier-0 details | `get_tier0_gateway` | `/policy/api/v1/infra/tier-0s/{id}` | GET |\n| BGP config + neighbor status | `get_bgp_neighbors` | `/policy/api/v1/infra/tier-0s/{id}/locale-services`, then `.../{ls}/bgp`, `.../{ls}/bgp/neighbors`, `.../{ls}/bgp/neighbors/status` | GET |\n| Configure BGP on a Tier-0 | `configure_tier0_bgp` | `/policy/api/v1/infra/tier-0s/{id}/locale-services/{ls}/bgp` | PATCH |\n\n**Note**: Tier-0 gateways cannot be created or deleted by this skill — that is a high-impact\ninfrastructure operation normally done during initial NSX deployment. The only Tier-0 write\ntool is `configure_tier0_bgp` (local AS, ECMP, inter-SR iBGP on an existing locale-service).\nThere is **no** Tier-0 or Tier-1 route-table tool; use `list_static_routes` for configured\nstatic routes and `get_bgp_neighbors` for learned-route peering state.\n\n### Tier-1 Gateways (5 tools — 2 read, 3 write)\n\n| Capability | Tool | API Endpoint | Method |\n|------------|------|-------------|--------|\n| List Tier-1 gateways | `list_tier1_gateways` | `/policy/api/v1/infra/tier-1s` | GET |\n| Get Tier-1 details | `get_tier1_gateway` | `/policy/api/v1/infra/tier-1s/{id}` | GET |\n| Create Tier-1 | `create_tier1_gateway` | `/policy/api/v1/infra/tier-1s/{id}`, plus `.../locale-services/default` when an edge cluster is given | PUT |\n| Update Tier-1 | `update_tier1_gateway` | `/policy/api/v1/infra/tier-1s/{id}` | PATCH |\n| Delete Tier-1 | `delete_tier1_gateway` | Pre-check (GET) of `/policy/api/v1/infra/tier-1s/{id}` (identity) — refuses, listing ids, if any remain: `/policy/api/v1/infra/segments` and `/policy/api/v1/infra/lb-services` (by `connectivity_path`); under `.../tier-1s/{id}/`: `segments`, `nat/USER/nat-rules`, `static-routes`, `locale-services` (any but `default`), `locale-services/default/interfaces`, `ipsec-vpn-services`, `l2vpn-services`, `dns-forwarder`. A 404 means none; any other read error aborts without deleting. Then `.../locale-services/default` (best effort), then `/policy/api/v1/infra/tier-1s/{id}` | GET, DELETE |\n\n**Route advertisement types**:\n- `TIER1_CONNECTED` — Connected subnets\n- `TIER1_NAT` — NAT IP addresses\n- `TIER1_STATIC_ROUTES` — Static routes\n- `TIER1_LB_VIP` — Load balancer VIPs\n- `TIER1_LB_SNAT` — Load balancer SNAT IPs\n- `TIER1_DNS_FORWARDER_IP` — DNS forwarder IPs\n- `TIER1_IPSEC_LOCAL_ENDPOINT` — IPSec local endpoints\n\n### NAT (3 tools — 1 read, 2 write)\n\n| Capability | Tool | API Endpoint | Method |\n|------------|------|-------------|--------|\n| List NAT rules | `list_nat_rules` | `/policy/api/v1/infra/tier-1s/{id}/nat/USER/nat-rules` | GET |\n| Create NAT rule | `create_nat_rule` | `/policy/api/v1/infra/tier-1s/{id}/nat/USER/nat-rules/{rule}` | PUT |\n| Delete NAT rule | `delete_nat_rule` | Blast radius (GET): walks `/policy/api/v1/infra/tier-1s/{id}/nat/USER/nat-rules` for the rule. Then `/policy/api/v1/infra/tier-1s/{id}/nat/USER/nat-rules/{rule}` | GET, DELETE |\n\n**No get/update NAT tool**: read a single rule by listing the gateway's rules and filtering\nclient-side; change a rule by re-issuing `create_nat_rule` with the same `rule_id` (the\nPolicy API PUT is an idempotent upsert).\n\n**NAT action types**:\n- `SNAT` — Source NAT (outbound traffic)\n- `DNAT` — Destination NAT (inbound traffic)\n- `REFLEXIVE` — Stateless bidirectional NAT\n- `NO_SNAT` — Exempt from SNAT\n- `NO_DNAT` — Exempt from DNAT\n\n**Tier-1 only**: the NAT tools address `/tier-1s/` exclusively — the gateway id parameter is\n`tier1_id` and the path is not switched by gateway type. Tier-0 NAT is not reachable through\nthis skill.\n\n### Static Routes (3 tools — 1 read, 2 write)\n\n| Capability | Tool | API Endpoint | Method |\n|------------|------|-------------|--------|\n| List static routes | `list_static_routes` | `/policy/api/v1/infra/tier-{0,1}s/{id}/static-routes` | GET |\n| Create static route | `create_static_route` | `/policy/api/v1/infra/tier-{0,1}s/{id}/static-routes/{route}` | PUT |\n| Delete static route | `delete_static_route` | Blast radius (GET): walks `/policy/api/v1/infra/tier-{0,1}s/{id}/static-routes` for the route. Then `/policy/api/v1/infra/tier-{0,1}s/{id}/static-routes/{route}` | GET, DELETE |\n\nUnlike NAT, these three do select `tier-0s` or `tier-1s` from the gateway type argument.\n\n### IP Pools (4 tools — 2 read, 2 write)\n\n| Capability | Tool | API Endpoint | Method |\n|------------|------|-------------|--------|\n| List pools | `list_ip_pools` | `/policy/api/v1/infra/ip-pools` | GET |\n| Get allocations for one pool | `get_ip_pool_usage` | `/policy/api/v1/infra/ip-pools/{id}/ip-allocations` | GET |\n| Create pool (with one static subnet) | `create_ip_pool` | `/policy/api/v1/infra/ip-pools/{id}`, then `.../ip-subnets/{subnet}` | PUT |\n| Delete pool | `delete_ip_pool` | Blast radius (GET): walks `/policy/api/v1/infra/ip-pools` for the pool, then `/policy/api/v1/infra/ip-pools/{id}/ip-allocations` — refuses, listing addresses, while any is allocated; also refuses while the pool's `pool_usage.allocated_ip_allocations` is above zero or unreadable. Then `/policy/api/v1/infra/ip-pools/{id}` | GET, DELETE |\n\n**Note**: subnet creation is not a separate tool — `create_ip_pool` writes the pool and its\none static subnet + allocation range in a single call. It is two PUTs, not atomic: if the\nsubnet PUT fails, the pool exists without it and the call returns a top-level `error` saying\nso (audited as a failure), with the cleanup — `delete_ip_pool`, then create again.\n\n**IP pool use cases**:\n- TEP (Tunnel Endpoint) IP assignment\n- SNAT IP pool for gateways\n- Load balancer VIP pools\n- Custom automation IP management\n\n### Fabric Inventory (3 tools — 3 read, 0 write)\n\n| Capability | Tool | API Endpoint | Method |\n|------------|------|-------------|--------|\n| List transport zones | `list_transport_zones` | `/policy/api/v1/infra/sites/default/enforcement-points/default/transport-zones` | GET |\n| List transport nodes | `list_transport_nodes` | `/api/v1/transport-nodes` | GET |\n| List edge clusters | `list_edge_clusters` | `/api/v1/edge-clusters` | GET |\n\n### Health (4 tools — 4 read, 0 write)\n\n| Capability | Tool | API Endpoint | Method |\n|------------|------|-------------|--------|\n| NSX alarms at one severity | `list_nsx_alarms` | `/api/v1/alarms` | GET |\n| Transport node status | `get_transport_node_status` | `/api/v1/transport-nodes/{id}/status` | GET |\n| Edge cluster status | `get_edge_cluster_status` | `/api/v1/edge-clusters/{id}/status` | GET |\n| Manager cluster status | `get_nsx_manager_status` | `/api/v1/cluster/status` | GET |\n\n### Troubleshooting (2 tools — 2 read, 0 write)\n\n| Capability | Tool | API Endpoint | Method |\n|------------|------|-------------|--------|\n| Realized state of all ports on a segment | `get_logical_port_status` | `/policy/api/v1/infra/segments/{id}` + `/ports`, then `/ports/{port}/state` per port | GET |\n| VM-to-segment lookup by display name | `get_segment_port_for_vm` | `/api/v1/fabric/virtual-machines`, `/api/v1/fabric/vifs`, then `/policy/api/v1/search/query` (falls back to scanning `/policy/api/v1/infra/segments/{id}/ports`) | GET |\n\n**Note**: Health and troubleshooting tools use a mix of Policy API and Management API endpoints. The Management API is used where the Policy API does not yet expose equivalent realized-state or status information (alarms, transport node status, fabric VM/VIF discovery).\n\n### Tool Count Summary\n\n| Category | Tools | Read | Write |\n|----------|:-----:|:----:|:-----:|\n| Segments | 5 | 2 | 3 |\n| Tier-0 Gateways | 4 | 3 | 1 |\n| Tier-1 Gateways | 5 | 2 | 3 |\n| NAT | 3 | 1 | 2 |\n| Static Routes | 3 | 1 | 2 |\n| IP Pools | 4 | 2 | 2 |\n| Fabric Inventory | 3 | 3 | 0 |\n| Health | 4 | 4 | 0 |\n| Troubleshooting | 2 | 2 | 0 |\n| **Total** | **33** | **20** | **13** |\n\n## NSX Version Compatibility\n\n| NSX Version | Support Level | Notes |\n|-------------|--------------|-------|\n| NSX 9.1 | Full | Policy API supported. Note: VDS 7.0+ required (N-VDS removed in NSX 9). |\n| NSX 9.0 | Full | Policy API supported. Note: bare-metal agent / physical-server L2 overlay removed. |\n| NSX 4.2.x | Full | Latest, all features supported |\n| NSX 4.1.x | Full | All features supported |\n| NSX 4.0.x | Full | Policy API v1 fully available |\n| NSX-T 3.2.x | Full | Policy API mature, all features work |\n| NSX-T 3.1.x | Full | Minor differences in route table API response format |\n| NSX-T 3.0.x | Compatible | IP pool subnet API introduced here; older formats handled |\n| NSX-T 2.5.x | Limited | Policy API available but incomplete; some tools may fail |\n| NSX-V (6.x) | Not supported | Completely different API (SOAP-based). Use legacy tools |\n\n### VCF (VMware Cloud Foundation) Compatibility\n\n| VCF Version | Bundled NSX | Support |\n|-------------|-------------|---------|\n| VCF 9.1 | NSX 9.1 | Full |\n| VCF 9.0 | NSX 9.0 | Full |\n| VCF 5.2 | NSX 4.2.x | Full |\n| VCF 5.1 | NSX 4.1.x | Full |\n| VCF 5.0 | NSX 4.0.x | Full |\n| VCF 4.5 | NSX-T 3.2.x | Full |\n| VCF 4.4 | NSX-T 3.2.x | Full |\n| VCF 4.3 | NSX-T 3.1.x | Full |\n\n## Scope Boundaries\n\n### What This Skill Does\n\n- Network infrastructure: segments, gateways, routing, NAT, IPAM\n- Network health: alarms, transport nodes, edge clusters, manager status\n- Network troubleshooting: port status, VM-to-segment mapping\n\n### What This Skill Does NOT Do\n\n| Capability | Responsible Skill |\n|------------|-------------------|\n| Distributed Firewall (DFW) rules | `vmware-nsx-security` |\n| Security groups and policies | `vmware-nsx-security` |\n| IDS/IPS configuration | `vmware-nsx-security` |\n| URL filtering | `vmware-nsx-security` |\n| Service insertion / east-west security | `vmware-nsx-security` |\n| VM lifecycle (power, deploy, guest ops) | `vmware-aiops` |\n| vSphere inventory and health | `vmware-monitor` |\n| Storage (datastores, iSCSI, vSAN) | `vmware-storage` |\n| Tanzu Kubernetes | `vmware-vks` |\n| Load balancing | Future skill or NSX ALB |\n| VPN (IPSec / L2VPN) | Future skill |\n| NSX Intelligence / Network Detection and Response | Future skill |\n\n## Rate Limiting and Pagination\n\n- NSX Policy API supports pagination via `cursor` and `page_size` parameters\n- Default page size: 1000 objects (configurable)\n- List operations automatically paginate through all results\n- NSX Manager has built-in rate limiting; the skill respects `429 Too Many Requests` responses with automatic backoff\n- Recommendation: for environments with >500 segments or >200 gateways, use targeted `get` operations instead of `list`\n\n### List Result Envelope\n\nEvery list-returning tool wraps its rows in the family envelope\n(`vmware_policy.paginated`) rather than returning a bare array, so an agent can\ntell a complete answer from page one instead of guessing (VMware-AIops issue\n#31). Keys: `items`, `returned`, `limit`, `total`, `truncated`, `hint` — always\nall six, with explicit `null` where a value is unknown — plus the `next_offset`\nextra. Example payload:\n\n```json\n{\n \"items\": [ ... ],\n \"returned\": 50,\n \"limit\": 50,\n \"total\": 412,\n \"truncated\": true,\n \"next_offset\": 50,\n \"hint\": \"Showing rows 0-49 of 412. Continue at offset 50 for the next page, or narrow the query with a filter.\"\n}\n```\n\n`next_offset` is the stop signal, and `truncated` is not. `truncated` answers\n\"is `items` the whole collection?\", which is still `true` on the last page of a\nwalk — rows 400-411 of 412 are not 412 rows. A loop driven by `truncated` never\nterminates; a loop driven by `next_offset is null` ends on the last page.\n\n`hint` is written for that same distinction. Mid-walk it names the offset to\npass back; on the last page it says there is no next page, and on a page past\nthe end it says the offset is past the end and to start again at 0. It never\ntells you to raise a limit that cannot return another row.\n\n`total` is the collection's `result_count` from the NSX ListResult. It is read\nfrom the pages `get_all` already fetched (via `CollectionTotal`), so it costs no\nextra round trip, and it stays `null` — never inferred — when the API omits the\nfield.\n\n| Tool | Bound | `total` source |\n|------|-------|---------------|\n| `list_segments` | `limit` (default 50) | `result_count` on `/policy/api/v1/infra/segments` |\n| `list_tier0_gateways` | `limit` (default 50) | `result_count` on `/policy/api/v1/infra/tier-0s` |\n| `list_tier1_gateways` | `limit` (default 50) | `result_count` on `/policy/api/v1/infra/tier-1s` |\n| `list_transport_zones` | `limit` (default 50) | `result_count` on the enforcement-point transport-zones path |\n| `list_transport_nodes` | `limit` (default 50) | `result_count` on `/api/v1/transport-nodes` |\n| `list_edge_clusters` | `limit` (default 50) | `result_count` on `/api/v1/edge-clusters` |\n| `list_nat_rules` | `limit` (default 50) | `result_count` on the Tier-1's `/nat/USER/nat-rules` |\n| `list_static_routes` | `limit` (default 50) | `result_count` on the gateway's `/static-routes` |\n| `list_ip_pools` | `limit` (default 50) | `result_count` on `/policy/api/v1/infra/ip-pools` |\n| `list_nsx_alarms` | none — every alarm at the severity | `result_count` on `/api/v1/alarms`; exceeds `returned` only when the 1000-item client backstop cut the walk short |\n\nBecause `total` is normally present, a page filled exactly to the limit is\nrecognised as complete when it matches the collection size, rather than being\nconservatively flagged truncated. When `total` is `null` (older APIs that omit\n`result_count`), a page filled exactly to the limit is conservatively flagged\ntruncated and may in fact be complete. CLI commands unwrap `items` and print\nthe rows; the envelope is the MCP/library contract.\n\n## Authentication\n\nThe skill authenticates to NSX Manager using HTTP Basic Authentication over HTTPS. This is the standard authentication method for the NSX Policy API.\n\n**Supported authentication methods**:\n- Local NSX Manager credentials (admin user)\n- vIDM-backed credentials (when NSX Manager is integrated with Identity Manager)\n- Principal Identity certificates (configure `cert_path` and `key_path` in config.yaml instead of password)\n\n**Session management**: Each API call creates an independent HTTPS request with Basic Auth headers. No persistent sessions are maintained, which simplifies connection pooling and avoids session timeout issues.\n\nFile v1.10.0:references/cli-reference.md\n\n# CLI Reference\n\nComplete command reference for the `vmware-nsx` CLI. Command groups:\n`inventory`, `networking`, `health`, `troubleshoot` (read-only) and\n`segment`, `gateway`, `nat`, `route`, `ip-pool` (write), plus `doctor`,\n`mcp`, and `mcp-config`.\n\n## Global Options\n\nAll commands accept these options:\n\n| Option | Description |\n|--------|-------------|\n| `--target`, `-t ` | Target name from `~/.vmware-nsx/config.yaml` (defaults to the configured default target) |\n| `--config`, `-c ` | Override config file path |\n| `--help` | Show command help |\n\nWrite commands additionally accept:\n\n| Option | Description |\n|--------|-------------|\n| `--dry-run` | Print the API call that would be made without executing it |\n\n**Error handling**: operational failures (connection refused, HTTP 4xx/5xx\nfrom NSX Manager, missing config) print a single red `Error: ...` line with\na remediation hint and exit with code 1 — no Python traceback.\n\n---\n\n## Inventory Commands (read-only)\n\n### `inventory list-segments`\n\n\n\nArchive v1.9.1: 8 files, 32885 bytes\n\nFiles: evals/evals.json (1283b), references/agent-guardrails.md (8636b), references/capabilities.md (18845b), references/cli-reference.md (12335b), references/setup-guide.md (15435b), skill-card.md (2590b), SKILL.md (23476b), _meta.json (129b)\n\nArchive v1.9.0: 8 files, 32945 bytes\n\nFiles: evals/evals.json (1283b), references/agent-guardrails.md (8636b), references/capabilities.md (18845b), references/cli-reference.md (12335b), references/setup-guide.md (15435b), skill-card.md (2814b), SKILL.md (23476b), _meta.json (129b)\n\nArchive v1.8.16: 8 files, 30515 bytes\n\nFiles: evals/evals.json (1283b), references/agent-guardrails.md (8541b), references/capabilities.md (17641b), references/cli-reference.md (11709b), references/setup-guide.md (13547b), skill-card.md (2442b), SKILL.md (21669b), _meta.json (130b)\n\nArchive v1.8.15: 8 files, 30553 bytes\n\nFiles: evals/evals.json (1283b), references/agent-guardrails.md (8541b), references/capabilities.md (17641b), references/cli-reference.md (11709b), references/setup-guide.md (13547b), skill-card.md (2502b), SKILL.md (21669b), _meta.json (130b)\n\nArchive v1.8.14: 8 files, 30623 bytes\n\nFiles: evals/evals.json (1283b), references/agent-guardrails.md (8541b), references/capabilities.md (17641b), references/cli-reference.md (11709b), references/setup-guide.md (13547b), skill-card.md (2665b), SKILL.md (21669b), _meta.json (130b)\n\nArchive v1.8.13: 8 files, 30560 bytes\n\nFiles: evals/evals.json (1283b), references/agent-guardrails.md (8541b), references/capabilities.md (17641b), references/cli-reference.md (11709b), references/setup-guide.md (13547b), skill-card.md (2470b), SKILL.md (21669b), _meta.json (130b)\n\nArchive v1.8.12: 8 files, 30044 bytes\n\nFiles: evals/evals.json (1283b), references/agent-guardrails.md (8430b), references/capabilities.md (16948b), references/cli-reference.md (11709b), references/setup-guide.md (13547b), skill-card.md (2300b), SKILL.md (21530b), _meta.json (130b)\n\nArchive v1.8.11: 8 files, 30089 bytes\n\nFiles: evals/evals.json (1283b), references/agent-guardrails.md (8430b), references/capabilities.md (16948b), references/cli-reference.md (11709b), references/setup-guide.md (13547b), skill-card.md (2420b), SKILL.md (21530b), _meta.json (130b)","readmeExcerpt":"Skill: vmware-nsx Owner: zw008 Summary: Use this skill when the user needs to inspect or manage VMware NSX networking through NSX Manager — segments, Tier-0/Tier-1 gateways, NAT, static routes/BGP, and IP pools. Directly handles: list and inspect segments, gateways, NAT rules, routes and IP pools; check transport node, edge cluster and manager health; find a VM's segment. Changes (create/update/delete segments, Tier-","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"uv tool install vmware-nsx-mgmt==1.11.0\nvmware-nsx init # guided setup: writes config + .env (chmod 600, password grep-safe), then verifies\nvmware-nsx doctor"},{"language":"bash","snippet":"# Inventory (read-only)\nvmware-nsx inventory list-segments [--target ]\nvmware-nsx inventory get-segment \nvmware-nsx inventory list-tier0s\nvmware-nsx inventory get-tier0 \nvmware-nsx inventory list-tier1s\nvmware-nsx inventory get-tier1 \nvmware-nsx inventory list-transport-zones\nvmware-nsx inventory list-transport-nodes\nvmware-nsx inventory list-edge-clusters\n\n# Networking (read-only)\nvmware-nsx networking list-nat-rules \nvmware-nsx networking bgp-neighbors \nvmware-nsx networking list-static-routes \nvmware-nsx networking list-ip-pools\nvmware-nsx networking ip-pool-usage \n\n# Segment management (write; full option lists in references/cli-reference.md)\nvmware-nsx segment create --name --tz [--vlan|--subnet] [--dry-run]\nvmware-nsx segment update [--name|--subnet] [--dry-run]\nvmware-nsx segment delete [--dry-run]\n\n# Gateway management (write)\nvmware-nsx gateway create-tier1 --name [--tier0|--edge-cluster] [--dry-run]\nvmware-nsx gateway update-tier1 [--name|--tier0|--advertise] [--dry-run]\nvmware-nsx gateway delete-tier1 [--dry-run]\nvmware-nsx gateway configure-tier0-bgp --local-as [--ecmp] [--dry-run]\n\n# NAT (write)\nvmware-nsx nat create-rule --tier1 --rule-id --action SNAT --source --translated [--dry-run]\nvmware-nsx nat delete-rule --tier1 --rule-id [--dry-run]\n\n# Static routes (write)\nvmware-nsx route create-static --tier1 --route-id --network --next-hop [--dry-run]\nvmware-nsx route delete-static --tier1 --route-id [--dry-run]\n\n# IP pools (write)\nvmware-nsx ip-pool create --name --start --end --cidr [--dry-run]\n\n# Health & Troubleshooting (read-only)\nvmware-nsx health alarms [--severity CRITICAL]\nvmware-nsx health transport-node-status \nvmware-nsx health edge-cluster-status \nvmware-nsx health manager-status\nv"},{"language":"bash","snippet":"uv tool install vmware-nsx-mgmt==1.11.0\nvmware-nsx init # writes ~/.vmware-nsx/config.yaml + .env (chmod 600), then verifies\nvmware-nsx doctor"},{"language":"text","snippet":"User (natural language)\n |\nAI Agent (Claude Code / Goose / Cursor)\n | reads SKILL.md\nvmware-nsx CLI or MCP server (stdio transport)\n | NSX Policy API (REST/JSON over HTTPS)\nNSX Manager\n |\nSegments / Gateways / NAT / Routes / IP Pools / Transport Nodes"},{"language":"text","snippet":"## Tool use\n\n- Always call an MCP tool before answering any question about the current NSX\n environment. Never answer from memory or assumption.\n- Never describe a tool call, and never output a JSON example, instead of\n executing the tool. If you intend to call a tool, call it.\n- If a tool fails, report the actual error text. Do not complete the answer\n with assumptions about what the result would have been.\n- Use explicit limits on queries that may return large amounts of data. Do not\n request unlimited results unless the user asks for them.\n- Every tool accepts an optional target. When more than one NSX Manager is\n configured, name the target explicitly rather than relying on the default.\n\n## Skill routing\n\n- vmware-nsx: segments, Tier-0 and Tier-1 gateways, BGP, NAT, static routes,\n IP pools, transport zones and nodes, edge clusters, NSX alarms.\n- vmware-nsx-security: DFW policies and rules, security groups, VM tags,\n IDS/IPS, Traceflow. Firewall work is not this skill.\n- vmware-monitor: read-only vCenter inventory, hosts, alarms, events.\n- vmware-aiops: VM lifecycle.\n- vmware-avi: load balancing, virtual services, pools, AKO.\n- vmware-pilot: multi-step workflows that need approval gates.\n\n## Data fidelity\n\n- Never invent segments, gateways, routes, pools, IP addresses or ASNs. If a\n tool did not return it, it does not exist for this answer.\n- Preserve the exact admin state, realization state, BGP session state and\n status values the tools return. Do not translate, normalise, or prettify\n enum values.\n- Report IP addresses, prefixes and ASNs exactly as returned. Never reformat,\n abbreviate or infer a subnet mask.\n- If a requested field was not returned, show it as \"not available\". Do not\n infer it from other fields.\n- Preserve the original order and the full set of fields when the user asks\n for specific ones.\n- When a response is long, report every item it contains. If a result is\n truncated, the tool says so explicitly — report the truncation rath"},{"language":"json","snippet":"{\n \"items\": [ ... ],\n \"returned\": 50,\n \"limit\": 50,\n \"total\": 412,\n \"truncated\": true,\n \"next_offset\": 50,\n \"hint\": \"Showing rows 0-49 of 412. Continue at offset 50 for the next page, or narrow the query with a filter.\"\n}"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: vmware-nsx\ndescription: >\n Use this skill when the user needs to inspect or manage VMware NSX networking through NSX Manager — segments, Tier-0/Tier-1 gateways, NAT, static routes/BGP, and IP pools.\n Directly handles: list and inspect segments, gateways, NAT rules, routes and IP pools; check transport node, edge cluster and manager health; find a VM's segment. Changes (create/update/delete segments, Tier-1 gateways, NAT rules, static routes, IP pools, Tier-0 BGP) only when the user explicitly asks for that change.\n Use this skill for \"create segment\", \"set up gateway\", \"create NAT rule\", \"check network health\", \"troubleshoot connectivity\" when the context is explicitly NSX, NSX-T, or NSX Manager.\n Do NOT use for networking outside NSX, DFW firewall rules or security groups (use vmware-nsx-security), vSphere distributed port groups or host VMkernel adapters (use vmware-aiops), VM lifecycle (use vmware-aiops), or AVI/ALB load balancing (use vmware-avi).\n For multi-step workflows use vmware-pilot.\ninstaller:\n kind: uv\n package: vmware-nsx-mgmt\nallowed-tools:\n - Bash\nmetadata: {\"openclaw\":{\"requires\":{\"anyBins\":[\"vmware-nsx\",\"uvx\"]},\"optional\":{\"env\":[\"VMWARE_NSX_CONFIG\",\"VMWARE_NSX__PASSWORD\",\"VMWARE_NSX__USERNAME\",\"VMWARE_AUDIT_APPROVED_BY\"],\"bins\":[\"vmware-policy\"]},\"homepage\":\"https://github.com/vmware-skills/VMware-NSX\",\"emoji\":\"🌐\",\"os\":[\"macos\",\"linux\"]}}\ncompatibility: >\n vmware-policy auto-installed as Python dependency (provides @vmware_tool decorator and audit logging). All write operations audited to ~/.vmware/audit.db.\n Credentials: Each NSX Manager target requires a per-target password env var in ~/.vmware-nsx/.env following the pattern VMWARE_NSX__PASSWORD. Username/password session auth only (client-certificate auth is not implemented). Passwords are never logged or echoed.\n Write operations: CLI write commands require double confirmation and support --dry-run. The five MCP delete tools preview by default — without confirm=True they return the blast radius and change nothing, and confirm=True is refused while a blocker remains (attached ports, Tier-1 dependents, allocated IPs) or a read failed. Other MCP write tools execute when called and are audit-logged, so the agent must call them only on the user's explicit request; ~/.vmware/rules.yaml deny rules can block them per environment.\n VMWARE_AUDIT_APPROVED_BY is an optional attestation recorded in the audit row; it is not a gate and does not carry credentials.\n No webhooks, no outbound network calls, no guest operations. Local only: stdio MCP + NSX Policy API (HTTPS 443).\n SSL bypass: verify_ssl is on by default; trust a private CA via the SSL_CERT_FILE env var; verify_ssl false only for isolated labs with self-signed certs.\n Transitive dependencies: Only vmware-policy (audit/policy). No post-install scripts or background services.\n---\n\n# VMware NSX\n\n> **Disclaimer**: This is a community-maintained open-source project and is "},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7b067awq2s97bn3d7p5qfhw5827pxc\",\n \"slug\": \"vmware-nsx\",\n \"version\": \"1.11.0\",\n \"publishedAt\": 1789915924988\n}"},{"path":"references/agent-guardrails.md","content":"# Operating vmware-nsx with a local / small model\n\nClaude-class models drive this skill without special instruction. Smaller and\nlocally-hosted models — Llama 3.3 70B, Qwen, Mistral, and similar, served\nthrough Goose, Ollama, or OpenShift AI — need explicit operating rules to call\ntools reliably.\n\nThis page exists because an operator wrote those rules by hand first. The\nguardrails below are adapted, with thanks, from the working configuration\n[@juanpf-ha](https://github.com/juanpf-ha) developed while running\nvmware-monitor and vmware-aria against a production vSphere estate with Llama\n3.3 70B FP8 on an on-prem H100\n([VMware-AIops#31](https://github.com/vmware-skills/VMware-AIops/issues/31)). The\ncross-skill rules are identical across this family; the parts below marked\nvmware-nsx are specific to this skill.\n\nvmware-nsx exposes 33 MCP tools, 13 of which change state. Network writes fail\ndifferently from other writes: deleting a segment or reconfiguring a Tier-0's\nBGP does not error, it disconnects things — often something other than the\nobject the model was looking at.\n\n> **Disclaimer**: This is a community-maintained open-source project and is\n> **not affiliated with, endorsed by, or sponsored by VMware, Inc. or Broadcom\n> Inc.** \"VMware\" and \"vSphere\" are trademarks of Broadcom.\n\n---\n\n## First: the rules you no longer need to write\n\nSeveral guardrails from the original configuration are now enforced by the\nskill itself. Prompt instructions are advisory — a model can ignore them.\nThese are structural, so it cannot.\n\n| Guardrail you would otherwise prompt for | Now enforced by |\n|---|---|\n| \"Warn me if a segment still has workloads on it before deleting\" | **`delete_segment` checks the ports first** and refuses, deleting nothing, while any is attached (it names them). The check runs server-side, not in the prompt. |\n| \"Show me what a delete would remove before it happens\" | **The five delete tools preview by default.** Without `confirm=True` they return `blast_radius` and delete nothing; `confirm=True` is refused while a blocker remains or a read failed. |\n| \"Use explicit limits for queries that may return large amounts of data\" | **The list envelope.** Every list-returning tool returns `{items, returned, limit, total, truncated, hint}`, so the model reads truncation instead of guessing at it. `truncated: true` means `items` is not the whole collection; `next_offset` (null on the last page) is what a paging loop stops on, and the `hint` says which of the two you are looking at. |\n| \"If a listing came back empty, say so rather than claiming the call failed\" | Same envelope. Empty `items` with `truncated: false` means the query genuinely matched nothing — a stated result, not a silence the model has to interpret. |\n| \"Log every state change you make\" | **The `@vmware_tool` decorator.** Every write is recorded to `~/.vmware/audit.db` before the model sees the result, and policy rules are evaluated ahead of execution. |\n| \"Block state-changing writes "},{"path":"references/capabilities.md","content":"# Capabilities\n\nDetailed capability reference for `vmware-nsx`.\n\n## Automation Level Reference\n\nEach operation is classified by autonomy level per the Enterprise Harness Engineering framework:\n\n| Level | Meaning | Agent autonomy | Examples in this skill |\n|:-:|---|---|---|\n| **L1** | Read-only, raw data | Always auto-run | `list_segments`, `get_segment`, `list_tier0_gateways`, `list_tier1_gateways`, `list_nat_rules`, `list_ip_pools`, `list_static_routes`, alarms/health queries |\n| **L2** | Read + analysis / recommendation | Always auto-run | `get_bgp_neighbors`, `get_segment_port_for_vm`, `get_ip_pool_usage`, `get_logical_port_status` — correlation and utilization summaries over raw data |\n| **L3** | Single write — user must approve | Only when the user explicitly asked for that change; CLI adds double-confirm + optional `--dry-run`; the five MCP deletes preview by default and act only with `confirm=True`; segment delete refuses while ports are attached; Tier-1 delete refuses while anything still depends on the gateway; IP pool delete refuses while addresses are allocated | `create_segment`, `delete_segment`, `create_nat_rule`, `update_tier1_gateway`, `create_ip_pool`, `configure_tier0_bgp`, static route mutations |\n| **L4** | Multi-step plan / apply workflow | Plan generation auto; apply gated by user approval | *(roadmap — multi-segment rollout plans, gateway HA failover sequences)* |\n| **L5** | Auto-remediation from learned pattern | Pattern library only; requires `risk:low` + `reversible:true` + `repeatable:true` | *(roadmap — candidates: stale segment cleanup, transport-node refresh)* |\n\n**Notes**:\n- L1/L2 tools are always safe for agents to call without confirmation.\n- L3 tools always pass through the `@vmware_tool` decorator: policy check (`~/.vmware/rules.yaml` deny rules, per environment) → execute → audit log. The CLI's double-confirm and `--dry-run` do not apply to MCP calls.\n- **MCP deletes preview by default** (`delete_segment`, `delete_tier1_gateway`, `delete_nat_rule`, `delete_static_route`, `delete_ip_pool`). A call without `confirm=True` reads what the delete would remove and returns `{\"action\": \"preview\", \"blast_radius\": {...}}`, deleting nothing. `blast_radius` names the object and what it measured — a segment's gateway, subnets, `port_count`/`port_ids`; a Tier-1's `tier0_path`, the `default` locale-service and edge cluster it removes, and its `dependents` by kind; a NAT rule's gateway, action, match and translation; a route's gateway, network and next hops; a pool's `pool_usage`, `allocation_count` (Policy ip-allocations), `realized_allocation_count` (NSX's `pool_usage.allocated_ip_allocations`, which also counts addresses Policy does not list, e.g. TEP pools) and `allocated_ips` — plus `blockers` and `unmeasured`. `confirm=True` re-measures and is refused, deleting nothing, while a blocker remains (attached ports, any Tier-1 dependent, allocated IPs) or while any of those reads failed (`unmeasured` non-empty); the refusal is "},{"path":"references/cli-reference.md","content":"# CLI Reference\n\nComplete command reference for the `vmware-nsx` CLI. Command groups:\n`inventory`, `networking`, `health`, `troubleshoot` (read-only) and\n`segment`, `gateway`, `nat`, `route`, `ip-pool` (write), plus `doctor`,\n`mcp`, and `mcp-config`.\n\n## Global Options\n\nAll commands accept these options:\n\n| Option | Description |\n|--------|-------------|\n| `--target`, `-t ` | Target name from `~/.vmware-nsx/config.yaml` (defaults to the configured default target) |\n| `--config`, `-c ` | Override config file path |\n| `--help` | Show command help |\n\nWrite commands additionally accept:\n\n| Option | Description |\n|--------|-------------|\n| `--dry-run` | Print the API call that would be made without executing it |\n\n**Error handling**: operational failures (connection refused, HTTP 4xx/5xx\nfrom NSX Manager, missing config) print a single red `Error: ...` line with\na remediation hint and exit with code 1 — no Python traceback.\n\n---\n\n## Inventory Commands (read-only)\n\n### `inventory list-segments`\n\nList all network segments with type, subnet, admin state, and port count.\n\n```bash\nvmware-nsx inventory list-segments\nvmware-nsx inventory list-segments --target nsx-prod\n```\n\n### `inventory get-segment`\n\nGet detailed info for a specific segment.\n\n```bash\nvmware-nsx inventory get-segment app-web-seg\n```\n\n| Argument | Required | Description |\n|----------|:--------:|-------------|\n| `segment_id` | Yes | Segment ID (Policy API ID, not display name) |\n\n### `inventory list-tier0s`\n\nList all Tier-0 gateways with HA mode and transit subnets.\n\n```bash\nvmware-nsx inventory list-tier0s\n```\n\n### `inventory get-tier0`\n\nGet detailed info for a Tier-0 gateway.\n\n```bash\nvmware-nsx inventory get-tier0 tier0-gw\n```\n\n### `inventory list-tier1s`\n\nList all Tier-1 gateways with linked Tier-0 path and route advertisement.\n\n```bash\nvmware-nsx inventory list-tier1s\n```\n\n### `inventory get-tier1`\n\nGet detailed info for a Tier-1 gateway.\n\n```bash\nvmware-nsx inventory get-tier1 app-t1\n```\n\n### `inventory list-transport-zones`\n\nList all transport zones with type (OVERLAY / VLAN).\n\n```bash\nvmware-nsx inventory list-transport-zones\n```\n\n### `inventory list-transport-nodes`\n\nList all transport nodes with node type and status.\n\n```bash\nvmware-nsx inventory list-transport-nodes\n```\n\n### `inventory list-edge-clusters`\n\nList all edge clusters with member count and deployment type.\n\n```bash\nvmware-nsx inventory list-edge-clusters\n```\n\n---\n\n## Networking Commands (read-only)\n\n### `networking list-nat-rules`\n\nList NAT rules on a Tier-1 gateway.\n\n```bash\nvmware-nsx networking list-nat-rules app-t1\n```\n\n| Argument | Required | Description |\n|----------|:--------:|-------------|\n| `tier1_id` | Yes | Tier-1 gateway ID |\n\n### `networking bgp-neighbors`\n\nShow BGP neighbors for a Tier-0 gateway, including realized session state,\nremote ASN, hold/keep-alive timers, and prefix counts.\n\n```bash\nvmware-nsx networking bgp-neighbors tier0-gw\n```\n\n| Argument | Required | Description |\n|----------|:--"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":2300,"uniquenessScore":39,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T04:35:55.093Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T04:35:55.093Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-09T16:25:47.988Z","emptyReason":null},"items":[{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-10T18:48:31.762Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}