PowerShell Module (PSVergeOS)

PSVergeOS is a cross-platform PowerShell module that provides over 200 cmdlets for managing VergeOS infrastructure through the REST API. If your team already uses PowerShell for Windows Server, Active Directory, or VMware management, PSVergeOS lets you extend those same workflows and scripting patterns to VergeOS — with full pipeline support, tab completion, and the familiar Verb-Noun cmdlet naming convention.

Requirements & Installation

Requirement	Version
PowerShell	7.4 or later
VergeOS	26.0 or later
Platform	Windows, macOS, Linux

From PowerShell Gallery (Recommended)

Install-Module -Name PSVergeOS -Scope CurrentUser

Manual Installation (Development)

git clone https://github.com/verge-io/PSVergeOS.git
Import-Module ./PSVergeOS/PSVergeOS.psd1

Verify Installation

Get-Module PSVergeOS -ListAvailable
Get-Command -Module PSVergeOS | Measure-Object  # Should show 200+ cmdlets

Authentication

PSVergeOS supports multiple authentication methods to fit different environments — from interactive admin sessions to fully automated pipelines.

Interactive Credentials

Prompt for username and password at connection time:

Connect-VergeOS -Server "vergeos.example.com"
# Prompts for credentials interactively

PSCredential Object

Store credentials securely for non-interactive scripts:

$cred = Get-Credential
Connect-VergeOS -Server "vergeos.example.com" -Credential $cred

API Token

Use a pre-generated API token for automation pipelines:

Connect-VergeOS -Server "vergeos.example.com" -Token $env:VERGEOS_TOKEN

Self-Signed Certificates

For lab and development environments with self-signed certificates:

Connect-VergeOS -Server "192.168.1.100" -Token $token -SkipCertificateCheck

Caution

Only use -SkipCertificateCheck in test environments. For production systems, configure valid SSL certificates.

Multi-Server Management

PSVergeOS can manage multiple VergeOS systems from a single PowerShell session. Use the -PassThru parameter to capture connection objects and the -Server parameter to target specific systems:

# Connect to multiple systems
$prod = Connect-VergeOS -Server "prod.vergeos.local" -Token $env:PROD_TOKEN -PassThru
$dev  = Connect-VergeOS -Server "dev.vergeos.local"  -Token $env:DEV_TOKEN  -PassThru

# Query VMs on a specific server
Get-VergeVM -Server $prod
Get-VergeVM -Server $dev

# Switch the default connection
Set-VergeConnection -Server "prod.vergeos.local"

This is particularly valuable for MSPs managing multiple customer environments or organizations with separate production and development VergeOS clusters.

Cmdlet Categories

The module organizes its 200+ cmdlets into functional categories. Each category covers the full CRUD lifecycle plus resource-specific actions.

Category	Count	Description
Connection	4	Connect, disconnect, manage server connections
Virtual Machines	29	Lifecycle, power control, snapshots, drives, NICs, cloning
Networking	18	Virtual networks, firewall rules, DNS, DHCP, diagnostics
VPN	15	IPSec connections/policies, WireGuard interfaces/peers
NAS & Storage	27	NAS services, volumes, CIFS/NFS shares, snapshots, sync
Tenants	18	Provisioning, snapshots, storage/network block allocation
Users & Groups	18	Account management, permissions, API keys
System	12	Clusters, nodes, licenses, settings
Certificates	5	SSL certificate management
Tags	9	Resource tagging and categorization
Webhooks	6	Event-driven automation hooks
Monitoring & Tasks	7	Alarms, logs, async task tracking
Backup & DR	15	Snapshot profiles, cloud snapshots, site management, sync
Files & Media	6	ISO management, file uploads
Resource Groups	1	Logical resource grouping

VPN Cmdlets (IPSec & WireGuard)

The VPN category deserves special attention — PSVergeOS provides full management for both IPSec and WireGuard VPN implementations:

IPSec:

• New-VergeIPSecConnection / Get-VergeIPSecConnection / Remove-VergeIPSecConnection
• New-VergeIPSecPolicy / Get-VergeIPSecPolicy / Remove-VergeIPSecPolicy

WireGuard:

• New-VergeWireGuardInterface / Get-VergeWireGuardInterface / Remove-VergeWireGuardInterface
• New-VergeWireGuardPeer / Get-VergeWireGuardPeer / Remove-VergeWireGuardPeer

Pipeline Support

One of PSVergeOS’s biggest strengths is full PowerShell pipeline support. Cmdlets accept pipeline input and produce pipeline output, enabling concise one-liners for bulk operations:

# Stop all development VMs
Get-VergeVM -Name "Dev-*" | Stop-VergeVM -Confirm:$false

# Snapshot all production VMs
Get-VergeVM -Name "Prod-*" | ForEach-Object {
    New-VergeVMSnapshot -VMName $_.Name -Name "Daily-$(Get-Date -Format 'yyyyMMdd')"
}

# Power on all VMs in a specific network
Get-VergeVM | Where-Object { $_.Network -eq "app-network" } | Start-VergeVM

Pipeline support makes PSVergeOS particularly effective for scheduled maintenance tasks integrated with Windows Task Scheduler or Linux cron jobs.

Practical Examples

Bulk Snapshot with Retention

# Connect to the VergeOS system
Connect-VergeOS -Server "vergeos.example.com" -Token $env:VERGEOS_TOKEN

# Snapshot all running production VMs with a 24-hour retention
$vms = Get-VergeVM -Name "Prod-*" | Where-Object { $_.PowerState -eq "Running" }

foreach ($vm in $vms) {
    $snapshot = New-VergeVMSnapshot -VMName $vm.Name `
        -Name "Nightly-$(Get-Date -Format 'yyyyMMdd-HHmm')" `
        -Retention 86400
    Write-Host "Snapshotted $($vm.Name): $($snapshot.Name)"
}

Write-Host "Completed $($vms.Count) snapshots"

VM Inventory CSV Export

# Export complete VM inventory to CSV for reporting
Get-VergeVM | Select-Object Name, PowerState, RAM, CPUCores, OS,
    @{N='DiskGB'; E={[math]::Round($_.DiskSize / 1GB, 2)}},
    Created, Description |
    Export-Csv -Path "vm-inventory-$(Get-Date -Format 'yyyyMMdd').csv" -NoTypeInformation

Write-Host "Inventory exported to vm-inventory-$(Get-Date -Format 'yyyyMMdd').csv"

Network Creation with Firewall Rules

# Create an internal network with DHCP and firewall rules
$network = New-VergeNetwork -Name "web-tier" `
    -NetworkAddress "10.20.1.0/24" `
    -IPAddress "10.20.1.1" `
    -DHCPEnabled $true

# Add firewall rules
New-VergeNetworkRule -Network $network.Name `
    -Name "Allow HTTPS" -Action Accept -Protocol TCP -DestPort 443

New-VergeNetworkRule -Network $network.Name `
    -Name "Allow SSH" -Action Accept -Protocol TCP -DestPort 22

# Apply the rules and power on
Invoke-VergeNetworkApplyRules -Network $network.Name
Start-VergeNetwork -Name $network.Name

Write-Host "Network '$($network.Name)' is online with firewall rules applied"

Multi-Tenant Resource Report

# Generate a resource summary across all tenants
$report = @()

foreach ($tenant in Get-VergeTenant) {
    $tenantVMs = Get-VergeVM -Tenant $tenant.Name
    $report += [PSCustomObject]@{
        Tenant    = $tenant.Name
        VMCount   = $tenantVMs.Count
        TotalRAM  = ($tenantVMs | Measure-Object -Property RAM -Sum).Sum
        TotalCPU  = ($tenantVMs | Measure-Object -Property CPUCores -Sum).Sum
        Running   = ($tenantVMs | Where-Object PowerState -eq "Running").Count
        Stopped   = ($tenantVMs | Where-Object PowerState -ne "Running").Count
    }
}

$report | Format-Table -AutoSize
$report | Export-Csv "tenant-report.csv" -NoTypeInformation

WireGuard VPN Setup

# Create a WireGuard interface on the external network
$wgInterface = New-VergeWireGuardInterface -Network "External" `
    -Name "Remote-Access" `
    -IPAddress "10.100.0.1/24" `
    -ListenPort 51820

# Add a peer for a remote user
New-VergeWireGuardPeer -Interface $wgInterface.Name `
    -Name "Engineer-1" `
    -AllowedIPs "10.100.0.2/32" `
    -AutoGenerateConfig $true

# Apply network rules
Invoke-VergeNetworkApplyRules -Network "External"

Integration with Task Scheduler

PSVergeOS scripts integrate naturally with scheduled task systems for hands-off automation:

Windows Task Scheduler:

\Scripts\nightly-snapshot.ps1

Import-Module PSVergeOS
Connect-VergeOS -Server "vergeos.local" -Token $env:VERGEOS_TOKEN -SkipCertificateCheck
Get-VergeVM -Name "Prod-*" | ForEach-Object {
    New-VergeVMSnapshot -VMName $_.Name -Name "Nightly-$(Get-Date -Format 'yyyyMMdd')" -Retention 86400
}
Disconnect-VergeOS

Linux cron (PowerShell 7.4+):

# Run nightly at 2:00 AM
0 2 * * * /usr/bin/pwsh -File /opt/scripts/nightly-snapshot.ps1

Common Use Cases

Bulk VM Operations

Stop, start, snapshot, or migrate multiple VMs with pipeline one-liners. Ideal for maintenance windows.

Infrastructure Reporting

Export VM inventory, resource usage, and configuration data to CSV for auditing and capacity planning.

Network Automation

Create networks, configure DHCP, manage firewall rules, and set up VPN tunnels programmatically.

Scheduled Maintenance

Integrate with Task Scheduler or cron for automated snapshots, cleanup, and compliance checks.

VMware Bridge

VMware admins: PSVergeOS is the direct equivalent of PowerCLI for VergeOS. The cmdlet naming follows the same Verb-Noun convention (Get-VergeVM maps to Get-VM, New-VergeVMSnapshot maps to New-Snapshot). Pipeline patterns translate directly — Get-VM | Stop-VM becomes Get-VergeVM | Stop-VergeVM. Key differences: PSVergeOS includes built-in VPN cmdlets (IPSec and WireGuard) that PowerCLI lacks, and the multi-server -Server parameter replaces PowerCLI’s Connect-VIServer / $defaultVIServers pattern with a simpler model.

Nutanix Bridge

Nutanix admins: While Nutanix provides PowerShell cmdlets through the Nutanix Cmdlets package (e.g., Get-NTNXVM, New-NTNXVirtualMachine), PSVergeOS offers significantly broader coverage. With 200+ cmdlets vs. Nutanix’s ~50, PSVergeOS covers VPN management, NAS operations, and multi-tenant provisioning that require direct Prism API calls in the Nutanix ecosystem. The pipeline support and cmdlet consistency are comparable, but PSVergeOS’s tenant-aware cmdlets eliminate the need to reconnect to different Prism Element instances when managing multi-cluster environments.

Additional Resources

• GitHub Repository — Source code, issues, and 16 example scripts
• PowerShell Gallery — Latest release and install info
• PowerShell 7.4 Documentation — PowerShell runtime reference