Resources

pyvergeos provides resource managers for all VergeOS API endpoints. Each resource follows a consistent CRUD pattern with additional domain-specific methods.

Virtual Machines

Core VM Management

Virtual Machine resource manager.

class pyvergeos.resources.vms.VM

Bases: ResourceObject

Virtual Machine resource object.

property drives: DriveManager

Access drives attached to this VM.

property nics: NICManager

Access NICs attached to this VM.

property snapshots: VMSnapshotManager

Access snapshots for this VM.

property cloudinit_files: VMCloudInitFileManager

Access cloud-init files for this VM.

set_cloudinit_datasource(datasource)

Set the cloud-init datasource for this VM.

The datasource controls whether VergeOS attaches a virtual CD-ROM with cloud-init files to the VM. This is required for cloud-init files (Linux) or unattend.xml (Windows) to be delivered to the guest.

Parameters:

datasource (str) – Datasource type. Valid values: - “nocloud” or “NoCloud”: Enable NoCloud datasource - “config_drive_v2” or “ConfigDrive”: Enable Config Drive v2 - “none” or “”: Disable cloud-init datasource

Return type:

None

Example

>>> vm = client.vms.get(name="my-vm")
>>> # Enable cloud-init delivery
>>> vm.set_cloudinit_datasource("nocloud")
>>> # Create cloud-init files
>>> vm.cloudinit_files.create(name="/user-data", contents="...")
>>> # Disable cloud-init delivery
>>> vm.set_cloudinit_datasource("none")

property machine_key: int

Get the underlying machine key for this VM.

property stats: MachineStatsManager

Access performance stats for this VM.

Example

>>> stats = vm.stats.get()
>>> print(f"CPU: {stats.total_cpu}%, RAM: {stats.ram_used_mb}MB")

>>> # Get stats history
>>> history = vm.stats.history_short(limit=100)

property machine_status: MachineStatusManager

Access detailed operational status for this VM.

Example

>>> status = vm.machine_status.get()
>>> print(f"Status: {status.status}, Node: {status.node_name}")

property machine_logs: MachineLogManager

Access log entries for this VM.

Example

>>> logs = vm.machine_logs.list(limit=20)
>>> errors = vm.machine_logs.list(errors_only=True)

property devices: DeviceManager

Access devices (GPU, TPM, USB, PCI, SR-IOV) attached to this VM.

Returns:

DeviceManager scoped to this VM.

Example

>>> # List all devices
>>> devices = vm.devices.list()

>>> # List vGPUs only
>>> vgpus = vm.devices.list(device_type="node_nvidia_vgpu_devices")

>>> # Attach a vGPU
>>> device = vm.devices.create_vgpu(
...     resource_group=vgpu_pool.key,
...     frame_rate_limit=60,
... )

power_on(preferred_node=None)

Power on the VM.

Parameters:

preferred_node (int | None) – Node $key to start VM on.

Returns:

Self for chaining.

Raises:

ValueError – If VM is a snapshot.

Return type:

VM

power_off(force=False)

Power off the VM.

Parameters:

force (bool) – If True, forces immediate power off (like pulling the plug). If False (default), sends ACPI shutdown signal for graceful shutdown.

Returns:

Self for chaining.

Return type:

VM

reset()

Reset VM (hard reboot).

Return type:

VM

guest_reboot()

Send reboot signal to guest OS (requires guest agent).

Return type:

VM

guest_shutdown()

Send shutdown signal to guest OS (requires guest agent).

Return type:

VM

clone(name=None, preserve_macs=False)

Clone this VM.

Parameters:

• name (str | None) – Name for the clone (default: {name}_{timestamp}).

• preserve_macs (bool) – Keep original MAC addresses.

Returns:

Clone task information with new VM key.

Return type:

dict[str, Any] | None

move(node=None, cluster=None)

Move VM to a different node or cluster.

Parameters:

• node (int | None) – Target node $key.

• cluster (int | None) – Target cluster $key.

Returns:

Move task information.

Return type:

dict[str, Any] | None

migrate(preferred_node=None)

Live migrate VM to another node while keeping it running.

Parameters:

preferred_node (int | None) – Target node $key. If None, auto-selects based on resource balancing.

Returns:

Migration task information.

Return type:

dict[str, Any] | None

Note

The VM must be running for live migration. Migration progress can be monitored via the VM status field.

hibernate()

Hibernate the VM to disk.

Saves the VM’s memory state to disk and powers off. The VM can be resumed later by powering it on, which will restore the memory state.

Returns:

Hibernate task information.

Return type:

dict[str, Any] | None

restore(snapshot, preserve_macs=False, name=None)

Restore VM from a snapshot.

Parameters:

• snapshot (int) – Snapshot $key to restore from.

• preserve_macs (bool) – Keep original MAC addresses (default False).

• name (str | None) – Name for restored VM if creating a clone. If None, overwrites the current VM.

Returns:

Restore task information.

Return type:

dict[str, Any] | None

Warning

If name is not provided, this will overwrite the current VM. The VM should be powered off before restoring.

hotplug_drive(name, size, interface='virtio-scsi', media='disk', tier=1)

Hot-add a drive to a running VM.

Parameters:

• name (str) – Drive name.

• size (int) – Disk size in bytes.

• interface (str) – Drive interface type (default “virtio-scsi”). Options: virtio, virtio-scsi, ide, ahci, nvme, etc.

• media (str) – Media type (default “disk”).

• tier (int) – Preferred storage tier (1-5, default 1).

Returns:

Hotplug task information.

Return type:

dict[str, Any] | None

Note

The VM must be running and have allow_hotplug enabled.

hotplug_nic(name, network, interface='virtio')

Hot-add a NIC to a running VM.

Parameters:

• name (str) – NIC name.

• network (int) – Network $key to connect to.

• interface (str) – NIC interface type (default “virtio”). Options: virtio, e1000, e1000e, rtl8139, vmxnet3, etc.

Returns:

Hotplug task information.

Return type:

dict[str, Any] | None

Note

The VM must be running and have allow_hotplug enabled.

tag(tag_key)

Add a tag to this VM.

Parameters:

tag_key (int) – Tag $key to add.

Return type:

None

Example

>>> # Get a tag by name and add it
>>> tag = client.tags.get(name="Production", category_name="Environment")
>>> vm.tag(tag.key)

untag(tag_key)

Remove a tag from this VM.

Parameters:

tag_key (int) – Tag $key to remove.

Return type:

None

Example

>>> vm.untag(tag.key)

get_tags()

Get all tags assigned to this VM.

Returns:

List of tag info dictionaries with tag_key, tag_name, category_name.

Return type:

list[dict[str, Any]]

Example

>>> for tag_info in vm.get_tags():
...     print(f"{tag_info['category_name']}: {tag_info['tag_name']}")

favorite()

Add this VM to the current user’s favorites.

Example

>>> vm = client.vms.get(name="web-server")
>>> vm.favorite()

Return type:

None

unfavorite()

Remove this VM from the current user’s favorites.

Example

>>> vm = client.vms.get(name="web-server")
>>> vm.unfavorite()

Return type:

None

is_favorite()

Check if this VM is in the current user’s favorites.

Returns:

True if the VM is a favorite, False otherwise.

Return type:

bool

get_console_info()

Get console access information for this VM.

Returns:

Dict with console_type, host, port, url, web_url, is_available.

Return type:

dict[str, Any]

property is_running: bool

Check if VM is powered on.

property is_snapshot: bool

Check if this is a snapshot (not a running VM).

property status: str

Get VM status (running, stopped, etc.).

property node_name: str | None

Get the name of the node this VM is running on.

property cluster_name: str | None

Get the name of the cluster this VM belongs to.

class pyvergeos.resources.vms.VMManager

Bases: ResourceManager[VM]

Manager for Virtual Machine operations.

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, include_snapshots=False, **filter_kwargs)

List VMs with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (defaults to rich field set).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• include_snapshots (bool) – Include VM snapshots (default False).

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of VM objects.

Return type:

list[VM]

get(key=None, *, name=None, fields=None)

Get a single VM by key or name.

Parameters:

• key (int | None) – VM $key (ID).

• name (str | None) – VM name (will search if key not provided).

• fields (list[str] | None) – List of fields to return (defaults to rich field set).

Returns:

VM object.

Raises:

• NotFoundError – If VM not found.

• ValueError – If neither key nor name provided.

Return type:

VM

list_running()

List all running VMs.

Return type:

list[VM]

list_stopped()

List all stopped VMs.

Return type:

list[VM]

create(name, ram=1024, cpu_cores=1, description='', os_family='linux', machine_type='pc-q35-10.0', cloudinit_datasource=None, cloud_init=None, **kwargs)

Create a new VM.

Parameters:

• name (str) – VM name (required).

• ram (int) – RAM in MB (default 1024). Will be rounded UP to nearest 256MB.

• cpu_cores (int) – Number of CPU cores (default 1).

• description (str) – VM description.

• os_family (str) – OS family (linux, windows, freebsd, other).

• machine_type (str) – QEMU machine type.

• cloudinit_datasource (str | None) – Cloud-init datasource type. Valid values are “ConfigDrive” (Config Drive v2), “NoCloud”, or None (disabled, default). Automatically set to “ConfigDrive” if cloud_init files are provided.

• cloud_init (str | dict[str, str] | list[dict[str, Any]] | None) – Cloud-init file configuration for VM provisioning. Can be a string (content for /user-data), a dict mapping file names to contents (e.g., {“/user-data”: “…”, “/meta-data”: “…”}), or a list of file specs with full control. When provided, cloudinit_datasource defaults to “ConfigDrive” if not set.

• **kwargs (Any) – Additional VM properties.

Returns:

Created VM object.

Return type:

VM

Example

>>> # Simple user-data string (auto-enables ConfigDrive)
>>> vm = client.vms.create(
...     name="web-server",
...     cloud_init="#cloud-config\npackages:\n  - nginx"
... )
>>>
>>> # Multiple files as dict
>>> vm = client.vms.create(
...     name="web-server",
...     cloud_init={
...         "/user-data": "#cloud-config\npackages:\n  - nginx",
...         "/meta-data": "instance-id: web-1\nlocal-hostname: web-server"
...     }
... )
>>>
>>> # Full control with render options
>>> vm = client.vms.create(
...     name="web-server",
...     cloud_init=[
...         {"name": "/user-data", "contents": "...", "render": "Jinja2"},
...         {"name": "/meta-data", "contents": "..."}
...     ]
... )
>>>
>>> # Enable cloud-init datasource without files (files added later)
>>> vm = client.vms.create(
...     name="web-server",
...     cloudinit_datasource="ConfigDrive"
... )

VM Drives

VM Drive resource manager.

class pyvergeos.resources.drives.Drive

Bases: ResourceObject

VM Drive resource object.

property size_gb: float

Get disk size in GB.

property used_gb: float

Get used space in GB.

property interface_display: str

Get friendly interface name.

property media_display: str

Get friendly media type name.

property is_enabled: bool

Check if drive is enabled.

property is_readonly: bool

Check if drive is read-only.

class pyvergeos.resources.drives.DriveManager

Bases: ResourceManager[Drive]

Manager for VM Drive operations.

This manager is accessed through a VM object’s drives property.

__init__(client, vm)

Parameters:

• client (VergeClient)

• vm (VM)

Return type:

None

property machine_key: int

Get the machine key for this VM.

list(filter=None, fields=None, media=None, **kwargs)

List drives for this VM.

Parameters:

• filter (str | None) – Additional OData filter string.

• fields (list[str] | None) – List of fields to return.

• media (str | None) – Filter by media type (disk, cdrom, efidisk).

• **kwargs (Any) – Additional filter arguments.

Returns:

List of Drive objects.

Return type:

list[Drive]

get(key=None, *, name=None, fields=None)

Get a drive by key or name.

Parameters:

• key (int | None) – Drive $key (ID).

• name (str | None) – Drive name.

• fields (list[str] | None) – List of fields to return.

Returns:

Drive object.

Raises:

• NotFoundError – If drive not found.

• ValueError – If neither key nor name provided.

Return type:

Drive

create(size_gb=None, name=None, interface='virtio-scsi', media='disk', tier=None, description='', readonly=False, enabled=True, media_source=None)

Create a new drive for this VM.

Parameters:

• size_gb (int | None) – Disk size in GB (required for disk media).

• name (str | None) – Drive name (optional, auto-generated if not provided).

• interface (str) – Drive interface type (virtio-scsi, nvme, ahci, ide, etc.).

• media (str) – Media type (disk, cdrom, efidisk).

• tier (int | None) – Preferred storage tier (1-5).

• description (str) – Drive description.

• readonly (bool) – Make drive read-only.

• enabled (bool) – Enable drive (default True).

• media_source (int | str | None) – File key (int) or name (str) for CD-ROM media source. Used to attach ISO or other media files.

Returns:

Created Drive object.

Raises:

• ValueError – If size_gb not provided for disk media.

• ValueError – If media_source file not found (when passed as string).

Return type:

Drive

delete(key)

Delete a drive.

Parameters:

key (int) – Drive $key (ID).

Return type:

None

Note

VM should typically be powered off before removing drives.

update(key, **kwargs)

Update a drive.

Parameters:

• key (int) – Drive $key (ID).

• **kwargs (Any) – Fields to update.

Returns:

Updated Drive object.

Return type:

Drive

import_drive(file_key=None, file_name=None, name=None, interface='virtio-scsi', tier=None, preserve_drive_format=False, enabled=True)

Import a disk image file as a new drive.

Creates a new drive by importing from a disk image file (VMDK, QCOW2, VHD, VHDX, OVA, OVF, etc.). The file must already be uploaded to the VergeOS media catalog.

This is the recommended way to import VMs from OVA/OVF/VMDK files: 1. Create a new VM with client.vms.create() 2. Import the disk(s) with vm.drives.import_drive()

Parameters:

• file_key (int | None) – The $key (ID) of the disk image file to import.

• file_name (str | None) – The name of the disk image file to import. One of file_key or file_name is required.

• name (str | None) – Name for the new drive. If not specified, auto-generated.

• interface (str) – Drive interface type. Default is ‘virtio-scsi’. Valid values: virtio, ide, ahci, nvme, virtio-scsi, virtio-scsi-dedicated.

• tier (int | None) – Preferred storage tier (1-5).

• preserve_drive_format (bool) – Keep the original drive format instead of converting to raw. Default is False.

• enabled (bool) – Enable the drive. Default is True.

Returns:

Created Drive object.

Raises:

• ValueError – If neither file_key nor file_name is provided.

• ValueError – If file not found (when looking up by name).

Return type:

Drive

Example

>>> # Import a QCOW2 disk image
>>> vm = client.vms.get(name="NewServer")
>>> drive = vm.drives.import_drive(
...     file_name="debian-12-generic-amd64.qcow2",
...     interface="virtio-scsi",
...     tier=1,
... )

>>> # Import from an OVA file's disk
>>> vm = client.vms.create(name="ImportedVM", cpu_cores=2, ram=4096)
>>> drive = vm.drives.import_drive(file_name="server-disk.vmdk")

Note

Supported import formats: VMDK, QCOW2, VHD, VHDX, VDI, RAW, OVA, OVF. The import process converts the disk to VergeOS format unless preserve_drive_format is True.

VM NICs

VM NIC resource manager.

class pyvergeos.resources.nics.NIC

Bases: ResourceObject

VM NIC resource object.

property interface_display: str

Get friendly interface name.

property is_enabled: bool

Check if NIC is enabled.

property mac_address: str | None

Get MAC address.

property ip_address: str | None

Get IP address.

property network_name: str | None

Get connected network name.

property network_key: int | None

Get connected network key.

property speed_display: str | None

Get formatted speed string.

property rx_bytes: int

Get received bytes.

property tx_bytes: int

Get transmitted bytes.

class pyvergeos.resources.nics.NICManager

Bases: ResourceManager[NIC]

Manager for VM NIC operations.

This manager is accessed through a VM object’s nics property.

__init__(client, vm)

Parameters:

• client (VergeClient)

• vm (VM)

Return type:

None

property machine_key: int

Get the machine key for this VM.

list(filter=None, fields=None, **kwargs)

List NICs for this VM.

Parameters:

• filter (str | None) – Additional OData filter string.

• fields (list[str] | None) – List of fields to return.

• **kwargs (Any) – Additional filter arguments.

Returns:

List of NIC objects.

Return type:

list[NIC]

get(key=None, *, name=None, fields=None)

Get a NIC by key or name.

Parameters:

• key (int | None) – NIC $key (ID).

• name (str | None) – NIC name.

• fields (list[str] | None) – List of fields to return.

Returns:

NIC object.

Raises:

• NotFoundError – If NIC not found.

• ValueError – If neither key nor name provided.

Return type:

NIC

create(network=None, name=None, interface='virtio', mac_address=None, ip_address=None, description='', enabled=True)

Create a new NIC for this VM.

Parameters:

• network (int | str | None) – Network key (int) or name (str) to connect to.

• name (str | None) – NIC name (optional, auto-generated if not provided).

• interface (str) – NIC interface type (virtio, e1000, e1000e, etc.).

• mac_address (str | None) – MAC address (format: xx:xx:xx:xx:xx:xx).

• ip_address (str | None) – Static IP address.

• description (str) – NIC description.

• enabled (bool) – Enable NIC (default True).

Returns:

Created NIC object.

Return type:

NIC

delete(key)

Delete a NIC.

Parameters:

key (int) – NIC $key (ID).

Return type:

None

Note

VM should typically be powered off before removing NICs.

update(key, **kwargs)

Update a NIC.

Parameters:

• key (int) – NIC $key (ID).

• **kwargs (Any) – Fields to update.

Returns:

Updated NIC object.

Return type:

NIC

VM Snapshots

VM Snapshot resource manager.

class pyvergeos.resources.snapshots.VMSnapshot

Bases: ResourceObject

VM Snapshot resource object.

property created_at: datetime | None

Get creation timestamp as datetime.

property expires_at: datetime | None

Get expiration timestamp as datetime.

property never_expires: bool

Check if snapshot never expires.

property is_quiesced: bool

Check if snapshot was quiesced.

property is_manual: bool

Check if snapshot was created manually.

property snap_machine_key: int | None

Get the snap_machine key (used for restore).

property is_cloud_snapshot: bool

Check if this is a cloud snapshot.

restore(name=None, power_on=False)

Restore this snapshot to a new VM.

Parameters:

• name (str | None) – Name for the restored VM (default: “{snapshot_name} restored”).

• power_on (bool) – Power on the VM after restoration.

Returns:

Clone task information.

Return type:

dict[str, Any] | None

class pyvergeos.resources.snapshots.VMSnapshotManager

Bases: ResourceManager[VMSnapshot]

Manager for VM Snapshot operations.

This manager is accessed through a VM object’s snapshots property.

__init__(client, vm)

Parameters:

• client (VergeClient)

• vm (VM)

Return type:

None

property machine_key: int

Get the machine key for this VM.

list(filter=None, fields=None, **kwargs)

List snapshots for this VM.

Parameters:

• filter (str | None) – Additional OData filter string.

• fields (list[str] | None) – List of fields to return.

• **kwargs (Any) – Additional filter arguments.

Returns:

List of VMSnapshot objects.

Return type:

list[VMSnapshot]

get(key=None, *, name=None, fields=None)

Get a snapshot by key or name.

Parameters:

• key (int | None) – Snapshot $key (ID).

• name (str | None) – Snapshot name.

• fields (list[str] | None) – List of fields to return.

Returns:

VMSnapshot object.

Raises:

• NotFoundError – If snapshot not found.

• ValueError – If neither key nor name provided.

Return type:

VMSnapshot

create(name=None, retention=86400, quiesce=False, description='')

Create a new snapshot for this VM.

Parameters:

• name (str | None) – Snapshot name (optional, auto-generated with timestamp if not provided).

• retention (int) – Snapshot retention in seconds (default 24h). Use 0 for never expires.

• quiesce (bool) – Quiesce disk activity (requires guest agent).

• description (str) – Snapshot description.

Returns:

Created snapshot information.

Return type:

dict[str, Any] | None

delete(key)

Delete a snapshot.

Parameters:

key (int) – Snapshot $key (ID).

Return type:

None

restore(key, name=None, replace_original=False, power_on=False)

Restore a snapshot.

Parameters:

• key (int) – Snapshot $key (ID).

• name (str | None) – Name for the restored VM (only for clone mode).

• replace_original (bool) – If True, revert original VM to snapshot state. WARNING: All changes since snapshot will be lost.

• power_on (bool) – Power on VM after restoration.

Returns:

Restore task information.

Return type:

dict[str, Any] | None

VM Import/Export

Import VMs from various formats (VMDK, QCOW2, OVA, OVF) and export VMs to NAS volumes.

VM import resources for importing VMs from files.

class pyvergeos.resources.vm_imports.VmImport

Bases: ResourceObject

VM import resource object.

Represents a VM import operation for importing VMs from files (VMDK, QCOW2, OVA, OVF) or other sources.

Note

Import keys are 40-character hex strings, not integers like most other VergeOS resources.

key

The import unique identifier ($key) - 40-char hex string.

id

The import ID (same as $key).

name

VM name for the imported VM.

vm

Created VM key (after import completes).

uuid

UUID from the source VM.

file

Source file key from media catalog.

volume

Source NAS volume key.

volume_path

Path within the source volume.

status

Import status (initializing, importing, complete, aborted, error, warning).

status_info

Detailed status information.

importing

Whether import is in progress.

aborted

Whether import was aborted.

preserve_macs

Whether to preserve MAC addresses from source.

preserve_drive_format

Whether to preserve original drive format.

preferred_tier

Preferred storage tier (1-5).

timestamp

Creation timestamp.

modified

Last modified timestamp.

property key: str

Resource primary key ($key) - 40-character hex string.

Raises:

ValueError – If resource has no $key (not yet persisted).

refresh()

Refresh resource data from API.

Returns:

Updated VmImport object.

Return type:

VmImport

save(**kwargs)

Save changes to resource.

Parameters:

**kwargs (Any) – Fields to update.

Returns:

Updated VmImport object.

Return type:

VmImport

delete()

Delete this import.

Return type:

None

property is_complete: bool

Check if import completed successfully.

property is_importing: bool

Check if import is in progress.

property has_error: bool

Check if import has an error.

property vm_key: int | None

Get the created VM key (after import completes).

property logs: VmImportLogManager

Get a log manager for this import’s logs.

Returns:

VmImportLogManager scoped to this import.

Example

>>> # Browse import logs
>>> for log in vm_import.logs.list():
...     print(f"{log.level}: {log.text}")

start()

Start the import operation.

Returns:

Task information dict or None.

Return type:

dict[str, Any] | None

abort()

Abort the import operation.

Returns:

Task information dict or None.

Return type:

dict[str, Any] | None

class pyvergeos.resources.vm_imports.VmImportLog

Bases: ResourceObject

VM import log entry resource object.

Represents a log entry for a VM import operation.

key

The log entry key ($key).

vm_import

Parent import key.

level

Log level (message, warning, error, critical, debug, summary).

text

Log message text.

timestamp

Log entry timestamp.

user

User who initiated the action.

property is_error: bool

Check if this is an error log entry.

property is_warning: bool

Check if this is a warning log entry.

class pyvergeos.resources.vm_imports.VmImportManager

Bases: ResourceManager[VmImport]

Manager for VM import operations.

VM imports allow importing VMs from files (VMDK, QCOW2, OVA, OVF) or from NAS volumes.

Example

>>> # List all imports
>>> for imp in client.vm_imports.list():
...     print(f"{imp.name}: {imp.status}")

>>> # Get a specific import
>>> imp = client.vm_imports.get(key="abc123...")

>>> # Create an import from a file
>>> imp = client.vm_imports.create(
...     name="imported-vm",
...     file=123,  # file key from media catalog
...     preferred_tier="1"
... )

>>> # Start the import
>>> imp.start()

>>> # Monitor import logs
>>> for log in imp.logs.list():
...     print(f"{log.level}: {log.text}")

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, status=None, **filter_kwargs)

List VM imports with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• status (str | None) – Filter by status (initializing, importing, complete, aborted, error).

• **filter_kwargs (Any) – Shorthand filter arguments (name, etc.).

Returns:

List of VmImport objects.

Return type:

list[VmImport]

Example

>>> # List all imports
>>> imports = client.vm_imports.list()

>>> # List active imports
>>> active = client.vm_imports.list(status="importing")

>>> # List completed imports
>>> done = client.vm_imports.list(status="complete")

get(key=None, *, name=None, fields=None)

Get a single VM import by key or name.

Parameters:

• key (str | None) – Import $key (40-character hex string).

• name (str | None) – Import name (VM name).

• fields (list[str] | None) – List of fields to return.

Returns:

VmImport object.

Raises:

• NotFoundError – If import not found.

• ValueError – If no identifier provided.

Return type:

VmImport

Example

>>> # Get by key
>>> imp = client.vm_imports.get("8f73f8bcc9c9f1aaba32f733bfc295acaf548554")

>>> # Get by name
>>> imp = client.vm_imports.get(name="imported-vm")

create(name, *, file=None, volume=None, volume_path=None, shared_object=None, preserve_macs=True, preserve_drive_format=False, preferred_tier=None, no_optical_drives=False, override_drive_interface=None, override_nic_interface=None, cleanup_on_delete=False, importing=False)

Create a new VM import.

Parameters:

• name (str) – Name for the imported VM.

• file (int | None) – Source file key from media catalog (for file imports).

• volume (str | None) – Source NAS volume key (for volume imports).

• volume_path (str | None) – Path within the source volume.

• shared_object (int | None) – Shared object key (for tenant imports).

• preserve_macs (bool) – Preserve MAC addresses from source (default True).

• preserve_drive_format (bool) – Preserve original drive format instead of converting to optimized .raw format (default False).

• preferred_tier (str | None) – Preferred storage tier (1-5).

• no_optical_drives (bool) – Do not create optical drives (default False).

• override_drive_interface (str | None) – Override drive interface type.

• override_nic_interface (str | None) – Override NIC interface type.

• cleanup_on_delete (bool) – Clean up import file path on delete.

• importing (bool) – Auto-start the import immediately after creation (default False).

Returns:

Created VmImport object.

Raises:

ValueError – If no source (file, volume, or shared_object) provided.

Return type:

VmImport

Example

>>> # Import from media catalog file (auto-start)
>>> imp = client.vm_imports.create(
...     name="imported-vm",
...     file=123,
...     preferred_tier="1",
...     importing=True
... )

>>> # Import from NAS volume (two-step: create then start)
>>> imp = client.vm_imports.create(
...     name="imported-vm",
...     volume="abc123...",
...     volume_path="/exports/vm.vmdk"
... )
>>> imp.start()

update(key, *, name=None, vm=None, preserve_macs=None, preserve_drive_format=None, preferred_tier=None, no_optical_drives=None, override_drive_interface=None, override_nic_interface=None)

Update a VM import.

Parameters:

• key (str) – Import $key (40-character hex string).

• name (str | None) – New VM name.

• vm (int | None) – Associated VM key.

• preserve_macs (bool | None) – Preserve MAC addresses.

• preserve_drive_format (bool | None) – Preserve original drive format.

• preferred_tier (str | None) – Preferred storage tier (1-5).

• no_optical_drives (bool | None) – Do not create optical drives.

• override_drive_interface (str | None) – Override drive interface type.

• override_nic_interface (str | None) – Override NIC interface type.

Returns:

Updated VmImport object.

Return type:

VmImport

delete(key)

Delete a VM import.

Parameters:

key (str) – Import $key (40-character hex string).

Return type:

None

Example

>>> client.vm_imports.delete(imp.key)

start_import(key)

Start a VM import operation.

This initiates the actual import process for an import that has been created but not yet started.

Parameters:

key (str) – Import $key (40-character hex string).

Returns:

Task information dict or None.

Return type:

dict[str, Any] | None

Example

>>> result = client.vm_imports.start_import(imp.key)
>>> if result and "task" in result:
...     client.tasks.wait(result["task"])

abort_import(key)

Abort a VM import operation.

This stops an in-progress import.

Parameters:

key (str) – Import $key (40-character hex string).

Returns:

Task information dict or None.

Return type:

dict[str, Any] | None

Example

>>> client.vm_imports.abort_import(imp.key)

logs(key)

Get a log manager for a specific import.

Parameters:

key (str) – Import $key (40-character hex string).

Returns:

VmImportLogManager for the import.

Return type:

VmImportLogManager

Example

>>> # List logs for an import
>>> for log in client.vm_imports.logs(imp.key).list():
...     print(f"{log.level}: {log.text}")

class pyvergeos.resources.vm_imports.VmImportLogManager

Bases: ResourceManager[VmImportLog]

Manager for VM import log operations.

This manager provides access to log entries for VM imports. It can be used either standalone or scoped to a specific import.

Example

>>> # List all import logs (standalone)
>>> for log in client.vm_import_logs.list():
...     print(f"{log.level}: {log.text}")

>>> # List logs for a specific import
>>> for log in client.vm_imports.logs(imp.key).list():
...     print(f"{log.level}: {log.text}")

>>> # Get only errors
>>> errors = client.vm_imports.logs(imp.key).list(level="error")

__init__(client, *, import_key=None)

Parameters:

• client (VergeClient)

• import_key (str | None)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, level=None, vm_import=None, **filter_kwargs)

List VM import logs with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• level (str | None) – Filter by log level (message, warning, error, critical, debug).

• vm_import (str | None) – Filter by import key. Ignored if manager is scoped.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of VmImportLog objects.

Return type:

list[VmImportLog]

Example

>>> # List all logs
>>> logs = client.vm_import_logs.list()

>>> # List errors only
>>> errors = client.vm_import_logs.list(level="error")

>>> # List logs for a specific import
>>> logs = client.vm_imports.logs(imp.key).list()

get(key=None, *, fields=None)

Get a single VM import log entry by key.

Parameters:

• key (int | None) – Log entry $key (row ID).

• fields (list[str] | None) – List of fields to return.

Returns:

VmImportLog object.

Raises:

• NotFoundError – If log entry not found.

• ValueError – If key not provided.

Return type:

VmImportLog

Example

>>> log = client.vm_import_logs.get(1)

list_errors()

List only error and critical log entries.

Returns:

List of error VmImportLog objects.

Return type:

list[VmImportLog]

Example

>>> errors = client.vm_imports.logs(imp.key).list_errors()

list_warnings()

List only warning log entries.

Returns:

List of warning VmImportLog objects.

Return type:

list[VmImportLog]

Example

>>> warnings = client.vm_imports.logs(imp.key).list_warnings()

Volume VM export resources for exporting VMs to NAS volumes.

class pyvergeos.resources.volume_vm_exports.VolumeVmExport

Bases: ResourceObject

Volume VM export resource object.

Represents a VM export configuration for a NAS volume. VM exports allow exporting VMs to NAS volumes for backup/migration.

key

The export unique identifier ($key).

volume

Parent NAS volume key.

name

Volume name (derived from volume).

quiesced

Whether exports are quiesced.

status

Export status (idle, building, error, cleaning).

status_info

Detailed status information.

create_current

Whether to create ‘current’ folder with latest export.

max_exports

Maximum exports to store (1-100).

property is_idle: bool

Check if export is idle.

property is_building: bool

Check if export is building.

property has_error: bool

Check if export has an error.

property volume_key: int | None

Get the parent volume key.

property stats: VolumeVmExportStatManager

Get a stats manager for this export’s statistics.

Returns:

VolumeVmExportStatManager scoped to this export.

Example

>>> # Browse export stats
>>> for stat in export.stats.list():
...     print(f"{stat.file_name}: {stat.virtual_machines} VMs")

start(name=None, vms=None)

Start an export operation.

Parameters:

• name (str | None) – Optional export name/folder name.

• vms (list[int] | None) – Optional list of VM keys to export. If not provided, exports all.

Returns:

Action result dict or None.

Return type:

dict[str, Any] | None

stop()

Stop an in-progress export operation.

Returns:

Action result dict or None.

Return type:

dict[str, Any] | None

cleanup()

Clean up old export folders.

Returns:

Action result dict or None.

Return type:

dict[str, Any] | None

class pyvergeos.resources.volume_vm_exports.VolumeVmExportStat

Bases: ResourceObject

Volume VM export statistics resource object.

Represents statistics for a completed VM export.

key

The stat entry key ($key).

volume_vm_exports

Parent export key.

duration

Export duration in seconds.

virtual_machines

Number of VMs exported.

export_success

Number of successful exports.

errors

Number of errors.

quiesced

Whether the export was quiesced.

size_bytes

Total size in bytes.

file_name

Export folder name.

timestamp

Export timestamp.

property size_gb: float

Get the export size in GB.

property has_errors: bool

Check if the export had errors.

class pyvergeos.resources.volume_vm_exports.VolumeVmExportManager

Bases: ResourceManager[VolumeVmExport]

Manager for volume VM export operations.

Volume VM exports allow exporting VMs to NAS volumes for backup and migration purposes.

Example

>>> # List all exports
>>> for exp in client.volume_vm_exports.list():
...     print(f"{exp.name}: {exp.status}")

>>> # Get export for a volume
>>> exp = client.volume_vm_exports.get(volume=123)

>>> # Start an export
>>> exp.start(name="backup-2024")

>>> # View export stats
>>> for stat in exp.stats.list():
...     print(f"{stat.file_name}: {stat.size_gb}GB")

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, status=None, volume=None, **filter_kwargs)

List volume VM exports with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• status (str | None) – Filter by status (idle, building, error, cleaning).

• volume (int | None) – Filter by volume key.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of VolumeVmExport objects.

Return type:

list[VolumeVmExport]

Example

>>> # List all exports
>>> exports = client.volume_vm_exports.list()

>>> # List active exports
>>> active = client.volume_vm_exports.list(status="building")

get(key=None, *, volume=None, fields=None)

Get a single volume VM export by key or volume.

Parameters:

• key (int | None) – Export $key (row ID).

• volume (int | None) – Parent volume key (since there’s one export per volume).

• fields (list[str] | None) – List of fields to return.

Returns:

VolumeVmExport object.

Raises:

• NotFoundError – If export not found.

• ValueError – If no identifier provided.

Return type:

VolumeVmExport

Example

>>> # Get by key
>>> exp = client.volume_vm_exports.get(key=1)

>>> # Get by volume
>>> exp = client.volume_vm_exports.get(volume=123)

create(volume, *, quiesced=True, create_current=True, max_exports=3)

Create a new volume VM export configuration.

Parameters:

• volume (int) – NAS volume key to export VMs to.

• quiesced (bool) – Whether to quiesce VMs during export (default True).

• create_current (bool) – Create ‘current’ folder with latest export (default True).

• max_exports (int) – Maximum exports to store (1-100, default 3).

Returns:

Created VolumeVmExport object.

Return type:

VolumeVmExport

Example

>>> exp = client.volume_vm_exports.create(
...     volume=123,
...     max_exports=5,
...     quiesced=True
... )

update(key, *, quiesced=None, create_current=None, max_exports=None)

Update a volume VM export configuration.

Parameters:

• key (int) – Export $key (row ID).

• quiesced (bool | None) – Whether to quiesce VMs during export.

• create_current (bool | None) – Create ‘current’ folder with latest export.

• max_exports (int | None) – Maximum exports to store (1-100).

Returns:

Updated VolumeVmExport object.

Return type:

VolumeVmExport

delete(key)

Delete a volume VM export configuration.

Parameters:

key (int) – Export $key (row ID).

Return type:

None

Example

>>> client.volume_vm_exports.delete(1)

start_export(key, name=None, vms=None)

Start a VM export operation.

Parameters:

• key (int) – Export $key (row ID).

• name (str | None) – Optional export name/folder name.

• vms (list[int] | None) – Optional list of VM keys to export. If not provided, exports all.

Returns:

Action result dict or None.

Return type:

dict[str, Any] | None

Example

>>> result = client.volume_vm_exports.start_export(1, name="backup-2024")

stop_export(key)

Stop an in-progress VM export operation.

Parameters:

key (int) – Export $key (row ID).

Returns:

Action result dict or None.

Return type:

dict[str, Any] | None

Example

>>> client.volume_vm_exports.stop_export(1)

cleanup_exports(key)

Clean up old export folders.

Parameters:

key (int) – Export $key (row ID).

Returns:

Action result dict or None.

Return type:

dict[str, Any] | None

Example

>>> client.volume_vm_exports.cleanup_exports(1)

stats(key)

Get a stats manager for a specific export.

Parameters:

key (int) – Export $key (row ID).

Returns:

VolumeVmExportStatManager for the export.

Return type:

VolumeVmExportStatManager

Example

>>> for stat in client.volume_vm_exports.stats(1).list():
...     print(f"{stat.file_name}: {stat.size_gb}GB")

class pyvergeos.resources.volume_vm_exports.VolumeVmExportStatManager

Bases: ResourceManager[VolumeVmExportStat]

Manager for volume VM export statistics.

This manager provides access to export statistics. It can be used either standalone or scoped to a specific export.

Example

>>> # List all export stats (standalone)
>>> for stat in client.volume_vm_export_stats.list():
...     print(f"{stat.file_name}: {stat.size_gb}GB")

>>> # List stats for a specific export
>>> for stat in client.volume_vm_exports.stats(1).list():
...     print(f"{stat.file_name}: {stat.virtual_machines} VMs")

__init__(client, *, export_key=None)

Parameters:

• client (VergeClient)

• export_key (int | None)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, volume_vm_exports=None, **filter_kwargs)

List volume VM export statistics with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• volume_vm_exports (int | None) – Filter by export key. Ignored if manager is scoped.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of VolumeVmExportStat objects.

Return type:

list[VolumeVmExportStat]

Example

>>> # List all stats
>>> stats = client.volume_vm_export_stats.list()

>>> # List stats for a specific export
>>> stats = client.volume_vm_exports.stats(1).list()

get(key=None, *, fields=None)

Get a single VM export stat by key.

Parameters:

• key (int | None) – Stat $key (row ID).

• fields (list[str] | None) – List of fields to return.

Returns:

VolumeVmExportStat object.

Raises:

• NotFoundError – If stat not found.

• ValueError – If key not provided.

Return type:

VolumeVmExportStat

Example

>>> stat = client.volume_vm_export_stats.get(1)

delete(key)

Delete a VM export stat entry.

Parameters:

key (int) – Stat $key (row ID).

Return type:

None

Example

>>> client.volume_vm_export_stats.delete(1)

Machine Stats & Monitoring

Real-time and historical performance metrics for VMs and nodes.

Machine Stats & Monitoring resource managers.

This module provides access to machine performance metrics, status, and logs. A “machine” in VergeOS represents both VMs and physical nodes.

Example

>>> # Access VM stats
>>> vm = client.vms.get(name="web-server")
>>> stats = vm.stats.get()
>>> print(f"CPU: {stats.total_cpu}%, RAM: {stats.ram_used_mb}MB")

>>> # Access stats history
>>> history = vm.stats.history_short()
>>> for point in history:
...     print(f"{point.timestamp}: CPU {point.total_cpu}%")

>>> # Access machine status
>>> status = vm.machine_status.get()
>>> print(f"Status: {status.status}, Node: {status.node_name}")

>>> # Access machine logs
>>> logs = vm.machine_logs.list(level="error")
>>> for log in logs:
...     print(f"[{log.level}] {log.text}")

class pyvergeos.resources.machine_stats.MachineStats

Bases: ResourceObject

Machine statistics resource object.

Provides current performance metrics for a machine (VM or node).

property machine_key: int

Parent machine key.

property total_cpu: int

Total CPU usage percentage (0-100).

property user_cpu: int

User CPU usage percentage.

property system_cpu: int

System CPU usage percentage.

property iowait_cpu: int

IO wait CPU percentage.

property vmusage_cpu: int

VM usage CPU percentage (for nodes).

property irq_cpu: int

IRQ CPU percentage.

property ram_used_mb: int

Physical RAM used in MB.

property ram_pct: int

Physical RAM used percentage.

property vram_used_mb: int

Virtual RAM used in MB.

property core_usagelist: list[Any]

Per-core usage list.

property core_temp: int | None

Average core temperature in Celsius.

property core_temp_top: int | None

Top (highest) core temperature in Celsius.

property core_peak: int

Peak core usage percentage.

property cores_gt_25_pct: int

Count of cores above 25% usage.

property cores_gt_50_pct: int

Count of cores above 50% usage.

property cores_gt_75_pct: int

Count of cores above 75% usage.

property modified_at: datetime | None

Timestamp when stats were last updated.

class pyvergeos.resources.machine_stats.MachineStatsHistory

Bases: ResourceObject

Machine statistics history record.

Represents a single time point in the stats history.

property machine_key: int

Parent machine key.

property timestamp: datetime | None

Timestamp for this history point.

property timestamp_epoch: int

Timestamp as Unix epoch.

property total_cpu: int

Total CPU usage percentage.

property user_cpu: int

User CPU usage percentage.

property system_cpu: int

System CPU usage percentage.

property iowait_cpu: int

IO wait CPU percentage.

property vmusage_cpu: int

VM usage CPU percentage.

property irq_cpu: int

IRQ CPU percentage.

property ram_used_mb: int

Physical RAM used in MB.

property vram_used_mb: int

Virtual RAM used in MB.

property core_temp: int | None

Average core temperature.

property core_temp_top: int | None

Top core temperature.

property core_peak: int

Peak core usage percentage.

class pyvergeos.resources.machine_stats.MachineStatsManager

Bases: ResourceManager[MachineStats]

Manager for machine statistics.

Provides access to current and historical performance metrics. Scoped to a specific machine.

Example

>>> # Get current stats
>>> stats = manager.get()
>>> print(f"CPU: {stats.total_cpu}%")

>>> # Get short-term history (high resolution)
>>> history = manager.history_short(limit=100)

>>> # Get long-term history (lower resolution, longer retention)
>>> history = manager.history_long(limit=1000)

__init__(client, machine_key)

Parameters:

• client (VergeClient)

• machine_key (int)

Return type:

None

get(fields=None)

Get current machine statistics.

Parameters:

fields (list[str] | None) – List of fields to return.

Returns:

MachineStats object.

Raises:

NotFoundError – If stats not found for this machine.

Return type:

MachineStats

history_short(limit=None, offset=None, since=None, until=None, fields=None)

Get short-term stats history (high resolution).

Parameters:

• limit (int | None) – Maximum number of records to return.

• offset (int | None) – Skip this many records.

• since (datetime | int | None) – Return records after this time (datetime or epoch).

• until (datetime | int | None) – Return records before this time (datetime or epoch).

• fields (list[str] | None) – List of fields to return.

Returns:

List of MachineStatsHistory objects, sorted by timestamp descending.

Return type:

list[MachineStatsHistory]

history_long(limit=None, offset=None, since=None, until=None, fields=None)

Get long-term stats history (lower resolution, longer retention).

Parameters:

• limit (int | None) – Maximum number of records to return.

• offset (int | None) – Skip this many records.

• since (datetime | int | None) – Return records after this time (datetime or epoch).

• until (datetime | int | None) – Return records before this time (datetime or epoch).

• fields (list[str] | None) – List of fields to return.

Returns:

List of MachineStatsHistory objects, sorted by timestamp descending.

Return type:

list[MachineStatsHistory]

class pyvergeos.resources.machine_stats.MachineStatus

Bases: ResourceObject

Machine status resource object.

Provides operational status for a machine (VM or node).

property machine_key: int

Parent machine key.

property is_running: bool

Check if machine is currently running.

property is_migratable: bool

Check if machine can be migrated.

property status: str

Current status (running, stopped, migrating, etc.).

property status_raw: str

Raw status value.

property status_info: str

Additional status information.

property state: str

State (online, offline, warning, error).

property state_raw: str

Raw state value.

property powerstate: bool

Power state (on/off).

property node_key: int | None

Node where machine is running.

property node_name: str

Name of node where machine is running.

property migrated_node_key: int | None

Node the machine was migrated from.

property migration_destination_key: int | None

Node the machine is migrating to.

property started_at: datetime | None

Timestamp when machine was started.

property local_time: datetime | None

Machine local time.

property last_update: datetime | None

Timestamp of last status update.

property running_cores: int

Number of running CPU cores.

property running_ram_mb: int

Amount of running RAM in MB.

property agent_version: str

Guest agent version.

property has_agent: bool

Check if guest agent is installed.

property agent_features: dict[str, Any]

Guest agent supported features.

property agent_guest_info: dict[str, Any]

Guest OS information from agent.

class pyvergeos.resources.machine_stats.MachineStatusManager

Bases: ResourceManager[MachineStatus]

Manager for machine status.

Provides access to operational status for a machine. Scoped to a specific machine.

Example

>>> status = manager.get()
>>> print(f"Status: {status.status}")
>>> if status.is_running:
...     print(f"Running on node: {status.node_name}")

__init__(client, machine_key)

Parameters:

• client (VergeClient)

• machine_key (int)

Return type:

None

get(fields=None)

Get machine status.

Parameters:

fields (list[str] | None) – List of fields to return.

Returns:

MachineStatus object.

Raises:

NotFoundError – If status not found for this machine.

Return type:

MachineStatus

class pyvergeos.resources.machine_stats.MachineLog

Bases: ResourceObject

Machine log entry resource object.

property machine_key: int

Parent machine key.

property machine_name: str

Parent machine name.

property level: str

Log level (Audit, Message, Warning, Error, Critical).

property level_raw: str

Raw log level value.

property text: str

Log message text.

property user: str

User who generated the log entry.

property timestamp: datetime | None

Timestamp of log entry (microseconds precision).

property timestamp_epoch_us: int

Timestamp as Unix epoch in microseconds.

property is_error: bool

Check if this is an error or critical log.

property is_warning: bool

Check if this is a warning log.

property is_audit: bool

Check if this is an audit log.

class pyvergeos.resources.machine_stats.MachineLogManager

Bases: ResourceManager[MachineLog]

Manager for machine logs.

Provides access to log entries for a machine. Scoped to a specific machine.

Example

>>> # Get recent logs
>>> logs = manager.list(limit=20)

>>> # Get errors only
>>> errors = manager.list(level="error")

>>> # Get logs since a specific time
>>> logs = manager.list(since=datetime.now() - timedelta(hours=1))

__init__(client, machine_key)

Parameters:

• client (VergeClient)

• machine_key (int)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, level=None, errors_only=False, warnings_only=False, since=None, until=None, **filter_kwargs)

List machine log entries.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• level (Literal['audit', 'message', 'warning', 'error', 'critical', 'summary', 'debug'] | None) – Filter by log level.

• errors_only (bool) – Only return error and critical logs.

• warnings_only (bool) – Only return warning logs.

• since (datetime | int | None) – Return logs after this time (datetime or epoch microseconds).

• until (datetime | int | None) – Return logs before this time (datetime or epoch microseconds).

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of MachineLog objects, sorted by timestamp descending.

Return type:

list[MachineLog]

get(key=None, *, fields=None)

Get a specific log entry by key.

Parameters:

• key (int | None) – Log entry $key (ID).

• fields (list[str] | None) – List of fields to return.

Returns:

MachineLog object.

Raises:

• NotFoundError – If log entry not found.

• ValueError – If key not provided.

Return type:

MachineLog

Networks

Core Network Management

Virtual Network resource manager.

class pyvergeos.resources.networks.Network

Bases: ResourceObject

Virtual Network resource object.

power_on(apply_rules=True)

Power on the network.

Parameters:

apply_rules (bool) – Apply firewall rules on start.

Returns:

Self for chaining.

Return type:

Network

power_off(force=False)

Power off the network.

Parameters:

force (bool) – Force immediate power off (killpower) instead of graceful.

Returns:

Self for chaining.

Return type:

Network

restart(apply_rules=True)

Restart the network.

Parameters:

apply_rules (bool) – Apply firewall rules on restart.

Returns:

Self for chaining.

Return type:

Network

reset(apply_rules=True)

Restart the network.

Parameters:

apply_rules (bool) – Apply firewall rules on restart.

Returns:

Self for chaining.

Return type:

Network

apply_rules()

Apply firewall rules.

Returns:

Self for chaining.

Return type:

Network

apply_dns()

Apply DNS configuration.

Returns:

Self for chaining.

Return type:

Network

property is_running: bool

Check if network is powered on.

property status: str

Get the network status (running, stopped, etc.).

property needs_restart: bool

Check if network needs restart to apply changes.

property needs_rule_apply: bool

Check if firewall rules need to be applied.

property needs_dns_apply: bool

Check if DNS configuration needs to be applied.

property needs_proxy_apply: bool

Check if proxy configuration needs to be applied.

property proxy_enabled: bool

Check if proxy service is enabled on this network.

property rules: NetworkRuleManager

Access firewall rules for this network.

Returns:

NetworkRuleManager for this network.

Examples

List all rules:

rules = network.rules.list()

Create a rule:

rule = network.rules.create(
    name="Allow HTTPS",
    direction="incoming",
    action="accept",
    protocol="tcp",
    destination_ports="443"
)

property aliases: NetworkAliasManager

Access IP aliases for this network.

Returns:

NetworkAliasManager for this network.

Examples

List all aliases:

aliases = network.aliases.list()

Create an alias:

alias = network.aliases.create(
    ip="10.0.0.100",
    name="webserver",
    description="Main web server"
)

Get alias by IP:

alias = network.aliases.get(ip="10.0.0.100")

property hosts: NetworkHostManager

Access DHCP/DNS host overrides for this network.

Returns:

NetworkHostManager for this network.

Examples

List all host overrides:

hosts = network.hosts.list()

Create a host override:

host = network.hosts.create(
    hostname="server01",
    ip="10.0.0.50"
)

Get host by hostname:

host = network.hosts.get(hostname="server01")

Note

Host override changes require DNS apply to take effect.

property dns_zones: DNSZoneManager

Access DNS zones for this network.

Returns:

DNSZoneManager for this network.

Examples

List all DNS zones:

zones = network.dns_zones.list()

Get a zone by domain:

zone = network.dns_zones.get(domain="example.com")

List records in a zone:

records = zone.records.list()

Create a DNS record:

record = zone.records.create(
    host="www",
    record_type="A",
    value="10.0.0.100"
)

Note

DNS zones are typically created through the VergeOS UI. DNS changes require DNS apply on the network to take effect.

property dns_views: DNSViewManager

Access DNS views for this network.

Returns:

DNSViewManager for this network.

Examples

List all DNS views:

views = network.dns_views.list()

Get a view by name:

view = network.dns_views.get(name="internal")

Create a view:

view = network.dns_views.create(name="internal")

Create a zone through a view:

zone = view.zones.create(domain="example.com")

Note

DNS changes require DNS apply on the network to take effect.

property ipsec: IPSecConnectionManager

Access IPSec VPN connections for this network.

Returns:

IPSecConnectionManager for this network.

Examples

List all IPSec connections:

connections = network.ipsec.list()

Get a connection by name:

conn = network.ipsec.get(name="Site-B")

Create a connection:

conn = network.ipsec.create(
    name="Site-B",
    remote_gateway="203.0.113.1",
    pre_shared_key="MySecretKey123"
)

Access Phase 2 policies:

policies = conn.policies.list()

Create a Phase 2 policy:

policy = conn.policies.create(
    name="LAN-to-LAN",
    local_network="10.0.0.0/24",
    remote_network="192.168.1.0/24"
)

Note

IPSec configuration changes may require applying firewall rules on the network for changes to take effect.

property wireguard: WireGuardManager

Access WireGuard VPN interfaces for this network.

Returns:

WireGuardManager for this network.

Examples

List all WireGuard interfaces:

interfaces = network.wireguard.list()

Get an interface by name:

wg = network.wireguard.get(name="wg0")

Create an interface:

wg = network.wireguard.create(
    name="wg0",
    ip_address="10.100.0.1/24",
    listen_port=51820
)

Access peers:

peers = wg.peers.list()

Create a peer:

peer = wg.peers.create(
    name="remote-office",
    peer_ip="10.100.0.2",
    public_key="abc123...",
    allowed_ips="192.168.1.0/24"
)

Get peer configuration:

config = peer.get_config()

Note

WireGuard configuration changes may require applying firewall rules on the network for changes to take effect.

property routing: NetworkRoutingManager

Access routing protocols (BGP, OSPF, EIGRP) for this network.

Returns:

NetworkRoutingManager for this network.

Examples

Configure BGP:

# Create a BGP router
bgp = network.routing.bgp_routers.create(asn=65000)

# Add a neighbor
bgp.commands.create(
    command="neighbor",
    params="192.168.1.1 remote-as 65001"
)

Configure OSPF:

# Set router ID
network.routing.ospf_commands.create(
    command="router-id",
    params="1.1.1.1"
)

# Add network to area 0
network.routing.ospf_commands.create(
    command="network",
    params="10.0.0.0/24 area 0"
)

Configure EIGRP:

# Create an EIGRP router
eigrp = network.routing.eigrp_routers.create(asn=100)

# Add network
eigrp.commands.create(
    command="network",
    params="10.0.0.0/24"
)

Note

Routing configuration changes require restarting the network for changes to take effect.

property proxy: VnetProxyManager

Access proxy configuration for this network.

The proxy service enables multi-tenant access through a single IP address using FQDN-based routing. Each tenant is assigned a unique hostname that routes to their UI through the proxy.

Returns:

VnetProxyManager for this network.

Examples

Check if proxy is configured:

if network.proxy.exists():
    proxy = network.proxy.get()
    print(f"Proxy listening on {proxy.listen_address}")

Enable proxy on a network:

proxy = network.proxy.create(
    listen_address="0.0.0.0",
    default_self=True
)

Add a tenant mapping:

mapping = proxy.tenants.create(
    tenant=tenant_key,
    fqdn="tenant1.example.com"
)

List all tenant mappings:

for mapping in proxy.tenants.list():
    print(f"{mapping.fqdn} -> {mapping.tenant_name}")

Note

Proxy is typically used on external networks to allow multiple tenants to share a single public IP address. After adding/modifying tenant mappings, the tenant may need to have proxy applied via the tenant dashboard.

property stats: NetworkMonitorStatsManager

Access network monitoring statistics for this network.

Provides network quality metrics including packet loss, latency, and overall connection health for monitoring and troubleshooting.

Returns:

NetworkMonitorStatsManager for this network.

Examples

Get current stats:

stats = network.stats.get()
print(f"Quality: {stats.quality}%")
print(f"Latency: {stats.latency_avg_ms}ms")
if stats.has_issues:
    print("Warning: Network quality issues detected!")

Get recent history:

history = network.stats.history_short(limit=60)
for point in history:
    print(f"{point.timestamp}: {point.quality}% quality")

Get long-term trends:

from datetime import datetime, timedelta
since = datetime.now() - timedelta(days=7)
history = network.stats.history_long(since=since)

Note

Statistics are collected by VergeOS network monitoring and may not be available for newly created networks until they have been running for some time.

property ipsec_connections: IPSecActiveConnectionManager

Access active IPSec VPN connections for this network.

Provides real-time status of currently established IPSec tunnels, including connection details and tunnel parameters.

Returns:

IPSecActiveConnectionManager for this network.

Examples

List active connections:

for conn in network.ipsec_connections.list():
    print(f"{conn.connection}: {conn.local} <-> {conn.remote}")
    print(f"  Local Network: {conn.local_network}")
    print(f"  Remote Network: {conn.remote_network}")
    print(f"  Protocol: {conn.protocol}")

Check connection count:

count = network.ipsec_connections.count()
print(f"Active IPSec tunnels: {count}")

Note

This provides real-time connection status, not configuration. For IPSec configuration management, use network.ipsec instead. Connections are dynamically computed and not stored in the database.

diagnostics(diagnostic_type='all')

Get network diagnostic information.

Returns DHCP leases and/or address table entries for this network.

Parameters:

diagnostic_type (Literal['dhcp_leases', 'addresses', 'all']) – Type of diagnostics to retrieve: - “dhcp_leases”: Only DHCP lease information (dynamic addresses) - “addresses”: All address table entries - “all”: Both DHCP leases and addresses (default)

Returns:

• network_key: Network key

• network_name: Network name

• is_running: Whether network is running

• dhcp_enabled: Whether DHCP is enabled

• dhcp_leases: List of DHCP leases (if requested)

• dhcp_lease_count: Number of DHCP leases

• addresses: List of all addresses (if requested)

• address_count: Number of addresses

Return type:

Dictionary containing

Examples

Get all diagnostics:

diag = network.diagnostics()
print(f"DHCP Leases: {diag['dhcp_lease_count']}")
for lease in diag['dhcp_leases']:
    print(f"  {lease['ip']} -> {lease['hostname']}")

Get only DHCP leases:

diag = network.diagnostics(diagnostic_type="dhcp_leases")

Get only address table:

diag = network.diagnostics(diagnostic_type="addresses")

statistics(include_history=False, history_limit=60)

Get network traffic statistics.

Returns current traffic statistics and optionally historical data.

Parameters:

• include_history (bool) – Include historical monitoring data.

• history_limit (int) – Maximum number of history entries to return (default 60).

Returns:

• network_key: Network key

• network_name: Network name

• is_running: Whether network is running

• tx_bytes_per_sec: Transmit rate in bytes/second

• rx_bytes_per_sec: Receive rate in bytes/second

• tx_packets_per_sec: Transmit packets/second

• rx_packets_per_sec: Receive packets/second

• tx_bytes_total: Total bytes transmitted

• rx_bytes_total: Total bytes received

• tx_total_formatted: Human-readable total transmitted

• rx_total_formatted: Human-readable total received

• dmz_tx_bytes_per_sec: DMZ transmit rate (if applicable)

• dmz_rx_bytes_per_sec: DMZ receive rate (if applicable)

• … (similar DMZ stats)

• history: List of historical stats (if requested)

Return type:

Dictionary containing

Examples

Get current statistics:

stats = network.statistics()
print(f"TX: {stats['tx_total_formatted']}")
print(f"RX: {stats['rx_total_formatted']}")

Get statistics with history:

stats = network.statistics(include_history=True)
for entry in stats.get('history', []):
    print(f"{entry['timestamp']}: {entry['quality']}% quality")

Note

Statistics are only available for running networks.

class pyvergeos.resources.networks.NetworkManager

Bases: ResourceManager[Network]

Manager for Virtual Network operations.

Provides CRUD operations and power management for virtual networks.

Examples

List all networks:

networks = client.networks.list()

Get a network by name:

external = client.networks.get(name="External")

Create an internal network:

net = client.networks.create(
    name="Dev-Network",
    network_address="10.10.10.0/24",
    ip_address="10.10.10.1",
    dhcp_enabled=True,
    dhcp_start="10.10.10.100",
    dhcp_stop="10.10.10.200"
)

Power operations:

net.power_on()
net.restart()
net.power_off()

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List networks with optional filtering.

By default, requests common fields including running status. Override with the fields parameter for custom field selection.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (defaults to common fields).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of Network objects.

Return type:

list[Network]

get(key=None, *, name=None, fields=None)

Get a single network by key or name.

Parameters:

• key (int | None) – Network $key (ID).

• name (str | None) – Network name.

• fields (list[str] | None) – List of fields to return (defaults to common fields).

Returns:

Network object.

Raises:

NotFoundError – If network not found.

Return type:

Network

list_internal()

List internal networks.

Returns:

List of internal networks.

Return type:

list[Network]

list_external()

List external networks.

Returns:

List of external networks.

Return type:

list[Network]

list_running()

List all running networks.

Returns:

List of running networks.

Return type:

list[Network]

list_stopped()

List all stopped networks.

Returns:

List of stopped networks.

Return type:

list[Network]

create(name, network_type='internal', network_address=None, ip_address=None, gateway=None, dhcp_enabled=False, dhcp_start=None, dhcp_stop=None, dns='simple', dns_servers=None, domain=None, mtu=None, layer2_type='vxlan', layer2_id=None, interface_network=None, on_power_loss='last_state', description='', **kwargs)

Create a new virtual network.

Parameters:

• name (str) – Network name.

• network_type (str) – Network type (internal, external, dmz).

• network_address (str | None) – CIDR notation (e.g., “192.168.1.0/24”).

• ip_address (str | None) – Router IP address within the network.

• gateway (str | None) – Default gateway IP (for DHCP clients).

• dhcp_enabled (bool) – Enable DHCP server.

• dhcp_start (str | None) – DHCP range start IP.

• dhcp_stop (str | None) – DHCP range end IP.

• dns (str) – DNS mode (disabled, simple, bind, network).

• dns_servers (list[str] | None) – List of DNS server IPs for DHCP.

• domain (str | None) – Domain name for the network.

• mtu (int | None) – MTU size (1000-65536).

• layer2_type (str) – Layer 2 type (vlan, vxlan, none).

• layer2_id (int | None) – VLAN or VXLAN ID.

• interface_network (int | None) – Key of interface (uplink) network.

• on_power_loss (str) – Behavior on power restore (power_on, last_state, leave_off).

• description (str) – Network description.

• **kwargs (Any) – Additional network properties.

Returns:

Created network object.

Return type:

Network

diagnostics(key, diagnostic_type='all')

Get network diagnostic information.

Returns DHCP leases and/or address table entries for a network.

Parameters:

• key (int) – Network $key (ID).

• diagnostic_type (Literal['dhcp_leases', 'addresses', 'all']) – Type of diagnostics to retrieve: - “dhcp_leases”: Only DHCP lease information (dynamic addresses) - “addresses”: All address table entries - “all”: Both DHCP leases and addresses (default)

Returns:

Dictionary containing diagnostic information.

Return type:

dict[str, Any]

Examples

Get all diagnostics:

diag = client.networks.diagnostics(network_key)
print(f"DHCP Leases: {diag['dhcp_lease_count']}")

Get via network object:

network = client.networks.get(name="Internal")
diag = network.diagnostics()

statistics(key, include_history=False, history_limit=60)

Get network traffic statistics.

Returns current traffic statistics and optionally historical data.

Parameters:

• key (int) – Network $key (ID).

• include_history (bool) – Include historical monitoring data.

• history_limit (int) – Maximum number of history entries (default 60).

Returns:

Dictionary containing traffic statistics.

Return type:

dict[str, Any]

Examples

Get current statistics:

stats = client.networks.statistics(network_key)
print(f"TX: {stats['tx_total_formatted']}")

Get via network object:

network = client.networks.get(name="External")
stats = network.statistics(include_history=True)

Note

Statistics are only available for running networks.

Firewall Rules

Network firewall rule resource manager.

class pyvergeos.resources.rules.NetworkRule

Bases: ResourceObject

Network firewall rule resource object.

property network_key: int

Get the network key this rule belongs to.

property network_name: str | None

Get the network name this rule belongs to.

property is_enabled: bool

Check if rule is enabled.

property is_system_rule: bool

Check if this is a system rule (cannot be modified/deleted).

property order: int

Get rule order position.

property direction: str

Get rule direction (incoming/outgoing).

property action: str

Get rule action (accept/drop/reject/translate/route).

property protocol: str

Get rule protocol (tcp/udp/tcpudp/icmp/any).

property source_ip: str | None

Get source IP filter.

property source_ports: str | None

Get source ports filter.

property destination_ip: str | None

Get destination IP filter.

property destination_ports: str | None

Get destination ports filter.

property target_ip: str | None

Get target IP for translate/route actions.

property target_ports: str | None

Get target ports for port translation.

property is_logging: bool

Check if logging is enabled.

property has_statistics: bool

Check if statistics tracking is enabled.

property packet_count: int

Get number of packets matched by this rule.

property byte_count: int

Get number of bytes matched by this rule.

enable()

Enable this rule.

Returns:

Self for chaining.

Return type:

NetworkRule

disable()

Disable this rule.

Returns:

Self for chaining.

Return type:

NetworkRule

class pyvergeos.resources.rules.NetworkRuleManager

Bases: ResourceManager[NetworkRule]

Manager for Network firewall rule operations.

This manager is accessed through a Network object’s rules property.

Examples

List all rules for a network:

rules = network.rules.list()

List only incoming rules:

incoming = network.rules.list(direction="incoming")

Create a new accept rule:

rule = network.rules.create(
    name="Allow HTTPS",
    direction="incoming",
    action="accept",
    protocol="tcp",
    destination_ports="443"
)

Create a NAT rule:

rule = network.rules.create(
    name="NAT to Web Server",
    direction="incoming",
    action="translate",
    protocol="tcp",
    destination_ports="80,443",
    target_ip="192.168.1.10"
)

Delete a rule:

network.rules.delete(rule.key)

__init__(client, network)

Parameters:

• client (VergeClient)

• network (Network)

Return type:

None

property network_key: int

Get the network key for this manager.

list(filter=None, fields=None, direction=None, action=None, protocol=None, enabled=None, **kwargs)

List firewall rules for this network.

Parameters:

• filter (str | None) – Additional OData filter string.

• fields (list[str] | None) – List of fields to return.

• direction (Literal['incoming', 'outgoing'] | None) – Filter by direction (incoming/outgoing).

• action (Literal['accept', 'drop', 'reject', 'translate', 'route'] | None) – Filter by action (accept/drop/reject/translate/route).

• protocol (Literal['tcp', 'udp', 'tcpudp', 'icmp', 'any'] | None) – Filter by protocol (tcp/udp/tcpudp/icmp/any).

• enabled (bool | None) – Filter by enabled status.

• **kwargs (Any) – Additional filter arguments.

Returns:

List of NetworkRule objects sorted by order.

Return type:

list[NetworkRule]

get(key=None, *, name=None, fields=None)

Get a rule by key or name.

Parameters:

• key (int | None) – Rule $key (ID).

• name (str | None) – Rule name.

• fields (list[str] | None) – List of fields to return.

Returns:

NetworkRule object.

Raises:

• NotFoundError – If rule not found.

• ValueError – If neither key nor name provided.

Return type:

NetworkRule

create(name, direction='incoming', action='accept', protocol='any', interface='auto', source_ip=None, source_ports=None, destination_ip=None, destination_ports=None, target_ip=None, target_ports=None, enabled=True, log=False, statistics=False, pin=None, order=None, description='')

Create a new firewall rule.

Parameters:

• name (str) – Rule name (must be unique within the network).

• direction (Literal['incoming', 'outgoing']) – Traffic direction (incoming or outgoing).

• action (Literal['accept', 'drop', 'reject', 'translate', 'route']) – Action to take (accept, drop, reject, translate, route).

• protocol (Literal['tcp', 'udp', 'tcpudp', 'icmp', 'any']) – Protocol to match (tcp, udp, tcpudp, icmp, any).

• interface (Literal['auto', 'router', 'dmz', 'wireguard', 'any']) – Interface for the rule (auto, router, dmz, wireguard, any).

• source_ip (str | None) – Source IP filter (IP, CIDR, or special value like “vnetself”).

• source_ports (str | None) – Source ports (e.g., “80”, “1024-65535”, “80,443”).

• destination_ip (str | None) – Destination IP filter.

• destination_ports (str | None) – Destination ports.

• target_ip (str | None) – Target IP for translate/route actions.

• target_ports (str | None) – Target ports for port translation.

• enabled (bool) – Enable the rule (default True).

• log (bool) – Enable logging for this rule.

• statistics (bool) – Enable statistics tracking.

• pin (Literal['top', 'bottom'] | None) – Pin position (“top” or “bottom”).

• order (int | None) – Specific order position (alternative to pin).

• description (str) – Rule description.

Returns:

Created NetworkRule object.

Raises:

ValidationError – If a rule with this name already exists.

Return type:

NetworkRule

update(key, **kwargs)

Update a firewall rule.

Parameters:

• key (int) – Rule $key (ID).

• **kwargs (Any) – Fields to update. Common fields: - name: New rule name - direction: incoming/outgoing - action: accept/drop/reject/translate/route - protocol: tcp/udp/tcpudp/icmp/any - source_ip, source_ports: Source filters - destination_ip, destination_ports: Destination filters - target_ip, target_ports: Target for translate/route - enabled: Enable/disable rule - log: Enable/disable logging - statistics: Enable/disable statistics

Returns:

Updated NetworkRule object.

Raises:

ValidationError – If trying to modify a system rule.

Return type:

NetworkRule

delete(key)

Delete a firewall rule.

Parameters:

key (int) – Rule $key (ID).

Raises:

ValidationError – If trying to delete a system rule.

Return type:

None

Note

Rule changes are not active until network.apply_rules() is called.

list_incoming()

List incoming rules.

Returns:

List of incoming rules.

Return type:

list[NetworkRule]

list_outgoing()

List outgoing rules.

Returns:

List of outgoing rules.

Return type:

list[NetworkRule]

list_enabled()

List enabled rules.

Returns:

List of enabled rules.

Return type:

list[NetworkRule]

list_disabled()

List disabled rules.

Returns:

List of disabled rules.

Return type:

list[NetworkRule]

DNS

DNS Zone and Record resource managers.

class pyvergeos.resources.dns.DNSRecord

Bases: ResourceObject

DNS Record resource object.

property zone_key: int

Get the zone key this record belongs to.

property host: str

Get the hostname of this record.

property record_type: str

Get the record type (A, AAAA, CNAME, MX, etc.).

property value: str

Get the record value (IP address, hostname, or text).

property ttl: str | None

Get the TTL for this record.

property mx_preference: int

Get the MX preference (for MX records).

property weight: int

Get the weight (for SRV records).

property port: int

Get the port (for SRV records).

property description: str | None

Get the record description.

class pyvergeos.resources.dns.DNSRecordManager

Bases: ResourceManager[DNSRecord]

Manager for DNS Record operations.

This manager is accessed through a DNSZone object’s records property.

Examples

List all records in a zone:

records = zone.records.list()

Get an A record by host:

record = zone.records.get(host="www")

Create an A record:

record = zone.records.create(
    host="www",
    record_type="A",
    value="10.0.0.100"
)

Create an MX record:

record = zone.records.create(
    host="",  # root domain
    record_type="MX",
    value="mail.example.com",
    mx_preference=10
)

Delete a record:

zone.records.delete(record.key)

__init__(client, zone)

Parameters:

• client (VergeClient)

• zone (DNSZone)

Return type:

None

property zone_key: int

Get the zone key for this manager.

list(filter=None, fields=None, host=None, record_type=None, **kwargs)

List DNS records in this zone.

Parameters:

• filter (str | None) – Additional OData filter string.

• fields (list[str] | None) – List of fields to return.

• host (str | None) – Filter by exact hostname.

• record_type (Literal['A', 'AAAA', 'CNAME', 'MX', 'NS', 'PTR', 'SRV', 'TXT', 'CAA'] | None) – Filter by record type (A, CNAME, MX, etc.).

• **kwargs (Any) – Additional filter arguments.

Returns:

List of DNSRecord objects sorted by order.

Return type:

list[DNSRecord]

get(key=None, *, host=None, record_type=None, fields=None)

Get a DNS record by key, host, or type.

Parameters:

• key (int | None) – Record $key (ID).

• host (str | None) – Hostname of the record.

• record_type (Literal['A', 'AAAA', 'CNAME', 'MX', 'NS', 'PTR', 'SRV', 'TXT', 'CAA'] | None) – Record type to filter by.

• fields (list[str] | None) – List of fields to return.

Returns:

DNSRecord object.

Raises:

• NotFoundError – If record not found.

• ValueError – If no identifier provided.

Return type:

DNSRecord

create(record_type, value, host='', ttl=None, mx_preference=0, weight=0, port=0, description=None)

Create a new DNS record.

Parameters:

• record_type (Literal['A', 'AAAA', 'CNAME', 'MX', 'NS', 'PTR', 'SRV', 'TXT', 'CAA']) – Record type (A, AAAA, CNAME, MX, NS, PTR, SRV, TXT, CAA).

• value (str) – Record value (IP address, hostname, or text).

• host (str) – Hostname for the record (empty string for root domain).

• ttl (str | None) – Time-to-live for the record (e.g., “1h”, “30m”, “1d”).

• mx_preference (int) – Preference value for MX records (lower = higher priority).

• weight (int) – Weight for SRV records.

• port (int) – Port for SRV records.

• description (str | None) – Optional description for the record.

Returns:

Created DNSRecord object.

Return type:

DNSRecord

Note

DNS changes require DNS apply on the network to take effect.

delete(key)

Delete a DNS record.

Parameters:

key (int) – Record $key (ID).

Return type:

None

Note

DNS changes require DNS apply on the network to take effect.

class pyvergeos.resources.dns.DNSZone

Bases: ResourceObject

DNS Zone resource object.

__init__(data, manager, view_key=None, view_name=None)

Parameters:

• data (dict[str, Any])

• manager (DNSZoneManager)

• view_key (int | None)

• view_name (str | None)

Return type:

None

property view_key: int

Get the DNS view key this zone belongs to.

property view_name: str | None

Get the DNS view name this zone belongs to.

property domain: str

Get the domain name for this zone.

property zone_type: str

Get the zone type (raw API value).

property zone_type_display: str

Get the zone type display name.

property nameserver: str | None

Get the primary nameserver for this zone.

property email: str | None

Get the zone administrator email.

property default_ttl: str | None

Get the default TTL for records in this zone.

property serial_number: int

Get the zone serial number.

property records: DNSRecordManager

Access DNS records for this zone.

Returns:

DNSRecordManager for this zone.

Examples

List all records:

records = zone.records.list()

Create an A record:

record = zone.records.create(
    host="www",
    record_type="A",
    value="10.0.0.100"
)

class pyvergeos.resources.dns.DNSZoneManager

Bases: ResourceManager[DNSZone]

Manager for DNS Zone operations.

This manager can be accessed through a Network object’s dns_zones property (read-only listing) or through a DNSView object’s zones property (full CRUD).

Examples

List all zones for a network:

zones = network.dns_zones.list()

Get a zone by domain:

zone = network.dns_zones.get(domain="example.com")

Create a zone through a view:

view = network.dns_views.get(name="default")
zone = view.zones.create(domain="example.com")

List records in a zone:

records = zone.records.list()

Create a record:

record = zone.records.create(
    host="www",
    record_type="A",
    value="10.0.0.100"
)

__init__(client, network=None, view=None)

Parameters:

• client (VergeClient)

• network (Network | None)

• view (DNSView | None)

Return type:

None

property network_key: int

Get the network key for this manager.

property view_key: int | None

Get the view key if this manager is scoped to a view.

list(filter=None, fields=None, domain=None, zone_type=None, include_records=False, **kwargs)

List DNS zones for this network or view.

Parameters:

• filter (str | None) – Additional OData filter string.

• fields (list[str] | None) – List of fields to return.

• domain (str | None) – Filter by exact domain name.

• zone_type (Literal['master', 'slave', 'redirect', 'forward', 'static-stub', 'stub'] | None) – Filter by zone type.

• include_records (bool) – Include records in each zone (not yet implemented).

• **kwargs (Any) – Additional filter arguments.

Returns:

List of DNSZone objects sorted by domain.

Return type:

list[DNSZone]

get(key=None, *, domain=None, fields=None)

Get a DNS zone by key or domain.

Parameters:

• key (int | None) – Zone $key (ID).

• domain (str | None) – Domain name of the zone.

• fields (list[str] | None) – List of fields to return.

Returns:

DNSZone object.

Raises:

• NotFoundError – If zone not found.

• ValueError – If no identifier provided.

Return type:

DNSZone

create(domain, zone_type='master', nameserver='', email='', default_ttl='1h', notify='yes', allow_notify='none;', allow_transfer='none;', masters='', refresh_interval='3h', retry_interval='30m', expiry_period='3w', negative_ttl='10m', forwarders='', **kwargs)

Create a new DNS zone.

This method is only available when the manager is scoped to a view (accessed via view.zones). Use network.dns_views to get a view first.

Parameters:

• domain (str) – Domain name for the zone (required).

• zone_type (Literal['master', 'slave', 'redirect', 'forward', 'static-stub', 'stub']) – Zone type (default “master”).

• nameserver (str) – Primary nameserver FQDN.

• email (str) – Zone administrator email.

• default_ttl (str) – Default TTL for records (e.g., “1h”, “30m”, “1d”).

• notify (str) – Notify setting (“yes”, “no”, “explicit”).

• allow_notify (str) – IP networks allowed to send NOTIFY.

• allow_transfer (str) – Networks allowed zone transfers.

• masters (str) – Master server(s) for secondary zones.

• refresh_interval (str) – SOA refresh interval (default “3h”).

• retry_interval (str) – SOA retry interval (default “30m”).

• expiry_period (str) – SOA expiry period (default “3w”).

• negative_ttl (str) – Negative cache TTL (default “10m”).

• forwarders (str) – Forwarder servers (semicolon-delimited).

• **kwargs (Any) – Additional zone properties.

Returns:

Created DNSZone object.

Raises:

ValueError – If manager is not scoped to a view.

Return type:

DNSZone

Note

DNS changes require DNS apply on the network to take effect.

delete(key)

Delete a DNS zone.

Parameters:

key (int) – Zone $key (ID).

Return type:

None

Note

Deleting a zone also deletes all records within it. DNS changes require DNS apply on the network to take effect.

IP Aliases

Network IP alias resource manager.

class pyvergeos.resources.aliases.NetworkAlias

Bases: ResourceObject

Network IP alias resource object.

IP aliases can be referenced in firewall rules using alias:name syntax.

property network_key: int

Get the network key this alias belongs to.

property network_name: str | None

Get the network name this alias belongs to.

property ip: str

Get the IP address of this alias.

property hostname: str | None

Get the hostname/name of this alias.

property alias_name: str | None

Get the name of this alias (same as hostname).

property description: str | None

Get the description of this alias.

property mac: str | None

Get the MAC address associated with this alias.

class pyvergeos.resources.aliases.NetworkAliasManager

Bases: ResourceManager[NetworkAlias]

Manager for Network IP alias operations.

This manager is accessed through a Network object’s aliases property. IP aliases are used in firewall rules to reference groups of IP addresses.

Examples

List all aliases for a network:

aliases = network.aliases.list()

Get an alias by IP:

alias = network.aliases.get(ip="10.0.0.100")

Create a new IP alias:

alias = network.aliases.create(
    ip="10.0.0.100",
    name="webserver",
    description="Main web server"
)

Delete an alias:

network.aliases.delete(alias.key)

__init__(client, network)

Parameters:

• client (VergeClient)

• network (Network)

Return type:

None

property network_key: int

Get the network key for this manager.

list(filter=None, fields=None, ip=None, hostname=None, **kwargs)

List IP aliases for this network.

Parameters:

• filter (str | None) – Additional OData filter string.

• fields (list[str] | None) – List of fields to return.

• ip (str | None) – Filter by exact IP address.

• hostname (str | None) – Filter by exact hostname/name.

• **kwargs (Any) – Additional filter arguments.

Returns:

List of NetworkAlias objects sorted by IP.

Return type:

list[NetworkAlias]

get(key=None, *, ip=None, hostname=None, name=None, fields=None)

Get an alias by key, IP address, or hostname.

Parameters:

• key (int | None) – Alias $key (ID).

• ip (str | None) – IP address.

• hostname (str | None) – Hostname/name of the alias.

• name (str | None) – Alias for hostname (for convenience).

• fields (list[str] | None) – List of fields to return.

Returns:

NetworkAlias object.

Raises:

• NotFoundError – If alias not found.

• ValueError – If no identifier provided.

Return type:

NetworkAlias

create(ip, name, description='')

Create a new IP alias.

Parameters:

• ip (str) – IP address for the alias. Can be a single IP or CIDR notation.

• name (str) – Name/hostname for the alias (used in firewall rules as alias:name).

• description (str) – Optional description.

Returns:

Created NetworkAlias object.

Raises:

ValidationError – If an alias with this IP already exists.

Return type:

NetworkAlias

delete(key)

Delete an IP alias.

Parameters:

key (int) – Alias $key (ID).

Return type:

None

Note

Aliases referenced by firewall rules cannot be deleted until the rules are removed.

DHCP Hosts

Network DHCP/DNS host override resource manager.

class pyvergeos.resources.hosts.NetworkHost

Bases: ResourceObject

Network DHCP/DNS host override resource object.

Host overrides map hostnames to IP addresses for DHCP and DNS resolution.

property network_key: int

Get the network key this host belongs to.

property network_name: str | None

Get the network name this host belongs to.

property hostname: str

Get the hostname of this override.

property ip: str

Get the IP address of this host override.

property host_type: str

Get the type of this host override (‘host’ or ‘domain’).

property is_domain: bool

Check if this is a domain override.

property is_host: bool

Check if this is a host override.

class pyvergeos.resources.hosts.NetworkHostManager

Bases: ResourceManager[NetworkHost]

Manager for Network DHCP/DNS host override operations.

This manager is accessed through a Network object’s hosts property. Host overrides provide static DNS entries and DHCP hostname assignment.

Examples

List all hosts for a network:

hosts = network.hosts.list()

Get a host by hostname:

host = network.hosts.get(hostname="server01")

Create a new host override:

host = network.hosts.create(
    hostname="server01",
    ip="10.0.0.50",
    host_type="host"
)

Update a host override:

network.hosts.update(host.key, ip="10.0.0.51")

Delete a host override:

network.hosts.delete(host.key)

__init__(client, network)

Parameters:

• client (VergeClient)

• network (Network)

Return type:

None

property network_key: int

Get the network key for this manager.

list(filter=None, fields=None, hostname=None, ip=None, host_type=None, **kwargs)

List DHCP/DNS host overrides for this network.

Parameters:

• filter (str | None) – Additional OData filter string.

• fields (list[str] | None) – List of fields to return.

• hostname (str | None) – Filter by exact hostname.

• ip (str | None) – Filter by exact IP address.

• host_type (Literal['host', 'domain'] | None) – Filter by type (‘host’ or ‘domain’).

• **kwargs (Any) – Additional filter arguments.

Returns:

List of NetworkHost objects sorted by hostname.

Return type:

list[NetworkHost]

get(key=None, *, hostname=None, ip=None, fields=None)

Get a host override by key, hostname, or IP address.

Parameters:

• key (int | None) – Host $key (ID).

• hostname (str | None) – Hostname of the override.

• ip (str | None) – IP address of the override.

• fields (list[str] | None) – List of fields to return.

Returns:

NetworkHost object.

Raises:

• NotFoundError – If host not found.

• ValueError – If no identifier provided.

Return type:

NetworkHost

create(hostname, ip, host_type='host')

Create a new DHCP/DNS host override.

Parameters:

• hostname (str) – Hostname or domain name for the override.

• ip (str) – IP address to map to the hostname.

• host_type (Literal['host', 'domain']) – Type of override - ‘host’ (default) or ‘domain’.

Returns:

Created NetworkHost object.

Raises:

ValidationError – If a host with this hostname already exists.

Return type:

NetworkHost

Note

Host override changes require DNS apply to take effect.

update(key, *, hostname=None, ip=None, host_type=None)

Update an existing host override.

Parameters:

• key (int) – Host $key (ID).

• hostname (str | None) – New hostname for the override.

• ip (str | None) – New IP address for the override.

• host_type (Literal['host', 'domain'] | None) – New type (‘host’ or ‘domain’).

Returns:

Updated NetworkHost object.

Raises:

• NotFoundError – If host not found.

• ValueError – If no update fields provided.

Return type:

NetworkHost

Note

Host override changes require DNS apply to take effect.

delete(key)

Delete a host override.

Parameters:

key (int) – Host $key (ID).

Return type:

None

Note

Host override changes require DNS apply to take effect.

Network Statistics

Network performance monitoring and topology discovery.

Network Stats & Monitoring resource managers.

This module provides access to network performance metrics, dashboard, and VPN connection tracking for monitoring and troubleshooting.

Example

>>> # Access network monitor stats
>>> network = client.networks.get(name="External")
>>> stats = network.stats.get()
>>> print(f"Quality: {stats.quality}%, Latency: {stats.latency_avg_ms}ms")

>>> # Access stats history
>>> history = network.stats.history_short(limit=100)
>>> for point in history:
...     print(f"{point.timestamp}: Quality {point.quality}%")

>>> # Access network dashboard
>>> dashboard = client.network_dashboard.get()
>>> print(f"Online: {dashboard.vnets_online}/{dashboard.vnets_count}")

>>> # Access active IPSec connections
>>> for conn in network.ipsec_connections.list():
...     print(f"{conn.local} <-> {conn.remote}: {conn.protocol}")

>>> # Access WireGuard peer status
>>> for wg in network.wireguard.list():
...     for status in wg.peer_status.list():
...         print(f"{status.peer_key}: TX {status.tx_bytes_formatted}")

class pyvergeos.resources.network_stats.NetworkMonitorStats

Bases: ResourceObject

Network monitor statistics resource object.

Provides current network quality and performance metrics from the most recent monitoring sample.

property vnet_key: int

Parent network key.

property timestamp: datetime | None

Timestamp for this stats sample.

property timestamp_epoch: int

Timestamp as Unix epoch.

property sent: int

Number of monitoring packets sent.

property dropped: int

Number of monitoring packets dropped.

property quality: int

Network quality percentage (0-100, higher is better).

property dropped_pct: int

Packet drop percentage (0-100).

property latency_usec_avg: int

Average latency in microseconds.

property latency_usec_peak: int

Peak latency in microseconds.

property latency_avg_ms: float

Average latency in milliseconds.

property latency_peak_ms: float

Peak latency in milliseconds.

property duplicates: int

Number of duplicate packets received.

property truncated: int

Number of truncated packets received.

property bad_checksums: int

Number of packets with bad checksums.

property bad_data: int

Number of packets with bad data.

property has_issues: bool

Check if there are any packet quality issues.

property is_healthy: bool

Check if network quality is good (>= 95%).

class pyvergeos.resources.network_stats.NetworkMonitorStatsHistory

Bases: ResourceObject

Network monitor statistics history record.

Represents a single time point in the network monitoring history.

property vnet_key: int

Parent network key.

property timestamp: datetime | None

Timestamp for this history point.

property timestamp_epoch: int

Timestamp as Unix epoch.

property sent: int

Number of monitoring packets sent.

property dropped: int

Number of monitoring packets dropped.

property quality: int

Network quality percentage (0-100).

property dropped_pct: int

Packet drop percentage (0-100).

property latency_usec_avg: int

Average latency in microseconds.

property latency_usec_peak: int

Peak latency in microseconds.

property latency_avg_ms: float

Average latency in milliseconds.

property latency_peak_ms: float

Peak latency in milliseconds.

property duplicates: int

Number of duplicate packets.

property truncated: int

Number of truncated packets.

property bad_checksums: int

Number of packets with bad checksums.

property bad_data: int

Number of packets with bad data.

class pyvergeos.resources.network_stats.NetworkMonitorStatsManager

Bases: ResourceManager[NetworkMonitorStats]

Manager for network monitor statistics.

Provides access to current and historical network quality metrics. Scoped to a specific network.

Example

>>> # Get current stats (most recent sample)
>>> stats = manager.get()
>>> print(f"Quality: {stats.quality}%")

>>> # Get short-term history (high resolution)
>>> history = manager.history_short(limit=100)

>>> # Get long-term history (aggregated, longer retention)
>>> history = manager.history_long(limit=1000)

__init__(client, network)

Parameters:

• client (VergeClient)

• network (Network)

Return type:

None

get(fields=None)

Get the most recent network monitor statistics.

Parameters:

fields (list[str] | None) – List of fields to return.

Returns:

NetworkMonitorStats object with latest metrics.

Raises:

NotFoundError – If no stats found for this network.

Return type:

NetworkMonitorStats

history_short(limit=None, offset=None, since=None, until=None, fields=None)

Get short-term stats history (high resolution).

Short-term history provides granular data points for recent monitoring, typically stored for hours to a few days.

Parameters:

• limit (int | None) – Maximum number of records to return.

• offset (int | None) – Skip this many records.

• since (datetime | int | None) – Return records after this time (datetime or epoch).

• until (datetime | int | None) – Return records before this time (datetime or epoch).

• fields (list[str] | None) – List of fields to return.

Returns:

List of NetworkMonitorStatsHistory objects, sorted by timestamp descending.

Return type:

list[NetworkMonitorStatsHistory]

history_long(limit=None, offset=None, since=None, until=None, fields=None)

Get long-term stats history (aggregated, longer retention).

Long-term history provides aggregated data points (averages, peaks, sums) over longer periods, typically stored for weeks to months.

Parameters:

• limit (int | None) – Maximum number of records to return.

• offset (int | None) – Skip this many records.

• since (datetime | int | None) – Return records after this time (datetime or epoch).

• until (datetime | int | None) – Return records before this time (datetime or epoch).

• fields (list[str] | None) – List of fields to return.

Returns:

List of NetworkMonitorStatsHistory objects, sorted by timestamp descending.

Return type:

list[NetworkMonitorStatsHistory]

class pyvergeos.resources.network_stats.NetworkDashboard

Bases: ResourceObject

Network dashboard with aggregated metrics.

Provides a high-level overview of network status, counts by type and state, and top resource consumers for monitoring and capacity planning.

property vnets_count: int

Total number of networks.

property vnets_online: int

Number of online networks.

property vnets_warn: int

Number of networks in warning state.

property vnets_error: int

Number of networks in error state.

property vnets_offline: int

Number of offline networks.

property ext_count: int

Total external networks.

property ext_online: int

Online external networks.

property ext_warn: int

External networks in warning state.

property ext_error: int

External networks in error state.

property int_count: int

Total internal networks.

property int_online: int

Online internal networks.

property int_warn: int

Internal networks in warning state.

property int_error: int

Internal networks in error state.

property ten_count: int

Total tenant networks.

property ten_online: int

Online tenant networks.

property ten_warn: int

Tenant networks in warning state.

property ten_error: int

Tenant networks in error state.

property vpn_count: int

Total VPN networks.

property vpn_online: int

Online VPN networks.

property vpn_warn: int

VPN networks in warning state.

property vpn_error: int

VPN networks in error state.

property nics_count: int

Total network interfaces.

property nics_online: int

Online network interfaces.

property nics_warn: int

Network interfaces in warning state.

property nics_error: int

Network interfaces in error state.

property wireguards_count: int

Total WireGuard interfaces.

property running_ext_vnets: list[dict[str, Any]]

Top running external networks by throughput.

property running_int_vnets: list[dict[str, Any]]

Top running internal networks by throughput.

property running_tenant_vnets: list[dict[str, Any]]

Top running tenant networks by throughput.

property nics_rate: list[dict[str, Any]]

Top network interfaces by throughput rate.

property logs: list[dict[str, Any]]

Recent network-related logs.

get_health_summary()

Get a summary of network health across all types.

Returns:

Dictionary with health counts by network type.

Return type:

dict[str, Any]

property has_errors: bool

Check if any networks are in error state.

property has_warnings: bool

Check if any networks are in warning state.

class pyvergeos.resources.network_stats.NetworkDashboardManager

Bases: ResourceManager[NetworkDashboard]

Manager for network dashboard.

Provides aggregated network metrics and status counts for monitoring.

Example

>>> dashboard = client.network_dashboard.get()
>>> print(f"Online: {dashboard.vnets_online}/{dashboard.vnets_count}")
>>> print(f"Errors: {dashboard.vnets_error}")
>>> if dashboard.has_errors:
...     print("WARNING: Networks in error state!")

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

get()

Get network dashboard.

Returns:

NetworkDashboard object with aggregated metrics.

Return type:

NetworkDashboard

class pyvergeos.resources.network_stats.IPSecActiveConnection

Bases: ResourceObject

Active IPSec VPN connection (non-persistent/computed).

Represents a currently established IPSec tunnel with connection details. This data is computed from strongSwan status and is not stored in the database.

property vnet_key: int

Parent network key.

property phase1_key: int | None

Phase 1 (IKE SA) configuration key.

property phase2_key: int | None

Phase 2 (Child SA) configuration key.

property uniqueid: int

Unique identifier for this connection instance.

property local: str

Local endpoint address.

property remote: str

Remote endpoint address.

property local_network: str

Local network/subnet (CIDR).

property remote_network: str

Remote network/subnet (CIDR).

property connection: str

Connection name.

property reqid: str

Request ID.

property interface: str

Interface name.

property protocol: str

Protocol (ESP, AH, etc.).

property created_at: datetime | None

Timestamp when connection was established.

class pyvergeos.resources.network_stats.IPSecActiveConnectionManager

Bases: ResourceManager[IPSecActiveConnection]

Manager for active IPSec connections.

Provides access to currently established IPSec VPN tunnels. This is a read-only, non-persistent view of active connection state. Scoped to a specific network.

Example

>>> # List all active IPSec connections
>>> for conn in network.ipsec_connections.list():
...     print(f"{conn.local} <-> {conn.remote}")
...     print(f"  Protocol: {conn.protocol}")
...     print(f"  Local Network: {conn.local_network}")
...     print(f"  Remote Network: {conn.remote_network}")

__init__(client, network)

Parameters:

• client (VergeClient)

• network (Network)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List active IPSec connections for this network.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Additional filter parameters (ignored for scoped manager).

Returns:

List of IPSecActiveConnection objects.

Return type:

list[IPSecActiveConnection]

count()

Get count of active IPSec connections.

Returns:

Number of active connections.

Return type:

int

class pyvergeos.resources.network_stats.WireGuardPeerStatus

Bases: ResourceObject

WireGuard peer connection status.

Provides real-time status information for a WireGuard peer including handshake time and transfer statistics.

property peer_key: int

Peer configuration key.

property last_handshake: datetime | None

Timestamp of last successful handshake.

property last_handshake_epoch: int

Last handshake as Unix epoch.

property tx_bytes: int

Total bytes transmitted to peer.

property rx_bytes: int

Total bytes received from peer.

property tx_bytes_formatted: str

Human-readable bytes transmitted.

property rx_bytes_formatted: str

Human-readable bytes received.

property last_update: datetime | None

Timestamp of last status update.

property is_connected: bool

Check if peer has had a recent handshake (within 3 minutes).

class pyvergeos.resources.network_stats.WireGuardPeerStatusManager

Bases: ResourceManager[WireGuardPeerStatus]

Manager for WireGuard peer status.

Provides access to real-time connection status for WireGuard peers. Scoped to a specific WireGuard interface.

Example

>>> # List peer status for a WireGuard interface
>>> for wg in network.wireguard.list():
...     for status in wg.peer_status.list():
...         if status.is_connected:
...             print(f"Peer {status.peer_key}: {status.tx_bytes_formatted} TX")

__init__(client, wireguard)

Parameters:

• client (VergeClient)

• wireguard (WireGuardInterface)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List peer status for this WireGuard interface.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Additional filter parameters (ignored for scoped manager).

Returns:

List of WireGuardPeerStatus objects.

Return type:

list[WireGuardPeerStatus]

get_for_peer(peer_key)

Get status for a specific peer.

Parameters:

peer_key (int) – Peer $key (ID).

Returns:

WireGuardPeerStatus object.

Raises:

NotFoundError – If status not found for this peer.

Return type:

WireGuardPeerStatus

Routing Protocols

BGP, OSPF, and EIGRP configuration for enterprise deployments.

Network routing protocol resource managers (BGP, OSPF, EIGRP).

class pyvergeos.resources.routing.BGPRouterCommand

Bases: ResourceObject

BGP router command object.

Commands configure BGP router behavior including neighbors, networks, redistribution, and protocol settings.

property command_type: str

Get the command type (neighbor, network, redistribute, etc.).

property params: str

Get the command parameters.

property is_enabled: bool

Check if the command is enabled.

property is_negated: bool

Check if the command is negated (no prefix).

property order_id: int

Get the command order ID.

class pyvergeos.resources.routing.BGPRouterCommandManager

Bases: ResourceManager[BGPRouterCommand]

Manager for BGP router commands.

Commands configure the BGP router including neighbors, networks, redistribution, and other protocol settings.

Examples

List commands for a router:

commands = router.commands.list()

Add a neighbor:

router.commands.create(
    command="neighbor",
    params="192.168.1.1 remote-as 65001"
)

Add a network advertisement:

router.commands.create(
    command="network",
    params="10.0.0.0/24"
)

__init__(client, router)

Parameters:

• client (VergeClient)

• router (BGPRouter)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List commands for this BGP router.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of BGPRouterCommand objects.

Return type:

list[BGPRouterCommand]

get(key=None, *, fields=None)

Get a single command by key.

Parameters:

• key (int | None) – Command $key (ID).

• fields (list[str] | None) – List of fields to return.

Returns:

BGPRouterCommand object.

Raises:

• NotFoundError – If command not found.

• ValueError – If key not provided.

Return type:

BGPRouterCommand

create(command, params, *, enabled=True, negate=False)

Create a new BGP router command.

Parameters:

• command (Literal['aggregate-address', 'bgp', 'bmp', 'coalesce-time', 'distance', 'maximum-paths', 'neighbor', 'network', 'read-quanta', 'redistribute', 'segment-routing', 'table-map', 'timers', 'update-delay', 'vnc', 'vrf-policy', 'write-quanta']) – Command type (neighbor, network, redistribute, etc.).

• params (str) – Command parameters.

• enabled (bool) – Whether the command is enabled.

• negate (bool) – Whether to negate the command (no prefix).

Returns:

Created BGPRouterCommand object.

Return type:

BGPRouterCommand

Examples

Add a BGP neighbor:

cmd = router.commands.create(
    command="neighbor",
    params="192.168.1.1 remote-as 65001"
)

Advertise a network:

cmd = router.commands.create(
    command="network",
    params="10.0.0.0/24"
)

Redistribute connected routes:

cmd = router.commands.create(
    command="redistribute",
    params="connected"
)

update(key, **kwargs)

Update an existing command.

Parameters:

• key (int) – Command $key (ID).

• **kwargs (Any) – Attributes to update (command, params, enabled, negate).

Returns:

Updated BGPRouterCommand object.

Return type:

BGPRouterCommand

delete(key)

Delete a command.

Parameters:

key (int) – Command $key (ID).

Return type:

None

class pyvergeos.resources.routing.BGPRouter

Bases: ResourceObject

BGP router object.

A BGP router defines an autonomous system number (ASN) and contains commands for configuring neighbors, networks, and other BGP settings.

property asn: int

Get the Autonomous System Number.

property commands: BGPRouterCommandManager

Access commands for this BGP router.

Returns:

BGPRouterCommandManager for this router.

Examples

List commands:

commands = router.commands.list()

Add a neighbor:

router.commands.create(
    command="neighbor",
    params="192.168.1.1 remote-as 65001"
)

class pyvergeos.resources.routing.BGPRouterManager

Bases: ResourceManager[BGPRouter]

Manager for BGP routers.

BGP routers define the local autonomous system and contain configuration for BGP neighbors, networks, and policies.

Examples

List BGP routers:

routers = network.routing.bgp_routers.list()

Create a BGP router:

router = network.routing.bgp_routers.create(asn=65000)

Add a neighbor to the router:

router.commands.create(
    command="neighbor",
    params="192.168.1.1 remote-as 65001"
)

__init__(client, routing_manager)

Parameters:

• client (VergeClient)

• routing_manager (NetworkRoutingManager)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List BGP routers for this network.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of BGPRouter objects.

Return type:

list[BGPRouter]

get(key=None, *, asn=None, fields=None)

Get a single BGP router by key or ASN.

Parameters:

• key (int | None) – Router $key (ID).

• asn (int | None) – Autonomous System Number.

• fields (list[str] | None) – List of fields to return.

Returns:

BGPRouter object.

Raises:

• NotFoundError – If router not found.

• ValueError – If neither key nor asn provided.

Return type:

BGPRouter

create(asn)

Create a new BGP router.

Parameters:

asn (int) – Autonomous System Number (1-4294967295).

Returns:

Created BGPRouter object.

Return type:

BGPRouter

Examples

Create a BGP router:

router = network.routing.bgp_routers.create(asn=65000)

update(key, **kwargs)

Update an existing BGP router.

Parameters:

• key (int) – Router $key (ID).

• **kwargs (Any) – Attributes to update (asn).

Returns:

Updated BGPRouter object.

Return type:

BGPRouter

delete(key)

Delete a BGP router.

This also removes all associated commands.

Parameters:

key (int) – Router $key (ID).

Return type:

None

class pyvergeos.resources.routing.BGPInterfaceCommand

Bases: ResourceObject

BGP interface command object.

property command_type: str

Get the command type.

property params: str

Get the command parameters.

property order_id: int

Get the command order ID.

class pyvergeos.resources.routing.BGPInterfaceCommandManager

Bases: ResourceManager[BGPInterfaceCommand]

Manager for BGP interface commands.

Commands configure the BGP interface including IP settings, OSPF parameters, and link detection.

Examples

List commands:

commands = interface.commands.list()

Add OSPF cost:

interface.commands.create(
    command="ospf",
    params="cost 10"
)

__init__(client, interface)

Parameters:

• client (VergeClient)

• interface (BGPInterface)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List commands for this interface.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of BGPInterfaceCommand objects.

Return type:

list[BGPInterfaceCommand]

get(key=None, *, fields=None)

Get a single command by key.

Parameters:

• key (int | None) – Command $key (ID).

• fields (list[str] | None) – List of fields to return.

Returns:

BGPInterfaceCommand object.

Raises:

• NotFoundError – If command not found.

• ValueError – If key not provided.

Return type:

BGPInterfaceCommand

create(command, params)

Create a new interface command.

Parameters:

• command (Literal['bandwidth', 'description', 'ip', 'link-detect', 'mpls-te', 'multicast', 'no', 'ospf']) – Command type (ip, ospf, bandwidth, etc.).

• params (str) – Command parameters.

Returns:

Created BGPInterfaceCommand object.

Return type:

BGPInterfaceCommand

Examples

Set OSPF cost:

cmd = interface.commands.create(
    command="ospf",
    params="cost 10"
)

update(key, **kwargs)

Update an existing command.

Parameters:

• key (int) – Command $key (ID).

• **kwargs (Any) – Attributes to update (command, params).

Returns:

Updated BGPInterfaceCommand object.

Return type:

BGPInterfaceCommand

delete(key)

Delete a command.

Parameters:

key (int) – Command $key (ID).

Return type:

None

class pyvergeos.resources.routing.BGPInterface

Bases: ResourceObject

BGP interface object.

A BGP interface creates a Layer 2/3 connection for routing protocols. It creates an associated virtual network and NIC automatically.

property ip_address: str

Get the interface IP address.

property network_address: str

Get the network address (CIDR).

property mtu: int

Get the MTU size.

property layer2_type: str

Get the Layer 2 type (vlan or none).

property layer2_id: int | None

Get the Layer 2 ID (VLAN ID).

property interface_vnet: int | None

Get the interface (uplink) network key.

property commands: BGPInterfaceCommandManager

Access commands for this interface.

Returns:

BGPInterfaceCommandManager for this interface.

Examples

List commands:

commands = interface.commands.list()

Add OSPF cost:

interface.commands.create(
    command="ospf",
    params="cost 10"
)

class pyvergeos.resources.routing.BGPInterfaceManager

Bases: ResourceManager[BGPInterface]

Manager for BGP interfaces.

BGP interfaces create Layer 2/3 connections for routing protocols. Each interface automatically creates an associated virtual network and NIC.

Examples

List interfaces:

interfaces = network.routing.bgp_interfaces.list()

Create an interface:

interface = network.routing.bgp_interfaces.create(
    name="bgp-peer-1",
    ip_address="10.255.0.1",
    network="10.255.0.0/30",
    interface_network=external_net.key,
    layer2_id=100
)

__init__(client, routing_manager)

Parameters:

• client (VergeClient)

• routing_manager (NetworkRoutingManager)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List BGP interfaces for this network.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of BGPInterface objects.

Return type:

list[BGPInterface]

get(key=None, *, name=None, fields=None)

Get a single BGP interface by key or name.

Parameters:

• key (int | None) – Interface $key (ID).

• name (str | None) – Interface name.

• fields (list[str] | None) – List of fields to return.

Returns:

BGPInterface object.

Raises:

• NotFoundError – If interface not found.

• ValueError – If neither key nor name provided.

Return type:

BGPInterface

create(name, ip_address, network, interface_network, *, layer2_type='vlan', layer2_id=None, mtu=9000, description='')

Create a new BGP interface.

Parameters:

• name (str) – Interface name.

• ip_address (str) – IP address for this interface.

• network (str) – Network address in CIDR notation (e.g., “10.255.0.0/30”).

• interface_network (int) – Key of the interface (uplink) network.

• layer2_type (Literal['vlan', 'none']) – Layer 2 type (vlan or none).

• layer2_id (int | None) – VLAN ID (required if layer2_type is vlan).

• mtu (int) – MTU size (1000-65536, default 9000).

• description (str) – Interface description.

Returns:

Created BGPInterface object.

Return type:

BGPInterface

Examples

Create a BGP peering interface:

interface = network.routing.bgp_interfaces.create(
    name="bgp-peer-isp",
    ip_address="198.51.100.2",
    network="198.51.100.0/30",
    interface_network=external_net.key,
    layer2_type="vlan",
    layer2_id=100
)

update(key, **kwargs)

Update an existing BGP interface.

Parameters:

• key (int) – Interface $key (ID).

• **kwargs (Any) – Attributes to update.

Returns:

Updated BGPInterface object.

Return type:

BGPInterface

delete(key)

Delete a BGP interface.

This also removes the associated virtual network and NIC.

Parameters:

key (int) – Interface $key (ID).

Return type:

None

class pyvergeos.resources.routing.BGPRouteMapCommand

Bases: ResourceObject

BGP route map command object.

property command_type: str

Get the command type (match, set, call, etc.).

property params: str

Get the command parameters.

property order_id: int

Get the command order ID.

class pyvergeos.resources.routing.BGPRouteMapCommandManager

Bases: ResourceManager[BGPRouteMapCommand]

Manager for BGP route map commands.

Commands define match conditions and set actions for route maps.

Examples

List commands:

commands = routemap.commands.list()

Add a match condition:

routemap.commands.create(
    command="match",
    params="ip address prefix-list MY-PREFIX"
)

Add a set action:

routemap.commands.create(
    command="set",
    params="local-preference 200"
)

__init__(client, routemap)

Parameters:

• client (VergeClient)

• routemap (BGPRouteMap)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List commands for this route map.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of BGPRouteMapCommand objects.

Return type:

list[BGPRouteMapCommand]

get(key=None, *, fields=None)

Get a single command by key.

Parameters:

• key (int | None) – Command $key (ID).

• fields (list[str] | None) – List of fields to return.

Returns:

BGPRouteMapCommand object.

Raises:

• NotFoundError – If command not found.

• ValueError – If key not provided.

Return type:

BGPRouteMapCommand

create(command, params)

Create a new route map command.

Parameters:

• command (Literal['call', 'continue', 'description', 'match', 'on', 'set']) – Command type (match, set, call, etc.).

• params (str) – Command parameters.

Returns:

Created BGPRouteMapCommand object.

Return type:

BGPRouteMapCommand

Examples

Add a match condition:

cmd = routemap.commands.create(
    command="match",
    params="ip address prefix-list MY-PREFIX"
)

Add a set action:

cmd = routemap.commands.create(
    command="set",
    params="local-preference 200"
)

update(key, **kwargs)

Update an existing command.

Parameters:

• key (int) – Command $key (ID).

• **kwargs (Any) – Attributes to update (command, params).

Returns:

Updated BGPRouteMapCommand object.

Return type:

BGPRouteMapCommand

delete(key)

Delete a command.

Parameters:

key (int) – Command $key (ID).

Return type:

None

class pyvergeos.resources.routing.BGPRouteMap

Bases: ResourceObject

BGP route map object.

Route maps are used to filter and modify BGP routes. Each route map entry has a tag, sequence number, and permit/deny action.

property tag: str

Get the route map tag (name).

property sequence: int

Get the sequence number.

property is_permit: bool

Check if this is a permit entry (vs deny).

property commands: BGPRouteMapCommandManager

Access commands for this route map.

Returns:

BGPRouteMapCommandManager for this route map.

Examples

List commands:

commands = routemap.commands.list()

Add a match condition:

routemap.commands.create(
    command="match",
    params="ip address prefix-list MY-PREFIX"
)

class pyvergeos.resources.routing.BGPRouteMapManager

Bases: ResourceManager[BGPRouteMap]

Manager for BGP route maps.

Route maps filter and modify BGP routes. Multiple entries with the same tag form a route map; entries are evaluated by sequence number.

Examples

List route maps:

routemaps = network.routing.bgp_route_maps.list()

Create a route map entry:

routemap = network.routing.bgp_route_maps.create(
    tag="IMPORT-FROM-ISP",
    sequence=10,
    permit=True
)

Add match/set commands:

routemap.commands.create(command="match", params="as-path 1")
routemap.commands.create(command="set", params="local-preference 200")

__init__(client, routing_manager)

Parameters:

• client (VergeClient)

• routing_manager (NetworkRoutingManager)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List route maps for this network.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of BGPRouteMap objects.

Return type:

list[BGPRouteMap]

get(key=None, *, tag=None, sequence=None, fields=None)

Get a single route map by key or tag+sequence.

Parameters:

• key (int | None) – Route map $key (ID).

• tag (str | None) – Route map tag (use with sequence).

• sequence (int | None) – Sequence number (use with tag).

• fields (list[str] | None) – List of fields to return.

Returns:

BGPRouteMap object.

Raises:

• NotFoundError – If route map not found.

• ValueError – If invalid parameters.

Return type:

BGPRouteMap

create(tag, sequence, *, permit=True)

Create a new route map entry.

Parameters:

• tag (str) – Route map tag/name.

• sequence (int) – Sequence number (1-65535).

• permit (bool) – Whether this is a permit (True) or deny (False) entry.

Returns:

Created BGPRouteMap object.

Return type:

BGPRouteMap

Examples

Create a permit entry:

routemap = network.routing.bgp_route_maps.create(
    tag="IMPORT-FROM-ISP",
    sequence=10,
    permit=True
)

Create a deny entry:

routemap = network.routing.bgp_route_maps.create(
    tag="BLOCK-PRIVATE",
    sequence=10,
    permit=False
)

update(key, **kwargs)

Update an existing route map.

Parameters:

• key (int) – Route map $key (ID).

• **kwargs (Any) – Attributes to update (tag, sequence, permit).

Returns:

Updated BGPRouteMap object.

Return type:

BGPRouteMap

delete(key)

Delete a route map entry.

This also removes all associated commands.

Parameters:

key (int) – Route map $key (ID).

Return type:

None

class pyvergeos.resources.routing.BGPIPCommand

Bases: ResourceObject

BGP IP command object.

IP commands configure prefix lists, AS path lists, community lists, and other IP-level BGP settings.

property command_type: str

Get the command type (prefix-list, as-path, etc.).

property params: str

Get the command parameters.

property order_id: int

Get the command order ID.

class pyvergeos.resources.routing.BGPIPCommandManager

Bases: ResourceManager[BGPIPCommand]

Manager for BGP IP commands.

IP commands configure prefix lists, AS path access lists, community lists, and other IP-level BGP configuration.

Examples

List IP commands:

commands = network.routing.bgp_ip_commands.list()

Create a prefix list:

network.routing.bgp_ip_commands.create(
    command="prefix-list",
    params="MY-PREFIXES seq 10 permit 10.0.0.0/8 le 24"
)

Create an AS path access list:

network.routing.bgp_ip_commands.create(
    command="as-path",
    params="access-list 1 permit ^65001$"
)

__init__(client, routing_manager)

Parameters:

• client (VergeClient)

• routing_manager (NetworkRoutingManager)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List IP commands for this network.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of BGPIPCommand objects.

Return type:

list[BGPIPCommand]

get(key=None, *, fields=None)

Get a single IP command by key.

Parameters:

• key (int | None) – Command $key (ID).

• fields (list[str] | None) – List of fields to return.

Returns:

BGPIPCommand object.

Raises:

• NotFoundError – If command not found.

• ValueError – If key not provided.

Return type:

BGPIPCommand

create(command, params)

Create a new IP command.

Parameters:

• command (Literal['as-path', 'community-list', 'extcommunity-list', 'forwarding', 'mroute', 'multicast', 'multicast-routing', 'ospf', 'prefix-list', 'protocol', 'route', 'ssmpingd']) – Command type (prefix-list, as-path, community-list, etc.).

• params (str) – Command parameters.

Returns:

Created BGPIPCommand object.

Return type:

BGPIPCommand

Examples

Create a prefix list:

cmd = network.routing.bgp_ip_commands.create(
    command="prefix-list",
    params="MY-PREFIXES seq 10 permit 10.0.0.0/8 le 24"
)

Create an AS path access list:

cmd = network.routing.bgp_ip_commands.create(
    command="as-path",
    params="access-list 1 permit ^65001$"
)

Create a community list:

cmd = network.routing.bgp_ip_commands.create(
    command="community-list",
    params="standard COMMUNITY-1 permit 65000:100"
)

update(key, **kwargs)

Update an existing IP command.

Parameters:

• key (int) – Command $key (ID).

• **kwargs (Any) – Attributes to update (command, params).

Returns:

Updated BGPIPCommand object.

Return type:

BGPIPCommand

delete(key)

Delete an IP command.

Parameters:

key (int) – Command $key (ID).

Return type:

None

class pyvergeos.resources.routing.OSPFCommand

Bases: ResourceObject

OSPF command object.

OSPF commands configure the OSPF routing protocol including areas, networks, redistribution, and timers.

property command_type: str

Get the command type (area, network, redistribute, etc.).

property params: str

Get the command parameters.

property order_id: int

Get the command order ID.

class pyvergeos.resources.routing.OSPFCommandManager

Bases: ResourceManager[OSPFCommand]

Manager for OSPF commands.

OSPF commands configure the OSPF routing protocol including areas, networks, redistribution, router ID, and timers.

Examples

List OSPF commands:

commands = network.routing.ospf_commands.list()

Set router ID:

network.routing.ospf_commands.create(
    command="router-id",
    params="1.1.1.1"
)

Add network to OSPF:

network.routing.ospf_commands.create(
    command="network",
    params="10.0.0.0/24 area 0"
)

Configure an area:

network.routing.ospf_commands.create(
    command="area",
    params="0 authentication message-digest"
)

__init__(client, routing_manager)

Parameters:

• client (VergeClient)

• routing_manager (NetworkRoutingManager)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List OSPF commands for this network.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of OSPFCommand objects.

Return type:

list[OSPFCommand]

get(key=None, *, fields=None)

Get a single OSPF command by key.

Parameters:

• key (int | None) – Command $key (ID).

• fields (list[str] | None) – List of fields to return.

Returns:

OSPFCommand object.

Raises:

• NotFoundError – If command not found.

• ValueError – If key not provided.

Return type:

OSPFCommand

create(command, params)

Create a new OSPF command.

Parameters:

• command (Literal['advanced', 'area', 'auto-cost', 'capability', 'default-information', 'default-metric', 'distance', 'distribute-list', 'log-adjacency-changes', 'max-metric', 'mpls-te', 'neighbor', 'network', 'no', 'ospf', 'passive-interface', 'redistribute', 'router-id', 'timers']) – Command type (area, network, redistribute, etc.).

• params (str) – Command parameters.

Returns:

Created OSPFCommand object.

Return type:

OSPFCommand

Examples

Set router ID:

cmd = network.routing.ospf_commands.create(
    command="router-id",
    params="1.1.1.1"
)

Add network to OSPF area 0:

cmd = network.routing.ospf_commands.create(
    command="network",
    params="10.0.0.0/24 area 0"
)

Configure area authentication:

cmd = network.routing.ospf_commands.create(
    command="area",
    params="0 authentication message-digest"
)

Redistribute BGP routes:

cmd = network.routing.ospf_commands.create(
    command="redistribute",
    params="bgp metric 100"
)

Set passive interface:

cmd = network.routing.ospf_commands.create(
    command="passive-interface",
    params="default"
)

update(key, **kwargs)

Update an existing OSPF command.

Parameters:

• key (int) – Command $key (ID).

• **kwargs (Any) – Attributes to update (command, params).

Returns:

Updated OSPFCommand object.

Return type:

OSPFCommand

delete(key)

Delete an OSPF command.

Parameters:

key (int) – Command $key (ID).

Return type:

None

class pyvergeos.resources.routing.EIGRPRouterCommand

Bases: ResourceObject

EIGRP router command object.

property command_type: str

Get the command type (network, redistribute, etc.).

property params: str

Get the command parameters.

property is_enabled: bool

Check if the command is enabled.

property is_negated: bool

Check if the command is negated (no prefix).

property order_id: int

Get the command order ID.

class pyvergeos.resources.routing.EIGRPRouterCommandManager

Bases: ResourceManager[EIGRPRouterCommand]

Manager for EIGRP router commands.

Commands configure EIGRP router behavior including networks, redistribution, metrics, and neighbors.

Examples

List commands:

commands = router.commands.list()

Add a network:

router.commands.create(
    command="network",
    params="10.0.0.0/24"
)

Redistribute OSPF:

router.commands.create(
    command="redistribute",
    params="ospf"
)

__init__(client, router)

Parameters:

• client (VergeClient)

• router (EIGRPRouter)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List commands for this EIGRP router.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of EIGRPRouterCommand objects.

Return type:

list[EIGRPRouterCommand]

get(key=None, *, fields=None)

Get a single command by key.

Parameters:

• key (int | None) – Command $key (ID).

• fields (list[str] | None) – List of fields to return.

Returns:

EIGRPRouterCommand object.

Raises:

• NotFoundError – If command not found.

• ValueError – If key not provided.

Return type:

EIGRPRouterCommand

create(command, params, *, enabled=True, negate=False)

Create a new EIGRP router command.

Parameters:

• command (Literal['eigrp', 'coalesce-time', 'maximum-paths', 'metric', 'neighbor', 'network', 'passive-interface', 'redistribute', 'timers', 'variance']) – Command type (network, redistribute, metric, etc.).

• params (str) – Command parameters.

• enabled (bool) – Whether the command is enabled.

• negate (bool) – Whether to negate the command (no prefix).

Returns:

Created EIGRPRouterCommand object.

Return type:

EIGRPRouterCommand

Examples

Add a network:

cmd = router.commands.create(
    command="network",
    params="10.0.0.0/24"
)

Redistribute OSPF:

cmd = router.commands.create(
    command="redistribute",
    params="ospf"
)

Set variance:

cmd = router.commands.create(
    command="variance",
    params="2"
)

update(key, **kwargs)

Update an existing command.

Parameters:

• key (int) – Command $key (ID).

• **kwargs (Any) – Attributes to update (command, params, enabled, negate).

Returns:

Updated EIGRPRouterCommand object.

Return type:

EIGRPRouterCommand

delete(key)

Delete a command.

Parameters:

key (int) – Command $key (ID).

Return type:

None

class pyvergeos.resources.routing.EIGRPRouter

Bases: ResourceObject

EIGRP router object.

An EIGRP router defines an autonomous system number (ASN) and contains commands for configuring networks, redistribution, and other settings.

property asn: int

Get the Autonomous System Number.

property commands: EIGRPRouterCommandManager

Access commands for this EIGRP router.

Returns:

EIGRPRouterCommandManager for this router.

Examples

List commands:

commands = router.commands.list()

Add a network:

router.commands.create(
    command="network",
    params="10.0.0.0/24"
)

class pyvergeos.resources.routing.EIGRPRouterManager

Bases: ResourceManager[EIGRPRouter]

Manager for EIGRP routers.

EIGRP (Enhanced Interior Gateway Routing Protocol) is a Cisco-developed routing protocol. EIGRP routers define the AS number and contain configuration for networks, redistribution, and metrics.

Examples

List EIGRP routers:

routers = network.routing.eigrp_routers.list()

Create an EIGRP router:

router = network.routing.eigrp_routers.create(asn=100)

Add a network:

router.commands.create(
    command="network",
    params="10.0.0.0/24"
)

__init__(client, routing_manager)

Parameters:

• client (VergeClient)

• routing_manager (NetworkRoutingManager)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List EIGRP routers for this network.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of EIGRPRouter objects.

Return type:

list[EIGRPRouter]

get(key=None, *, asn=None, fields=None)

Get a single EIGRP router by key or ASN.

Parameters:

• key (int | None) – Router $key (ID).

• asn (int | None) – Autonomous System Number.

• fields (list[str] | None) – List of fields to return.

Returns:

EIGRPRouter object.

Raises:

• NotFoundError – If router not found.

• ValueError – If neither key nor asn provided.

Return type:

EIGRPRouter

create(asn)

Create a new EIGRP router.

Parameters:

asn (int) – Autonomous System Number (1-65535).

Returns:

Created EIGRPRouter object.

Return type:

EIGRPRouter

Examples

Create an EIGRP router:

router = network.routing.eigrp_routers.create(asn=100)

update(key, **kwargs)

Update an existing EIGRP router.

Parameters:

• key (int) – Router $key (ID).

• **kwargs (Any) – Attributes to update (asn).

Returns:

Updated EIGRPRouter object.

Return type:

EIGRPRouter

delete(key)

Delete an EIGRP router.

This also removes all associated commands.

Parameters:

key (int) – Router $key (ID).

Return type:

None

class pyvergeos.resources.routing.NetworkRoutingManager

Bases: object

Manager for network routing protocols (BGP, OSPF, EIGRP).

This is the main entry point for configuring dynamic routing protocols on a VergeOS virtual network.

Examples

Access routing configuration:

routing = network.routing

Configure BGP:

# Create a BGP router
bgp = routing.bgp_routers.create(asn=65000)

# Add a neighbor
bgp.commands.create(
    command="neighbor",
    params="192.168.1.1 remote-as 65001"
)

# Advertise networks
bgp.commands.create(
    command="network",
    params="10.0.0.0/24"
)

Configure OSPF:

# Set router ID
routing.ospf_commands.create(
    command="router-id",
    params="1.1.1.1"
)

# Add network to area 0
routing.ospf_commands.create(
    command="network",
    params="10.0.0.0/24 area 0"
)

Configure EIGRP:

# Create an EIGRP router
eigrp = routing.eigrp_routers.create(asn=100)

# Add network
eigrp.commands.create(
    command="network",
    params="10.0.0.0/24"
)

Note

Routing configuration changes require restarting the network for changes to take effect.

__init__(client, network)

Parameters:

• client (VergeClient)

• network (Network)

Return type:

None

property bgp_routers: BGPRouterManager

Access BGP routers for this network.

Returns:

BGPRouterManager for this network.

Examples

List BGP routers:

routers = network.routing.bgp_routers.list()

Create a router:

router = network.routing.bgp_routers.create(asn=65000)

property bgp_interfaces: BGPInterfaceManager

Access BGP interfaces for this network.

Returns:

BGPInterfaceManager for this network.

Examples

List interfaces:

interfaces = network.routing.bgp_interfaces.list()

Create an interface:

interface = network.routing.bgp_interfaces.create(
    name="peer-1",
    ip_address="10.255.0.1",
    network="10.255.0.0/30",
    interface_network=external.key
)

property bgp_route_maps: BGPRouteMapManager

Access BGP route maps for this network.

Returns:

BGPRouteMapManager for this network.

Examples

List route maps:

maps = network.routing.bgp_route_maps.list()

Create a route map:

rmap = network.routing.bgp_route_maps.create(
    tag="IMPORT",
    sequence=10,
    permit=True
)

property bgp_ip_commands: BGPIPCommandManager

Access BGP IP commands (prefix-lists, as-path lists, etc.).

Returns:

BGPIPCommandManager for this network.

Examples

Create a prefix list:

network.routing.bgp_ip_commands.create(
    command="prefix-list",
    params="MY-PREFIX seq 10 permit 10.0.0.0/8 le 24"
)

property ospf_commands: OSPFCommandManager

Access OSPF commands for this network.

Returns:

OSPFCommandManager for this network.

Examples

Set router ID:

network.routing.ospf_commands.create(
    command="router-id",
    params="1.1.1.1"
)

Add network to OSPF:

network.routing.ospf_commands.create(
    command="network",
    params="10.0.0.0/24 area 0"
)

property eigrp_routers: EIGRPRouterManager

Access EIGRP routers for this network.

Returns:

EIGRPRouterManager for this network.

Examples

List EIGRP routers:

routers = network.routing.eigrp_routers.list()

Create a router:

router = network.routing.eigrp_routers.create(asn=100)

property is_configured: bool

Check if routing is configured for this network.

Returns:

True if a vnet_bgp record exists for this network.

delete_config()

Delete all routing configuration for this network.

This removes the vnet_bgp record and all associated resources (BGP routers, interfaces, route maps, OSPF commands, EIGRP routers).

Warning

This is a destructive operation that removes all routing configuration for the network.

Return type:

None

IPSec VPN

IPSec VPN resource managers.

class pyvergeos.resources.ipsec.IPSecConnection

Bases: ResourceObject

IPSec Phase 1 (IKE) connection object.

property policies: IPSecPolicyManager

Access Phase 2 policies for this connection.

Returns:

IPSecPolicyManager for this connection.

Examples

List all policies:

policies = connection.policies.list()

Create a policy:

policy = connection.policies.create(
    name="LAN-to-LAN",
    local_network="10.0.0.0/24",
    remote_network="192.168.1.0/24"
)

property key_exchange_display: str

Human-readable key exchange version.

property auth_method_display: str

Human-readable authentication method.

property connection_mode_display: str

Human-readable connection mode.

property dpd_action_display: str

Human-readable DPD action.

property is_enabled: bool

Check if connection is enabled.

property remote_gateway: str

Get remote gateway address.

property modified_at: datetime | None

Get last modified timestamp.

class pyvergeos.resources.ipsec.IPSecPolicy

Bases: ResourceObject

IPSec Phase 2 policy (traffic selector) object.

property mode_display: str

Human-readable mode.

property protocol_display: str

Human-readable protocol.

property is_enabled: bool

Check if policy is enabled.

property local_network: str

Get local network CIDR.

property remote_network: str

Get remote network CIDR.

property modified_at: datetime | None

Get last modified timestamp.

class pyvergeos.resources.ipsec.IPSecConnectionManager

Bases: ResourceManager[IPSecConnection]

Manager for IPSec Phase 1 (IKE) connections.

IPSec connections define the IKE security association including remote gateway, authentication, and encryption settings.

This is a sub-resource manager that operates on a specific network.

Examples

List connections on a network:

connections = network.ipsec.list()

Get a connection by name:

conn = network.ipsec.get(name="Site-B")

Create a connection:

conn = network.ipsec.create(
    name="Site-B",
    remote_gateway="203.0.113.1",
    pre_shared_key="MySecretKey123"
)

Access Phase 2 policies:

policies = conn.policies.list()

__init__(client, network)

Parameters:

• client (VergeClient)

• network (Network)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List IPSec connections on this network.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Shorthand filter arguments (e.g., name=”Site-B”).

Returns:

List of IPSecConnection objects.

Return type:

list[IPSecConnection]

get(key=None, *, name=None, fields=None)

Get a single IPSec connection by key or name.

Parameters:

• key (int | None) – Connection $key (ID).

• name (str | None) – Connection name.

• fields (list[str] | None) – List of fields to return.

Returns:

IPSecConnection object.

Raises:

• NotFoundError – If connection not found.

• ValueError – If neither key nor name provided.

Return type:

IPSecConnection

create(name, remote_gateway, pre_shared_key, *, key_exchange='auto', encryption='aes256-sha256-modp2048', ike_lifetime=10800, connection_mode='on_demand', negotiation='main', identifier=None, peer_identifier=None, dpd_action='restart', dpd_delay=30, dpd_failures=5, force_udp_encap=False, mobike=False, split_connections=False, keying_tries=3, rekey=True, reauth=True, margin_time=540, description='', enabled=True)

Create a new IPSec connection.

Parameters:

• name (str) – Unique name for the connection.

• remote_gateway (str) – IP address or hostname of the remote VPN gateway.

• pre_shared_key (str) – Pre-shared key for authentication.

• key_exchange (Literal['auto', 'ikev1', 'ikev2']) – IKE version (auto, ikev1, ikev2).

• encryption (str) – IKE encryption algorithms (e.g., “aes256-sha256-modp2048”).

• ike_lifetime (int) – Lifetime of the IKE SA in seconds (60-86400).

• connection_mode (Literal['responder_only', 'on_demand', 'start']) – Connection behavior (responder_only, on_demand, start).

• negotiation (Literal['main', 'aggressive']) – IKEv1 negotiation mode (main, aggressive).

• identifier (str | None) – Local identifier (defaults to local IP).

• peer_identifier (str | None) – Remote peer identifier (defaults to remote gateway).

• dpd_action (Literal['disabled', 'clear', 'hold', 'restart']) – Dead Peer Detection action (disabled, clear, hold, restart).

• dpd_delay (int) – DPD delay in seconds (0-3600).

• dpd_failures (int) – Number of DPD failures before action (IKEv1 only).

• force_udp_encap (bool) – Force UDP encapsulation even without NAT.

• mobike (bool) – Enable IKEv2 MOBIKE protocol for mobility.

• split_connections (bool) – Split connection entries with multiple Phase 2 configs.

• keying_tries (int) – Number of keying attempts (0 = unlimited).

• rekey (bool) – Whether to renegotiate on expiry.

• reauth (bool) – Whether to reauthenticate on rekey (IKEv2).

• margin_time (int) – Time before expiry to start renegotiation.

• description (str) – Connection description.

• enabled (bool) – Whether the connection is enabled.

Returns:

Created IPSecConnection object.

Return type:

IPSecConnection

Examples

Basic connection:

conn = network.ipsec.create(
    name="Site-B",
    remote_gateway="203.0.113.1",
    pre_shared_key="MySecretKey123"
)

IKEv2 with custom encryption:

conn = network.ipsec.create(
    name="Azure-VPN",
    remote_gateway="azure-vpn.eastus.cloudapp.net",
    pre_shared_key="ComplexKey!@#",
    key_exchange="ikev2",
    encryption="aes256gcm16-sha384-modp2048",
    connection_mode="start"
)

update(key, **kwargs)

Update an existing IPSec connection.

Parameters:

• key (int) – Connection $key (ID).

• **kwargs (Any) – Attributes to update. Supports: - name: New name - remote_gateway: New remote gateway - pre_shared_key: New PSK - key_exchange: New IKE version - encryption: New encryption algorithms - ike_lifetime: New IKE SA lifetime - connection_mode: New connection behavior - negotiation: New negotiation mode - identifier: New local identifier - peer_identifier: New remote identifier - dpd_action: New DPD action - dpd_delay: New DPD delay - dpd_failures: New DPD failure count - force_udp_encap: Enable/disable forced UDP encap - mobike: Enable/disable MOBIKE - split_connections: Enable/disable split connections - keying_tries: New keying tries - rekey: Enable/disable rekey - reauth: Enable/disable reauth - margin_time: New margin time - description: New description - enabled: Enable/disable connection

Returns:

Updated IPSecConnection object.

Return type:

IPSecConnection

delete(key)

Delete an IPSec connection.

This also removes all associated Phase 2 policies.

Parameters:

key (int) – Connection $key (ID).

Return type:

None

class pyvergeos.resources.ipsec.IPSecPolicyManager

Bases: ResourceManager[IPSecPolicy]

Manager for IPSec Phase 2 policies (traffic selectors).

Phase 2 policies define which traffic should be encrypted through the IPSec tunnel. They specify local and remote networks.

This is a sub-resource manager that operates on a specific connection.

Examples

List policies for a connection:

policies = connection.policies.list()

Create a policy:

policy = connection.policies.create(
    name="LAN-to-LAN",
    local_network="10.0.0.0/24",
    remote_network="192.168.1.0/24"
)

Delete a policy:

connection.policies.delete(policy.key)

__init__(client, connection)

Parameters:

• client (VergeClient)

• connection (IPSecConnection)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List Phase 2 policies for this connection.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Shorthand filter arguments (e.g., name=”LAN”).

Returns:

List of IPSecPolicy objects.

Return type:

list[IPSecPolicy]

get(key=None, *, name=None, fields=None)

Get a single Phase 2 policy by key or name.

Parameters:

• key (int | None) – Policy $key (ID).

• name (str | None) – Policy name.

• fields (list[str] | None) – List of fields to return.

Returns:

IPSecPolicy object.

Raises:

• NotFoundError – If policy not found.

• ValueError – If neither key nor name provided.

Return type:

IPSecPolicy

create(name, local_network, remote_network=None, *, mode='tunnel', protocol='esp', ciphers='aes128-sha256-modp2048,aes128gcm128-sha256-modp2048', lifetime=3600, description='', enabled=True)

Create a new Phase 2 policy.

Parameters:

• name (str) – Unique name for the policy.

• local_network (str) – Local network/subnet in CIDR notation (e.g., “10.0.0.0/24”).

• remote_network (str | None) – Remote network/subnet in CIDR notation.

• mode (Literal['tunnel', 'transport']) – IPSec mode (tunnel or transport).

• protocol (Literal['esp', 'ah']) – Security protocol (esp for encrypted, ah for auth only).

• ciphers (str) – Phase 2 cipher suites.

• lifetime (int) – SA lifetime in seconds (60-86400).

• description (str) – Policy description.

• enabled (bool) – Whether the policy is enabled.

Returns:

Created IPSecPolicy object.

Return type:

IPSecPolicy

Examples

Basic LAN-to-LAN policy:

policy = connection.policies.create(
    name="LAN-to-LAN",
    local_network="10.0.0.0/24",
    remote_network="192.168.1.0/24"
)

All traffic through tunnel:

policy = connection.policies.create(
    name="All-Traffic",
    local_network="0.0.0.0/0",
    remote_network="0.0.0.0/0"
)

update(key, **kwargs)

Update an existing Phase 2 policy.

Parameters:

• key (int) – Policy $key (ID).

• **kwargs (Any) – Attributes to update. Supports: - name: New name - local_network: New local network - remote_network: New remote network - mode: New mode (tunnel/transport) - protocol: New protocol (esp/ah) - ciphers: New cipher suites - lifetime: New lifetime - description: New description - enabled: Enable/disable policy

Returns:

Updated IPSecPolicy object.

Return type:

IPSecPolicy

delete(key)

Delete a Phase 2 policy.

Parameters:

key (int) – Policy $key (ID).

Return type:

None

WireGuard VPN

WireGuard VPN resource managers.

class pyvergeos.resources.wireguard.WireGuardInterface

Bases: ResourceObject

WireGuard VPN interface object.

property peers: WireGuardPeerManager

Access peers for this WireGuard interface.

Returns:

WireGuardPeerManager for this interface.

Examples

List all peers:

peers = interface.peers.list()

Create a peer:

peer = interface.peers.create(
    name="remote-office",
    peer_ip="10.100.0.2",
    public_key="abc123...",
    allowed_ips="192.168.1.0/24"
)

property is_enabled: bool

Check if interface is enabled.

property ip_address: str

Get the tunnel IP address with CIDR notation.

property ip_only: str

Get the IP address without the CIDR mask.

property subnet_mask: str

Get the CIDR subnet mask.

property listen_port: int

Get the UDP listen port.

property mtu: int

Get the MTU (0 = auto).

property mtu_display: str

Get human-readable MTU.

property public_key: str

Get the interface public key.

property endpoint_ip: str

Get the endpoint IP for peer configurations.

property modified_at: datetime | None

Get last modified timestamp.

property peer_status: WireGuardPeerStatusManager

Access real-time peer status for this WireGuard interface.

Provides connection status including last handshake time and transfer statistics for all peers.

Returns:

WireGuardPeerStatusManager for this interface.

Examples

List peer status:

for status in wg.peer_status.list():
    if status.is_connected:
        print(f"Peer {status.peer_key} connected")
        print(f"  TX: {status.tx_bytes_formatted}")
        print(f"  RX: {status.rx_bytes_formatted}")
    else:
        print(f"Peer {status.peer_key} disconnected")

Get status for specific peer:

status = wg.peer_status.get_for_peer(peer.key)
print(f"Last handshake: {status.last_handshake}")

class pyvergeos.resources.wireguard.WireGuardPeer

Bases: ResourceObject

WireGuard VPN peer object.

property is_enabled: bool

Check if peer is enabled.

property endpoint: str

Get the peer endpoint (IP or hostname).

property port: int

Get the peer port.

property peer_ip: str

Get the peer tunnel IP address.

property public_key: str

Get the peer public key.

property has_preshared_key: bool

Check if a preshared key is configured.

property allowed_ips: str

Get the allowed IPs for this peer.

property keepalive: int

Get the keepalive interval in seconds (0 = disabled).

property firewall_config: str

Get the raw firewall configuration mode.

property firewall_config_display: str

Get human-readable firewall configuration mode.

property modified_at: datetime | None

Get last modified timestamp.

get_config()

Get the WireGuard configuration for this peer.

Returns the WireGuard config file content that can be used by the remote peer to connect to this tunnel.

Returns:

WireGuard configuration file content as string.

Raises:

ValueError – If configuration cannot be retrieved.

Return type:

str

Examples

Get and save peer config:

config = peer.get_config()
with open("wg0.conf", "w") as f:
    f.write(config)

class pyvergeos.resources.wireguard.WireGuardManager

Bases: ResourceManager[WireGuardInterface]

Manager for WireGuard VPN interfaces.

WireGuard interfaces define the local VPN tunnel endpoint including IP address, listen port, and cryptographic keys.

This is a sub-resource manager that operates on a specific network.

Examples

List interfaces on a network:

interfaces = network.wireguard.list()

Get an interface by name:

wg = network.wireguard.get(name="wg0")

Create an interface:

wg = network.wireguard.create(
    name="wg0",
    ip_address="10.100.0.1/24",
    listen_port=51820
)

Access peers:

peers = wg.peers.list()

__init__(client, network)

Parameters:

• client (VergeClient)

• network (Network)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List WireGuard interfaces on this network.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Shorthand filter arguments (e.g., name=”wg0”).

Returns:

List of WireGuardInterface objects.

Return type:

list[WireGuardInterface]

get(key=None, *, name=None, fields=None)

Get a single WireGuard interface by key or name.

Parameters:

• key (int | None) – Interface $key (ID).

• name (str | None) – Interface name.

• fields (list[str] | None) – List of fields to return.

Returns:

WireGuardInterface object.

Raises:

• NotFoundError – If interface not found.

• ValueError – If neither key nor name provided.

Return type:

WireGuardInterface

create(name, ip_address, *, listen_port=51820, mtu=0, endpoint_ip=None, description='', enabled=True)

Create a new WireGuard interface.

Parameters:

• name (str) – Unique name for the interface.

• ip_address (str) – Tunnel IP address in CIDR notation (e.g., “10.100.0.1/24”).

• listen_port (int) – UDP port to listen on (default: 51820).

• mtu (int) – MTU for the interface (0 = auto, default).

• endpoint_ip (str | None) – Public IP for peer configurations (auto-detected if not set).

• description (str) – Interface description.

• enabled (bool) – Whether the interface is enabled.

Returns:

Created WireGuardInterface object.

Return type:

WireGuardInterface

Examples

Basic interface:

wg = network.wireguard.create(
    name="wg0",
    ip_address="10.100.0.1/24"
)

Interface with custom port:

wg = network.wireguard.create(
    name="wg-remote",
    ip_address="10.100.0.1/24",
    listen_port=51821,
    endpoint_ip="203.0.113.50"
)

update(key, **kwargs)

Update an existing WireGuard interface.

Parameters:

• key (int) – Interface $key (ID).

• **kwargs (Any) – Attributes to update. Supports: - name: New name - ip_address: New tunnel IP in CIDR notation - listen_port: New listen port - mtu: New MTU (0 = auto) - endpoint_ip: New endpoint IP - description: New description - enabled: Enable/disable interface

Returns:

Updated WireGuardInterface object.

Return type:

WireGuardInterface

delete(key)

Delete a WireGuard interface.

This also removes all associated peers.

Parameters:

key (int) – Interface $key (ID).

Return type:

None

class pyvergeos.resources.wireguard.WireGuardPeerManager

Bases: ResourceManager[WireGuardPeer]

Manager for WireGuard VPN peers.

Peers define remote endpoints that can connect to the WireGuard tunnel.

This is a sub-resource manager that operates on a specific WireGuard interface.

Examples

List peers for an interface:

peers = interface.peers.list()

Create a site-to-site peer:

peer = interface.peers.create(
    name="remote-office",
    peer_ip="10.100.0.2",
    public_key="abc123...",
    allowed_ips="192.168.1.0/24"
)

Create a remote user peer:

peer = interface.peers.create(
    name="laptop",
    peer_ip="10.100.0.10",
    public_key="xyz789...",
    allowed_ips="10.100.0.10/32",
    firewall_config="remote_user",
    keepalive=25
)

Get peer configuration:

config = peer.get_config()

__init__(client, interface)

Parameters:

• client (VergeClient)

• interface (WireGuardInterface)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List peers for this WireGuard interface.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Shorthand filter arguments (e.g., name=”laptop”).

Returns:

List of WireGuardPeer objects.

Return type:

list[WireGuardPeer]

get(key=None, *, name=None, fields=None)

Get a single peer by key or name.

Parameters:

• key (int | None) – Peer $key (ID).

• name (str | None) – Peer name.

• fields (list[str] | None) – List of fields to return.

Returns:

WireGuardPeer object.

Raises:

• NotFoundError – If peer not found.

• ValueError – If neither key nor name provided.

Return type:

WireGuardPeer

create(name, peer_ip, public_key, allowed_ips, *, endpoint=None, port=51820, preshared_key=None, keepalive=0, firewall_config='site_to_site', description='', enabled=True)

Create a new WireGuard peer.

Parameters:

• name (str) – Unique name for the peer.

• peer_ip (str) – Tunnel IP address for the peer (e.g., “10.100.0.2”).

• public_key (str) – Public key of the remote peer (base64 encoded).

• allowed_ips (str) – Comma-separated allowed IP ranges (e.g., “192.168.1.0/24”).

• endpoint (str | None) – Remote peer IP/hostname (empty for roaming clients).

• port (int) – Remote peer port (default: 51820).

• preshared_key (str | None) – Optional preshared key for post-quantum resistance.

• keepalive (int) – Keepalive interval in seconds (0 = disabled).

• firewall_config (Literal['site_to_site', 'remote_user', 'none']) – Firewall rule configuration: - “site_to_site”: Create routes and accept rules for allowed IPs - “remote_user”: Same as site-to-site plus SNAT for outbound traffic - “none”: Don’t create any firewall rules

• description (str) – Peer description.

• enabled (bool) – Whether the peer is enabled.

Returns:

Created WireGuardPeer object.

Return type:

WireGuardPeer

Examples

Site-to-site peer:

peer = interface.peers.create(
    name="remote-office",
    peer_ip="10.100.0.2",
    public_key="abc123...",
    allowed_ips="192.168.1.0/24",
    endpoint="vpn.remote-office.com"
)

Remote user (roaming client):

peer = interface.peers.create(
    name="laptop",
    peer_ip="10.100.0.10",
    public_key="xyz789...",
    allowed_ips="10.100.0.10/32",
    firewall_config="remote_user",
    keepalive=25
)

update(key, **kwargs)

Update an existing WireGuard peer.

Parameters:

• key (int) – Peer $key (ID).

• **kwargs (Any) – Attributes to update. Supports: - name: New name - peer_ip: New peer tunnel IP - public_key: New public key - allowed_ips: New allowed IPs - endpoint: New endpoint - port: New port - preshared_key: New preshared key - keepalive: New keepalive interval - firewall_config: New firewall configuration - description: New description - enabled: Enable/disable peer

Returns:

Updated WireGuardPeer object.

Return type:

WireGuardPeer

delete(key)

Delete a WireGuard peer.

Parameters:

key (int) – Peer $key (ID).

Return type:

None

get_config(key)

Get the WireGuard configuration for a peer.

Retrieves the WireGuard config file content that can be used by the remote peer to connect to this tunnel.

Parameters:

key (int) – Peer $key (ID).

Returns:

WireGuard configuration file content as string.

Raises:

• NotFoundError – If peer not found.

• ValueError – If configuration cannot be retrieved.

Return type:

str

Examples

Get and save peer config:

config = interface.peers.get_config(peer.key)
with open("wg0.conf", "w") as f:
    f.write(config)

Note

Configuration is only available for peers that were created with the autogenerate_peer option enabled in the VergeOS UI.

Tenant Proxy

Reverse proxy for multi-tenant FQDN-based access.

Network proxy resource managers for multi-tenant FQDN-based access.

class pyvergeos.resources.vnet_proxy.VnetProxyTenant

Bases: ResourceObject

Tenant FQDN mapping for proxy service.

Maps a tenant to an FQDN for access through the network’s proxy service. Multiple tenants can share a single IP address by using different FQDNs.

property tenant_key: int

Get the tenant key.

property tenant_name: str

Get the tenant display name.

property fqdn: str

Get the FQDN for this tenant mapping.

property proxy_key: int

Get the parent proxy configuration key.

refresh()

Refresh this tenant mapping from the API.

Returns:

Updated VnetProxyTenant instance.

Return type:

VnetProxyTenant

save(**kwargs)

Save changes to this tenant mapping.

Parameters:

**kwargs (Any) – Fields to update.

Returns:

Updated VnetProxyTenant instance.

Return type:

VnetProxyTenant

delete()

Delete this tenant mapping.

Return type:

None

class pyvergeos.resources.vnet_proxy.VnetProxyTenantManager

Bases: ResourceManager[VnetProxyTenant]

Manager for proxy tenant FQDN mappings.

Scoped to a specific proxy configuration. Access via VnetProxy.tenants.

Examples

List all tenant mappings:

tenants = proxy.tenants.list()

Get a specific mapping:

mapping = proxy.tenants.get(key=1)
mapping = proxy.tenants.get(fqdn="tenant1.example.com")

Create a new mapping:

mapping = proxy.tenants.create(
    tenant=tenant_key,
    fqdn="tenant1.example.com"
)

Delete a mapping:

proxy.tenants.delete(key=1)

__init__(client, proxy)

Initialize the proxy tenant manager.

Parameters:

• client (VergeClient) – VergeClient instance.

• proxy (VnetProxy) – Parent VnetProxy object.

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List proxy tenant mappings.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of VnetProxyTenant objects.

Return type:

list[VnetProxyTenant]

get(key=None, *, fqdn=None, tenant=None, fields=None)

Get a proxy tenant mapping by key, FQDN, or tenant.

Parameters:

• key (int | None) – Mapping $key (ID).

• fqdn (str | None) – FQDN to look up.

• tenant (int | None) – Tenant key to look up.

• fields (list[str] | None) – List of fields to return.

Returns:

VnetProxyTenant object.

Raises:

• NotFoundError – If mapping not found.

• ValueError – If no lookup parameter provided.

Return type:

VnetProxyTenant

create(tenant, fqdn, **kwargs)

Create a new proxy tenant mapping.

Maps a tenant to an FQDN for access through this proxy service.

Parameters:

• tenant (int) – Tenant $key (ID) to map.

• fqdn (str) – Fully qualified domain name for the tenant.

• **kwargs (Any) – Additional fields.

Returns:

Created VnetProxyTenant object.

Return type:

VnetProxyTenant

Examples

Create a tenant mapping:

mapping = proxy.tenants.create(
    tenant=5,
    fqdn="tenant1.example.com"
)

update(key, **kwargs)

Update a proxy tenant mapping.

Parameters:

• key (int) – Mapping $key (ID).

• **kwargs (Any) – Fields to update (fqdn, tenant).

Returns:

Updated VnetProxyTenant object.

Return type:

VnetProxyTenant

delete(key)

Delete a proxy tenant mapping.

Parameters:

key (int) – Mapping $key (ID) to delete.

Return type:

None

class pyvergeos.resources.vnet_proxy.VnetProxy

Bases: ResourceObject

Network proxy configuration.

Enables multi-tenant access through a single IP address using FQDN mapping. Each tenant is assigned a unique FQDN that routes to their UI through the proxy service.

property network_key: int

Get the parent network key.

property network_name: str

Get the parent network display name.

property listen_address: str

Get the proxy listen address.

Returns:

Listen address (default “0.0.0.0” for all addresses).

property default_self: bool

Check if proxy defaults to self when no tenant matches.

When True, requests with no matching FQDN will show this system’s UI.

property tenants: VnetProxyTenantManager

Access tenant FQDN mappings for this proxy.

Returns:

VnetProxyTenantManager for this proxy.

Examples

List all tenant mappings:

for mapping in proxy.tenants.list():
    print(f"{mapping.fqdn} -> Tenant {mapping.tenant_name}")

Create a new mapping:

mapping = proxy.tenants.create(
    tenant=tenant_key,
    fqdn="newtenant.example.com"
)

refresh()

Refresh this proxy configuration from the API.

Returns:

Updated VnetProxy instance.

Return type:

VnetProxy

save(listen_address=None, default_self=None, **kwargs)

Save changes to this proxy configuration.

Parameters:

• listen_address (str | None) – New listen address.

• default_self (bool | None) – Whether to default to self UI when no match.

• **kwargs (Any) – Additional fields.

Returns:

Updated VnetProxy instance.

Return type:

VnetProxy

delete()

Delete this proxy configuration.

Note

This will also delete all associated tenant mappings.

Return type:

None

class pyvergeos.resources.vnet_proxy.VnetProxyManager

Bases: ResourceManager[VnetProxy]

Manager for network proxy configuration.

Scoped to a specific network. Access via Network.proxy.

The proxy service allows multiple tenants to share a single external IP address by using FQDN-based routing. Each tenant is assigned a unique hostname that routes to their UI through the proxy.

Examples

Get proxy configuration for a network:

proxy = network.proxy.get()
print(f"Listen address: {proxy.listen_address}")

Create/enable proxy on a network:

proxy = network.proxy.create(
    listen_address="0.0.0.0",
    default_self=True
)

List tenant mappings:

for mapping in proxy.tenants.list():
    print(f"{mapping.fqdn} -> {mapping.tenant_name}")

Add a tenant mapping:

mapping = proxy.tenants.create(
    tenant=tenant_key,
    fqdn="tenant1.example.com"
)

Note

Only one proxy configuration can exist per network. The proxy service is typically used on external networks.

__init__(client, network)

Initialize the proxy manager.

Parameters:

• client (VergeClient) – VergeClient instance.

• network (Network) – Parent Network object.

Return type:

None

exists()

Check if proxy is configured for this network.

Returns:

True if proxy configuration exists.

Return type:

bool

get(key=None, *, fields=None)

Get the proxy configuration for this network.

Parameters:

• key (int | None) – Optional proxy $key (ID). If not provided, gets the proxy for this network (there’s only one per network).

• fields (list[str] | None) – List of fields to return.

Returns:

VnetProxy object.

Raises:

NotFoundError – If proxy not configured for this network.

Return type:

VnetProxy

create(listen_address='0.0.0.0', default_self=True, **kwargs)

Create/enable proxy configuration for this network.

Parameters:

• listen_address (str) – Address to listen on (default “0.0.0.0” for all).

• default_self (bool) – Default to this system’s UI when no FQDN matches.

• **kwargs (Any) – Additional fields.

Returns:

Created VnetProxy object.

Return type:

VnetProxy

Note

Only one proxy configuration can exist per network. Creating a proxy when one already exists will raise an error.

Examples

Enable proxy with defaults:

proxy = network.proxy.create()

Enable proxy with custom listen address:

proxy = network.proxy.create(listen_address="192.168.1.1")

update(key, **kwargs)

Update proxy configuration.

Parameters:

• key (int) – Proxy $key (ID).

• **kwargs (Any) – Fields to update (listen_address, default_self).

Returns:

Updated VnetProxy object.

Return type:

VnetProxy

delete(key=None)

Delete proxy configuration for this network.

Parameters:

key (int | None) – Proxy $key (ID). If not provided, deletes the proxy for this network.

Return type:

None

Note

This will also delete all associated tenant mappings.

get_or_create(listen_address='0.0.0.0', default_self=True, **kwargs)

Get existing proxy or create new one.

Convenience method that returns existing proxy configuration or creates a new one with the provided settings.

Parameters:

• listen_address (str) – Listen address for new proxy.

• default_self (bool) – Default self setting for new proxy.

• **kwargs (Any) – Additional fields for new proxy.

Returns:

VnetProxy object (existing or newly created).

Return type:

VnetProxy

Examples

Ensure proxy is configured:

proxy = network.proxy.get_or_create()

Tenants

Tenant Management

Tenant resource manager.

class pyvergeos.resources.tenant_manager.Tenant

Bases: ResourceObject

Tenant resource object.

power_on(preferred_node=None)

Power on the tenant.

Parameters:

preferred_node (int | None) – Node $key to start tenant on.

Returns:

Self for chaining.

Raises:

ValueError – If tenant is a snapshot.

Return type:

Tenant

power_off()

Power off the tenant gracefully.

Returns:

Self for chaining.

Raises:

ValueError – If tenant is a snapshot.

Return type:

Tenant

reset()

Reset the tenant (hard reboot).

Returns:

Self for chaining.

Raises:

ValueError – If tenant is a snapshot.

Return type:

Tenant

restart()

Restart the tenant (alias for reset).

Returns:

Self for chaining.

Return type:

Tenant

clone(name=None, no_network=False, no_storage=False, no_nodes=False)

Clone this tenant.

Parameters:

• name (str | None) – Name for the clone. If not provided, a default name is generated.

• no_network (bool) – Do not clone the network configuration.

• no_storage (bool) – Do not clone the storage configuration.

• no_nodes (bool) – Do not clone the nodes (VMs).

Returns:

Clone task information.

Raises:

ValueError – If tenant is a snapshot.

Return type:

dict[str, Any] | None

refresh()

Refresh tenant data from API.

Returns:

Updated Tenant object.

Return type:

Tenant

save(**kwargs)

Save changes to tenant.

Parameters:

**kwargs (Any) – Fields to update.

Returns:

Updated Tenant object.

Return type:

Tenant

property is_running: bool

Check if tenant is powered on.

property is_starting: bool

Check if tenant is starting.

property is_stopping: bool

Check if tenant is stopping.

property is_migrating: bool

Check if tenant is migrating.

property is_snapshot: bool

Check if this is a snapshot (not a real tenant).

property is_isolated: bool

Check if tenant network isolation is enabled.

property status: str

Get tenant status (online, offline, starting, etc.).

property state: str

Get tenant state (online, offline, warning, error).

property network_name: str | None

Get the name of the tenant’s network.

property ui_address_ip: str | None

Get the UI access IP address.

property snapshots: TenantSnapshotManager

Get the snapshot manager for this tenant.

Returns:

TenantSnapshotManager for managing tenant snapshots.

Example

>>> tenant = client.tenants.get(name="my-tenant")
>>> snapshots = tenant.snapshots.list()
>>> tenant.snapshots.create("pre-upgrade")

property storage: TenantStorageManager

Get the storage manager for this tenant.

Returns:

TenantStorageManager for managing tenant storage allocations.

Example

>>> tenant = client.tenants.get(name="my-tenant")
>>> # List storage allocations
>>> for alloc in tenant.storage.list():
...     print(f"{alloc.tier_name}: {alloc.provisioned_gb} GB")
>>> # Add storage from Tier 1
>>> tenant.storage.create(tier=1, provisioned_gb=100)

property nodes: TenantNodeManager

Get the node manager for this tenant.

Returns:

TenantNodeManager for managing tenant compute nodes.

Example

>>> tenant = client.tenants.get(name="my-tenant")
>>> # List nodes
>>> for node in tenant.nodes.list():
...     print(f"{node.name}: {node.cpu_cores} cores, {node.ram_gb} GB")
>>> # Add a node with 4 cores and 16 GB RAM
>>> tenant.nodes.create(cpu_cores=4, ram_gb=16, cluster=1)

property network_blocks: TenantNetworkBlockManager

Get the network block manager for this tenant.

Returns:

TenantNetworkBlockManager for managing tenant network blocks.

Example

>>> tenant = client.tenants.get(name="my-tenant")
>>> # List network blocks
>>> for block in tenant.network_blocks.list():
...     print(f"{block.cidr} on {block.network_name}")
>>> # Assign a network block
>>> tenant.network_blocks.create(network=1, cidr="192.168.100.0/24")

property external_ips: TenantExternalIPManager

Get the external IP manager for this tenant.

Returns:

TenantExternalIPManager for managing tenant external IPs.

Example

>>> tenant = client.tenants.get(name="my-tenant")
>>> # List external IPs
>>> for ip in tenant.external_ips.list():
...     print(f"{ip.ip_address} on {ip.network_name}")
>>> # Assign an external IP
>>> tenant.external_ips.create(network=1, ip="192.168.1.100")

property l2_networks: TenantLayer2Manager

Get the Layer 2 network manager for this tenant.

Returns:

TenantLayer2Manager for managing tenant Layer 2 networks.

Example

>>> tenant = client.tenants.get(name="my-tenant")
>>> # List Layer 2 networks
>>> for l2 in tenant.l2_networks.list():
...     print(f"{l2.network_name}: {l2.is_enabled}")
>>> # Assign a Layer 2 network
>>> tenant.l2_networks.create(network_name="VLAN100")

property shared_objects: list[Any]

Get shared objects for this tenant.

Returns a list of shared objects (VMs) shared with this tenant.

Returns:

List of SharedObject objects.

Example

>>> tenant = client.tenants.get(name="my-tenant")
>>> for obj in tenant.shared_objects:
...     print(f"{obj.name}: {obj.object_type}")

property stats: TenantStatsManager

Get the stats manager for this tenant.

Returns:

TenantStatsManager for accessing tenant metrics and history.

Example

>>> tenant = client.tenants.get(name="my-tenant")
>>> # Get current stats
>>> stats = tenant.stats.get()
>>> print(f"RAM: {stats.ram_used_mb}MB")
>>> # Get stats history for billing/capacity planning
>>> history = tenant.stats.history_short(limit=100)
>>> for point in history:
...     print(f"{point.timestamp}: CPU {point.total_cpu}%")

property logs: TenantLogManager

Get the log manager for this tenant.

Returns:

TenantLogManager for accessing tenant-specific logs.

Example

>>> tenant = client.tenants.get(name="my-tenant")
>>> # Get recent logs
>>> logs = tenant.logs.list(limit=20)
>>> # Get errors only
>>> errors = tenant.logs.list(errors_only=True)
>>> for log in errors:
...     print(f"[{log.level}] {log.text}")

set_ui_ip(ip, network_name='External')

Set the UI IP address for this tenant.

Creates a virtual IP address on the specified network that allows external access to the tenant’s UI. This is the proper way to assign a tenant UI address.

Parameters:

• ip (str) – IP address for tenant UI access.

• network_name (str) – Network to create the IP on (default: “External”).

Returns:

Created vnet_address response.

Raises:

• ValueError – If tenant is a snapshot.

• NotFoundError – If the network is not found.

Return type:

dict[str, Any] | None

Example

>>> tenant = client.tenants.get(name="my-tenant")
>>> tenant.set_ui_ip("192.168.10.79")

send_file(file_key)

Send a file to this tenant.

Shares a file from the parent vSAN with the tenant. This allows tenants to access specific files (ISOs, disk images, etc.) within their own Files section. The process is near-instant as it uses a branch command rather than copying the file.

Parameters:

file_key (int) – The $key of the file to share with the tenant.

Returns:

Action response, or None if no response body.

Raises:

ValueError – If tenant is a snapshot.

Return type:

dict[str, Any] | None

Example

>>> tenant = client.tenants.get(name="my-tenant")
>>> # Get the file to share
>>> file = client.files.get(name="ubuntu-22.04.iso")
>>> tenant.send_file(file.key)

create_crash_cart(name=None)

Deploy a Crash Cart VM for emergency access to this tenant.

Deploys a Crash Cart VM that provides emergency UI access to a tenant. This is useful when normal tenant access is unavailable. The Crash Cart VM connects to the tenant’s internal network and provides a web-based console for troubleshooting.

Parameters:

name (str | None) – The name for the Crash Cart VM. Defaults to “Crash Cart - {tenant_name}”.

Returns:

Recipe deployment response, or None if no response body.

Raises:

• ValueError – If tenant is a snapshot.

• NotFoundError – If the Crash Cart recipe is not available.

Return type:

dict[str, Any] | None

Example

>>> tenant = client.tenants.get(name="my-tenant")
>>> tenant.create_crash_cart()
>>> # Access the crash cart VM console
>>> vm = client.vms.get(name="Crash Cart - my-tenant")

delete_crash_cart(name=None)

Remove a Crash Cart VM deployed for this tenant.

Removes the Crash Cart VM that was deployed for emergency tenant access. The VM must be stopped before removal. This should be called after troubleshooting is complete.

Parameters:

name (str | None) – The name of the Crash Cart VM to remove. Defaults to “Crash Cart - {tenant_name}”.

Raises:

• ValueError – If tenant is a snapshot.

• NotFoundError – If the Crash Cart VM is not found.

• APIError – If the VM is still running or cannot be deleted.

Return type:

None

Example

>>> tenant = client.tenants.get(name="my-tenant")
>>> # Stop the crash cart first
>>> vm = client.vms.get(name="Crash Cart - my-tenant")
>>> vm.power_off()
>>> # Wait for it to stop, then delete
>>> tenant.delete_crash_cart()

enable_isolation()

Enable network isolation mode for this tenant.

Enables isolation mode which disables the tenant’s network connectivity. This is useful for security purposes or when performing maintenance that requires network isolation.

Returns:

Self for chaining.

Raises:

ValueError – If tenant is a snapshot or already isolated.

Return type:

Tenant

Example

>>> tenant = client.tenants.get(name="my-tenant")
>>> tenant.enable_isolation()
>>> # Tenant network is now disabled

disable_isolation()

Disable network isolation mode for this tenant.

Disables isolation mode which restores the tenant’s network connectivity. Use this after troubleshooting or security investigation is complete.

Returns:

Self for chaining.

Raises:

ValueError – If tenant is a snapshot or not isolated.

Return type:

Tenant

Example

>>> tenant = client.tenants.get(name="my-tenant")
>>> tenant.disable_isolation()
>>> # Tenant network is now enabled

connect(username, password, verify_ssl=None, timeout=30)

Connect to the tenant’s VergeOS context.

Creates a new VergeClient connected to the tenant’s environment, allowing you to execute commands within the tenant’s context. The tenant must be running to connect.

Parameters:

• username (str) – Username for authenticating to the tenant.

• password (str) – Password for authenticating to the tenant.

• verify_ssl (bool | None) – Whether to verify SSL certificates. If None, inherits from the parent client.

• timeout (int) – Connection timeout in seconds.

Returns:

A new VergeClient connected to the tenant.

Raises:

• ValueError – If tenant is a snapshot or not running.

• ValueError – If tenant has no UI address configured.

• VergeConnectionError – If connection to tenant fails.

• AuthenticationError – If tenant credentials are invalid.

Return type:

VergeClient

Example

>>> tenant = client.tenants.get(name="my-tenant")
>>> tenant.power_on()
>>> # Wait for tenant to start...
>>> tenant_client = tenant.connect(
...     username="admin",
...     password="tenant-password"
... )
>>> # Now use tenant_client to manage resources within the tenant
>>> tenant_vms = tenant_client.vms.list()
>>> tenant_client.disconnect()

class pyvergeos.resources.tenant_manager.TenantManager

Bases: ResourceManager[Tenant]

Manager for Tenant operations.

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, include_snapshots=False, **filter_kwargs)

List tenants with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (defaults to rich field set).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• include_snapshots (bool) – Include tenant snapshots (default False).

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of Tenant objects.

Return type:

list[Tenant]

get(key=None, *, name=None, fields=None)

Get a single tenant by key or name.

Parameters:

• key (int | None) – Tenant $key (ID).

• name (str | None) – Tenant name (will search if key not provided).

• fields (list[str] | None) – List of fields to return (defaults to rich field set).

Returns:

Tenant object.

Raises:

• NotFoundError – If tenant not found.

• ValueError – If neither key nor name provided.

Return type:

Tenant

list_running()

List all running tenants.

Return type:

list[Tenant]

list_stopped()

List all stopped tenants.

Return type:

list[Tenant]

list_by_status(status)

List tenants by status.

Parameters:

status (str) – Status to filter by (online, offline, starting, stopping, migrating, error, reduced, provisioning, restarting).

Returns:

List of Tenant objects matching the status.

Return type:

list[Tenant]

create(name, password=None, description='', url=None, note=None, expose_cloud_snapshots=True, allow_branding=False, require_password_change=False, **kwargs)

Create a new tenant.

The tenant is created in a stopped state by default.

Parameters:

• name (str) – Tenant name (required, 1-120 characters).

• password (str | None) – Password for the auto-created admin user. If not specified, a random password is generated.

• description (str) – Tenant description.

• url (str | None) – URL associated with the tenant.

• note (str | None) – Note for the tenant.

• expose_cloud_snapshots (bool) – Allow tenant to request cloud snapshots (default True).

• allow_branding (bool) – Allow tenant to customize branding (default False).

• require_password_change (bool) – Require password change on first login (default False).

• **kwargs (Any) – Additional tenant properties.

Returns:

Created Tenant object.

Return type:

Tenant

update(key, **kwargs)

Update an existing tenant.

Parameters:

• key (int) – Tenant $key (ID).

• **kwargs (Any) – Attributes to update. Supported fields include: - name: New name for the tenant - description: Tenant description - url: URL associated with the tenant - note: Note for the tenant - expose_cloud_snapshots: Allow cloud snapshots - allow_branding: Allow branding customization

Returns:

Updated Tenant object.

Return type:

Tenant

power_on(key, preferred_node=None)

Power on a tenant.

Parameters:

• key (int) – Tenant $key (ID).

• preferred_node (int | None) – Node $key to start tenant on.

Returns:

Action response (may include task information).

Return type:

dict[str, Any] | None

power_off(key)

Power off a tenant gracefully.

Parameters:

key (int) – Tenant $key (ID).

Returns:

Action response (may include task information).

Return type:

dict[str, Any] | None

reset(key)

Reset a tenant (hard reboot).

Parameters:

key (int) – Tenant $key (ID).

Returns:

Action response (may include task information).

Return type:

dict[str, Any] | None

restart(key)

Restart a tenant (alias for reset).

Parameters:

key (int) – Tenant $key (ID).

Returns:

Action response (may include task information).

Return type:

dict[str, Any] | None

clone(key, name=None, no_network=False, no_storage=False, no_nodes=False)

Clone a tenant.

Parameters:

• key (int) – Tenant $key (ID) of the source tenant.

• name (str | None) – Name for the clone. If not provided, a default name is generated.

• no_network (bool) – Do not clone the network configuration.

• no_storage (bool) – Do not clone the storage configuration.

• no_nodes (bool) – Do not clone the nodes (VMs).

Returns:

Clone task information.

Return type:

dict[str, Any] | None

snapshots(tenant_key)

Get the snapshot manager for a specific tenant.

Parameters:

tenant_key (int) – Tenant $key (ID).

Returns:

TenantSnapshotManager for managing tenant snapshots.

Return type:

TenantSnapshotManager

Example

>>> # Access snapshot manager directly by tenant key
>>> snapshot_manager = client.tenants.snapshots(123)
>>> snapshots = snapshot_manager.list()

storage(tenant_key)

Get the storage manager for a specific tenant.

Parameters:

tenant_key (int) – Tenant $key (ID).

Returns:

TenantStorageManager for managing tenant storage allocations.

Return type:

TenantStorageManager

Example

>>> # Access storage manager directly by tenant key
>>> storage_manager = client.tenants.storage(123)
>>> allocations = storage_manager.list()

nodes(tenant_key)

Get the node manager for a specific tenant.

Parameters:

tenant_key (int) – Tenant $key (ID).

Returns:

TenantNodeManager for managing tenant compute nodes.

Return type:

TenantNodeManager

Example

>>> # Access node manager directly by tenant key
>>> node_manager = client.tenants.nodes(123)
>>> nodes = node_manager.list()

network_blocks(tenant_key)

Get the network block manager for a specific tenant.

Parameters:

tenant_key (int) – Tenant $key (ID).

Returns:

TenantNetworkBlockManager for managing tenant network blocks.

Return type:

TenantNetworkBlockManager

Example

>>> # Access network block manager directly by tenant key
>>> block_manager = client.tenants.network_blocks(123)
>>> blocks = block_manager.list()

external_ips(tenant_key)

Get the external IP manager for a specific tenant.

Parameters:

tenant_key (int) – Tenant $key (ID).

Returns:

TenantExternalIPManager for managing tenant external IPs.

Return type:

TenantExternalIPManager

Example

>>> # Access external IP manager directly by tenant key
>>> ip_manager = client.tenants.external_ips(123)
>>> ips = ip_manager.list()

l2_networks(tenant_key)

Get the Layer 2 network manager for a specific tenant.

Parameters:

tenant_key (int) – Tenant $key (ID).

Returns:

TenantLayer2Manager for managing tenant Layer 2 networks.

Return type:

TenantLayer2Manager

Example

>>> # Access Layer 2 network manager directly by tenant key
>>> l2_manager = client.tenants.l2_networks(123)
>>> l2_networks = l2_manager.list()

connect_context(key=None, *, name=None, username, password, verify_ssl=None, timeout=30)

Connect to a tenant’s VergeOS context.

Creates a new VergeClient connected to the tenant’s environment, allowing you to execute commands within the tenant’s context. The tenant must be running to connect.

Parameters:

• key (int | None) – Tenant $key (ID).

• name (str | None) – Tenant name (alternative to key).

• username (str) – Username for authenticating to the tenant.

• password (str) – Password for authenticating to the tenant.

• verify_ssl (bool | None) – Whether to verify SSL certificates. If None, inherits from the parent client.

• timeout (int) – Connection timeout in seconds.

Returns:

A new VergeClient connected to the tenant.

Raises:

• NotFoundError – If tenant not found.

• ValueError – If tenant is a snapshot or not running.

• ValueError – If tenant has no UI address configured.

• VergeConnectionError – If connection to tenant fails.

• AuthenticationError – If tenant credentials are invalid.

Return type:

VergeClient

Example

>>> # Connect to tenant by name
>>> tenant_client = client.tenants.connect_context(
...     name="my-tenant",
...     username="admin",
...     password="tenant-password"
... )
>>> # Now use tenant_client to manage resources within the tenant
>>> tenant_vms = tenant_client.vms.list()
>>> tenant_client.disconnect()

>>> # Or connect by key
>>> tenant_client = client.tenants.connect_context(
...     key=123,
...     username="admin",
...     password="tenant-password"
... )

shared_objects(tenant_key)

Get shared objects for a specific tenant.

Parameters:

tenant_key (int) – Tenant $key (ID).

Returns:

List of SharedObject objects shared with the tenant.

Return type:

list[Any]

Example

>>> shared = client.tenants.shared_objects(123)
>>> for obj in shared:
...     print(f"{obj.name}: {obj.object_type}")

send_file(key, file_key)

Send a file to a tenant.

Shares a file from the parent vSAN with the tenant. This allows tenants to access specific files (ISOs, disk images, etc.) within their own Files section. The process is near-instant as it uses a branch command rather than copying the file.

Parameters:

• key (int) – Tenant $key (ID).

• file_key (int) – The $key of the file to share with the tenant.

Returns:

Action response, or None if no response body.

Return type:

dict[str, Any] | None

Example

>>> file = client.files.get(name="ubuntu-22.04.iso")
>>> client.tenants.send_file(123, file.key)

create_crash_cart(key, name=None)

Deploy a Crash Cart VM for emergency access to a tenant.

Deploys a Crash Cart VM that provides emergency UI access to a tenant. This is useful when normal tenant access is unavailable. The Crash Cart VM connects to the tenant’s internal network and provides a web-based console for troubleshooting.

Parameters:

• key (int) – Tenant $key (ID).

• name (str | None) – The name for the Crash Cart VM. Defaults to “Crash Cart - {tenant_name}”.

Returns:

Recipe deployment response, or None if no response body.

Raises:

NotFoundError – If the Crash Cart recipe is not available.

Return type:

dict[str, Any] | None

Example

>>> client.tenants.create_crash_cart(123)
>>> # Or with a custom name
>>> client.tenants.create_crash_cart(123, name="Emergency Access VM")

delete_crash_cart(key, name=None)

Remove a Crash Cart VM deployed for a tenant.

Removes the Crash Cart VM that was deployed for emergency tenant access. The VM must be stopped before removal. This should be called after troubleshooting is complete.

Parameters:

• key (int) – Tenant $key (ID).

• name (str | None) – The name of the Crash Cart VM to remove. Defaults to “Crash Cart - {tenant_name}”.

Raises:

• NotFoundError – If the Crash Cart VM is not found.

• APIError – If the VM is still running or cannot be deleted.

Return type:

None

Example

>>> client.tenants.delete_crash_cart(123)

enable_isolation(key)

Enable network isolation mode for a tenant.

Enables isolation mode which disables the tenant’s network connectivity. This is useful for security purposes or when performing maintenance that requires network isolation.

Parameters:

key (int) – Tenant $key (ID).

Returns:

Action response, or None if no response body.

Return type:

dict[str, Any] | None

Example

>>> client.tenants.enable_isolation(123)

disable_isolation(key)

Disable network isolation mode for a tenant.

Disables isolation mode which restores the tenant’s network connectivity. Use this after troubleshooting or security investigation is complete.

Parameters:

key (int) – Tenant $key (ID).

Returns:

Action response, or None if no response body.

Return type:

dict[str, Any] | None

Example

>>> client.tenants.disable_isolation(123)

Tenant Stats & Monitoring

Resource utilization and activity logging for tenants.

Tenant Stats & Monitoring resource managers.

This module provides access to tenant performance metrics, status, logs, and dashboard information for monitoring and billing/chargeback purposes.

Example

>>> # Access tenant stats
>>> tenant = client.tenants.get(name="customer-a")
>>> stats = tenant.stats.get()
>>> print(f"RAM: {stats.ram_used_mb}MB")

>>> # Access stats history for billing/capacity planning
>>> history = tenant.stats.history_short(limit=100)
>>> for point in history:
...     print(f"{point.timestamp}: CPU {point.total_cpu}%, RAM {point.ram_used_mb}MB")

>>> # Access tenant-specific logs
>>> logs = tenant.logs.list(level="error")
>>> for log in logs:
...     print(f"[{log.level}] {log.text}")

>>> # Access dashboard summary
>>> dashboard = client.tenant_dashboard.get()
>>> print(f"Online: {dashboard.tenants_online}/{dashboard.tenants_count}")

class pyvergeos.resources.tenant_stats.TenantStats

Bases: ResourceObject

Tenant statistics resource object.

Provides current performance metrics for a tenant.

property tenant_key: int

Parent tenant key.

property ram_used_mb: int

RAM used in MB.

property last_update: datetime | None

Timestamp when stats were last updated.

class pyvergeos.resources.tenant_stats.TenantStatsHistory

Bases: ResourceObject

Tenant statistics history record.

Represents a single time point in the stats history with comprehensive resource utilization metrics for billing and capacity planning.

property tenant_key: int

Parent tenant key.

property timestamp: datetime | None

Timestamp for this history point.

property timestamp_epoch: int

Timestamp as Unix epoch.

property total_cpu: int

Total CPU usage percentage.

property core_count: int

Number of allocated CPU cores.

property ram_used_mb: int

Physical RAM used in MB.

property vram_used_mb: int

Virtual RAM used in MB.

property ram_allocated_mb: int

RAM allocated to tenant in MB.

property ram_pct: int

RAM usage percentage.

property ip_count: int

Number of IP addresses assigned.

property tier0_provisioned: int

Tier 0 storage provisioned in bytes.

property tier0_used: int

Tier 0 storage used in bytes.

property tier0_allocated: int

Tier 0 storage allocated in bytes.

property tier0_pct: int

Tier 0 storage usage percentage.

property tier1_provisioned: int

Tier 1 storage provisioned in bytes.

property tier1_used: int

Tier 1 storage used in bytes.

property tier1_allocated: int

Tier 1 storage allocated in bytes.

property tier1_pct: int

Tier 1 storage usage percentage.

property tier2_provisioned: int

Tier 2 storage provisioned in bytes.

property tier2_used: int

Tier 2 storage used in bytes.

property tier2_allocated: int

Tier 2 storage allocated in bytes.

property tier2_pct: int

Tier 2 storage usage percentage.

property tier3_provisioned: int

Tier 3 storage provisioned in bytes.

property tier3_used: int

Tier 3 storage used in bytes.

property tier3_allocated: int

Tier 3 storage allocated in bytes.

property tier3_pct: int

Tier 3 storage usage percentage.

property tier4_provisioned: int

Tier 4 storage provisioned in bytes.

property tier4_used: int

Tier 4 storage used in bytes.

property tier4_allocated: int

Tier 4 storage allocated in bytes.

property tier4_pct: int

Tier 4 storage usage percentage.

property tier5_provisioned: int

Tier 5 storage provisioned in bytes.

property tier5_used: int

Tier 5 storage used in bytes.

property tier5_allocated: int

Tier 5 storage allocated in bytes.

property tier5_pct: int

Tier 5 storage usage percentage.

property gpus_used: int

Number of physical GPUs in use.

property gpus_total: int

Total physical GPUs allocated.

property gpus_pct: int

GPU usage percentage.

property vgpus_used: int

Number of vGPUs in use.

property vgpus_total: int

Total vGPUs allocated.

property vgpus_pct: int

vGPU usage percentage.

get_tier_stats(tier)

Get stats for a specific storage tier.

Parameters:

tier (int) – Tier number (0-5).

Returns:

Dict with provisioned, used, allocated, and pct values.

Raises:

ValueError – If tier is not 0-5.

Return type:

dict[str, int]

property total_storage_used: int

Total storage used across all tiers in bytes.

property total_storage_provisioned: int

Total storage provisioned across all tiers in bytes.

property total_storage_allocated: int

Total storage allocated across all tiers in bytes.

class pyvergeos.resources.tenant_stats.TenantStatsManager

Bases: ResourceManager[TenantStats]

Manager for tenant statistics.

Provides access to current and historical performance metrics for a tenant. Scoped to a specific tenant.

Example

>>> # Get current stats
>>> stats = manager.get()
>>> print(f"RAM: {stats.ram_used_mb}MB")

>>> # Get short-term history (high resolution)
>>> history = manager.history_short(limit=100)

>>> # Get long-term history (lower resolution, longer retention)
>>> history = manager.history_long(limit=1000)

__init__(client, tenant)

Parameters:

• client (VergeClient)

• tenant (Tenant)

Return type:

None

get(fields=None)

Get current tenant statistics.

Parameters:

fields (list[str] | None) – List of fields to return.

Returns:

TenantStats object.

Raises:

NotFoundError – If stats not found for this tenant.

Return type:

TenantStats

history_short(limit=None, offset=None, since=None, until=None, fields=None)

Get short-term stats history (high resolution).

Parameters:

• limit (int | None) – Maximum number of records to return.

• offset (int | None) – Skip this many records.

• since (datetime | int | None) – Return records after this time (datetime or epoch).

• until (datetime | int | None) – Return records before this time (datetime or epoch).

• fields (list[str] | None) – List of fields to return.

Returns:

List of TenantStatsHistory objects, sorted by timestamp descending.

Return type:

list[TenantStatsHistory]

history_long(limit=None, offset=None, since=None, until=None, fields=None)

Get long-term stats history (lower resolution, longer retention).

Parameters:

• limit (int | None) – Maximum number of records to return.

• offset (int | None) – Skip this many records.

• since (datetime | int | None) – Return records after this time (datetime or epoch).

• until (datetime | int | None) – Return records before this time (datetime or epoch).

• fields (list[str] | None) – List of fields to return.

Returns:

List of TenantStatsHistory objects, sorted by timestamp descending.

Return type:

list[TenantStatsHistory]

class pyvergeos.resources.tenant_stats.TenantLog

Bases: ResourceObject

Tenant log entry resource object.

property tenant_key: int

Parent tenant key.

property tenant_name: str

Parent tenant name.

property level: str

Log level (Audit, Message, Warning, Error, Critical).

property level_raw: str

Raw log level value.

property text: str

Log message text.

property user: str

User who generated the log entry.

property timestamp: datetime | None

Timestamp of log entry (microseconds precision).

property timestamp_epoch_us: int

Timestamp as Unix epoch in microseconds.

property is_error: bool

Check if this is an error or critical log.

property is_warning: bool

Check if this is a warning log.

property is_audit: bool

Check if this is an audit log.

class pyvergeos.resources.tenant_stats.TenantLogManager

Bases: ResourceManager[TenantLog]

Manager for tenant logs.

Provides access to log entries for a tenant. Scoped to a specific tenant.

Example

>>> # Get recent logs
>>> logs = manager.list(limit=20)

>>> # Get errors only
>>> errors = manager.list(level="error")

>>> # Get logs since a specific time
>>> logs = manager.list(since=datetime.now() - timedelta(hours=1))

__init__(client, tenant)

Parameters:

• client (VergeClient)

• tenant (Tenant)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, level=None, errors_only=False, warnings_only=False, since=None, until=None, **filter_kwargs)

List tenant log entries.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• level (Literal['audit', 'message', 'warning', 'error', 'critical', 'summary', 'debug'] | None) – Filter by log level.

• errors_only (bool) – Only return error and critical logs.

• warnings_only (bool) – Only return warning logs.

• since (datetime | int | None) – Return logs after this time (datetime or epoch microseconds).

• until (datetime | int | None) – Return logs before this time (datetime or epoch microseconds).

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of TenantLog objects, sorted by timestamp descending.

Return type:

list[TenantLog]

get(key=None, *, fields=None)

Get a specific log entry by key.

Parameters:

• key (int | None) – Log entry $key (ID).

• fields (list[str] | None) – List of fields to return.

Returns:

TenantLog object.

Raises:

• NotFoundError – If log entry not found.

• ValueError – If key not provided.

Return type:

TenantLog

class pyvergeos.resources.tenant_stats.TenantDashboard

Bases: ResourceObject

Tenant dashboard with aggregated metrics.

Provides a high-level overview of tenant status and resource utilization across all tenants in the system.

property tenants_count: int

Total number of tenants.

property tenants_online: int

Number of online tenants.

property tenants_warn: int

Number of tenants in warning state.

property tenants_error: int

Number of tenants in error state.

property tenants_offline: int

Number of offline tenants.

property storage_count: int

Number of tenant storage allocations.

property snapshots_count: int

Number of tenant snapshots.

property cloud_snapshots_count: int

Number of cloud snapshots.

property nodes_count: int

Total number of tenant nodes.

property nodes_online: int

Number of online tenant nodes.

property nodes_warn: int

Number of tenant nodes in warning state.

property nodes_error: int

Number of tenant nodes in error state.

property tenant_recipes_count: int

Total number of tenant recipes.

property tenant_recipes_online: int

Number of online tenant recipes.

property tenant_recipes_warn: int

Number of tenant recipes in warning state.

property tenant_recipes_error: int

Number of tenant recipes in error state.

property devices_count: int

Total number of tenant devices.

property devices_online: int

Number of online tenant devices.

property devices_warn: int

Number of tenant devices in warning state.

property devices_error: int

Number of tenant devices in error state.

property running_tenants_cores: list[dict[str, Any]]

Top running tenants by CPU cores.

property tenant_storage: list[dict[str, Any]]

Top tenant storage by usage.

property running_nodes_cpu: list[dict[str, Any]]

Top tenant nodes by CPU usage.

property running_nodes_ram: list[dict[str, Any]]

Top tenant nodes by RAM usage.

property running_nodes_nic: list[dict[str, Any]]

Top tenant nodes by network bandwidth.

property logs: list[dict[str, Any]]

Recent tenant-related logs.

property tenant_snapshots: list[dict[str, Any]]

Tenant snapshot information.

class pyvergeos.resources.tenant_stats.TenantDashboardManager

Bases: ResourceManager[TenantDashboard]

Manager for tenant dashboard.

Provides aggregated tenant metrics and status counts.

Example

>>> dashboard = client.tenant_dashboard.get()
>>> print(f"Online: {dashboard.tenants_online}/{dashboard.tenants_count}")
>>> print(f"Errors: {dashboard.tenants_error}")

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

get()

Get tenant dashboard.

Returns:

TenantDashboard object with aggregated metrics.

Return type:

TenantDashboard

Tenant Storage

Tenant storage allocation resource manager.

class pyvergeos.resources.tenant_storage.TenantStorage

Bases: ResourceObject

Tenant Storage allocation resource object.

Represents a storage tier allocation for a tenant. Each tenant can have allocations from different storage tiers. Values are in bytes but convenience properties provide GB conversions.

property tenant_key: int

Get the tenant key this allocation belongs to.

property tier_key: int

Get the storage tier key.

property tier: int

Get the tier number (1-5).

property tier_name: str

Get the formatted tier name (e.g., ‘Tier 1’).

property tier_description: str | None

Get the tier description.

property provisioned_bytes: int

Get provisioned storage in bytes.

property provisioned_gb: float

Get provisioned storage in GB.

property used_bytes: int

Get used storage in bytes.

property used_gb: float

Get used storage in GB.

property allocated_bytes: int

Get allocated storage in bytes.

property allocated_gb: float

Get allocated storage in GB.

property used_percent: int

Get percentage of provisioned storage used.

property free_bytes: int

Get free (provisioned - used) storage in bytes.

property free_gb: float

Get free storage in GB.

property last_update: datetime | None

Get last update timestamp as datetime.

save(provisioned_gb=None, **kwargs)

Save changes to this storage allocation.

Parameters:

• provisioned_gb (int | None) – New provisioned size in GB (convenience parameter).

• **kwargs (Any) – Additional fields to update.

Returns:

Updated TenantStorage object.

Return type:

TenantStorage

delete()

Delete this storage allocation.

Return type:

None

class pyvergeos.resources.tenant_storage.TenantStorageManager

Bases: ResourceManager[TenantStorage]

Manager for Tenant Storage allocation operations.

This manager handles storage tier allocations for tenants. Each tenant can have storage allocated from one or more storage tiers.

This manager is accessed through a Tenant object’s storage property or via client.tenants.storage(tenant_key).

Example

>>> tenant = client.tenants.get(name="my-tenant")
>>> # List all storage allocations
>>> for alloc in tenant.storage.list():
...     print(f"{alloc.tier_name}: {alloc.provisioned_gb} GB")
>>> # Add storage from Tier 1
>>> tenant.storage.create(tier=1, provisioned_gb=100)
>>> # Update allocation
>>> tenant.storage.update_by_tier(1, provisioned_gb=200)

__init__(client, tenant)

Parameters:

• client (VergeClient)

• tenant (Tenant)

Return type:

None

list(filter=None, fields=None, tier=None, **kwargs)

List storage allocations for this tenant.

Parameters:

• filter (str | None) – Additional OData filter string.

• fields (list[str] | None) – List of fields to return.

• tier (int | None) – Filter by specific tier number (1-5).

• **kwargs (Any) – Additional filter arguments.

Returns:

List of TenantStorage objects.

Return type:

list[TenantStorage]

get(key=None, *, tier=None, fields=None)

Get a storage allocation by key or tier number.

Parameters:

• key (int | None) – Storage allocation $key (ID).

• tier (int | None) – Tier number (1-5) - alternative to key.

• fields (list[str] | None) – List of fields to return.

Returns:

TenantStorage object.

Raises:

• NotFoundError – If allocation not found.

• ValueError – If neither key nor tier provided.

Return type:

TenantStorage

create(tier, provisioned_gb=None, provisioned_bytes=None)

Create a new storage allocation for this tenant.

Parameters:

• tier (int) – Storage tier number (1-5). Tier 0 is reserved for system metadata.

• provisioned_gb (int | None) – Provisioned storage in GB (use this or provisioned_bytes).

• provisioned_bytes (int | None) – Provisioned storage in bytes (precise control).

Returns:

Created TenantStorage object.

Raises:

• ValueError – If tenant is a snapshot, tier is invalid, or no size specified.

• ConflictError – If an allocation for this tier already exists.

Return type:

TenantStorage

update(key, **kwargs)

Update a storage allocation.

Parameters:

• key (int) – Storage allocation $key (ID).

• **kwargs (Any) – Fields to update. Supported fields: - provisioned: Provisioned size in bytes

Returns:

Updated TenantStorage object.

Return type:

TenantStorage

update_by_tier(tier, provisioned_gb=None, provisioned_bytes=None)

Update a storage allocation by tier number.

Parameters:

• tier (int) – Tier number (1-5).

• provisioned_gb (int | None) – New provisioned size in GB.

• provisioned_bytes (int | None) – New provisioned size in bytes.

Returns:

Updated TenantStorage object.

Raises:

• NotFoundError – If no allocation exists for this tier.

• ValueError – If no size specified.

Return type:

TenantStorage

delete(key)

Delete a storage allocation.

Parameters:

key (int) – Storage allocation $key (ID).

Return type:

None

Warning

Removing a storage allocation with data may cause data loss. Ensure the allocation is empty before removal.

delete_by_tier(tier)

Delete a storage allocation by tier number.

Parameters:

tier (int) – Tier number (1-5).

Raises:

NotFoundError – If no allocation exists for this tier.

Return type:

None

Warning

Removing a storage allocation with data may cause data loss. Ensure the allocation is empty before removal.

Tenant Network Blocks

Tenant network block resource manager.

class pyvergeos.resources.tenant_network_blocks.TenantNetworkBlock

Bases: ResourceObject

Tenant Network Block resource object.

Represents a CIDR network block assigned to a tenant from a parent network. These blocks allow tenants to have entire subnets routed to them.

property tenant_key: int

Get the tenant key this block is assigned to.

Parses the owner field which is in format ‘tenants/{key}’.

property network_key: int

Get the network key this block belongs to.

property network_name: str | None

Get the network name.

property cidr: str

Get the CIDR notation (e.g., ‘192.168.100.0/24’).

property network_address: str

Get the network address portion of the CIDR.

property prefix_length: int

Get the prefix length (subnet mask bits).

property address_count: int

Get the number of addresses in this block.

property description: str | None

Get the block description.

delete()

Delete this network block assignment.

Return type:

None

class pyvergeos.resources.tenant_network_blocks.TenantNetworkBlockManager

Bases: ResourceManager[TenantNetworkBlock]

Manager for Tenant Network Block operations.

This manager handles CIDR network blocks assigned to tenants. Network blocks allow routing entire subnets from a parent network to a tenant.

This manager is accessed through a Tenant object’s network_blocks property or via client.tenants.network_blocks(tenant_key).

Example

>>> tenant = client.tenants.get(name="my-tenant")
>>> # List network blocks
>>> for block in tenant.network_blocks.list():
...     print(f"{block.cidr} on {block.network_name}")
>>> # Assign a network block
>>> tenant.network_blocks.create(network=1, cidr="192.168.100.0/24")

__init__(client, tenant)

Parameters:

• client (VergeClient)

• tenant (Tenant)

Return type:

None

list(filter=None, fields=None, cidr=None, **kwargs)

List network blocks assigned to this tenant.

Parameters:

• filter (str | None) – Additional OData filter string.

• fields (list[str] | None) – List of fields to return.

• cidr (str | None) – Filter by specific CIDR block.

• **kwargs (Any) – Additional filter arguments.

Returns:

List of TenantNetworkBlock objects.

Return type:

list[TenantNetworkBlock]

get(key=None, *, cidr=None, fields=None)

Get a network block by key or CIDR.

Parameters:

• key (int | None) – Network block $key (ID).

• cidr (str | None) – CIDR notation to find.

• fields (list[str] | None) – List of fields to return.

Returns:

TenantNetworkBlock object.

Raises:

• NotFoundError – If network block not found.

• ValueError – If neither key nor cidr provided.

Return type:

TenantNetworkBlock

create(cidr, network=None, network_name=None, description='')

Assign a network block to this tenant.

Parameters:

• cidr (str) – Network block in CIDR notation (e.g., “192.168.100.0/24”).

• network (int | None) – Network $key (ID) to assign block from.

• network_name (str | None) – Network name (alternative to network key).

• description (str) – Optional description for the block.

Returns:

Created TenantNetworkBlock object.

Raises:

• ValueError – If tenant is a snapshot or neither network nor network_name provided.

• NotFoundError – If network not found.

• ConflictError – If CIDR already exists or overlaps.

Return type:

TenantNetworkBlock

delete(key)

Remove a network block assignment.

Parameters:

key (int) – Network block $key (ID).

Return type:

None

Warning

Removing a network block may disrupt connectivity for services using addresses in that range. Firewall rules referencing the block must be removed first.

delete_by_cidr(cidr)

Remove a network block by CIDR.

Parameters:

cidr (str) – CIDR notation of the block to remove.

Raises:

NotFoundError – If no block with this CIDR exists.

Return type:

None

Tenant External IPs

Tenant external IP resource manager.

class pyvergeos.resources.tenant_external_ips.TenantExternalIP

Bases: ResourceObject

Tenant External IP resource object.

Represents a virtual IP address assigned to a tenant from a parent network. These external IPs can be used for NAT rules, services, or other networking purposes within the tenant’s environment.

property tenant_key: int

Get the tenant key this IP is assigned to.

Parses the owner field which is in format ‘tenants/{key}’.

property network_key: int

Get the network key this IP belongs to.

property network_name: str | None

Get the network name.

property ip_address: str

Get the IP address.

property hostname: str | None

Get the hostname associated with this IP.

property mac_address: str | None

Get the MAC address (if any).

property ip_type: str

Get the IP type (should be ‘virtual’ for external IPs).

delete()

Delete this external IP assignment.

Return type:

None

class pyvergeos.resources.tenant_external_ips.TenantExternalIPManager

Bases: ResourceManager[TenantExternalIP]

Manager for Tenant External IP operations.

This manager handles virtual IP addresses assigned to tenants. External IPs allow tenants to have public or routable addresses from a parent network that can be used for NAT rules, services, or external connectivity.

This manager is accessed through a Tenant object’s external_ips property or via client.tenants.external_ips(tenant_key).

Example

>>> tenant = client.tenants.get(name="my-tenant")
>>> # List external IPs
>>> for ip in tenant.external_ips.list():
...     print(f"{ip.ip_address} on {ip.network_name}")
>>> # Assign an external IP
>>> tenant.external_ips.create(network=1, ip="192.168.1.100")

__init__(client, tenant)

Parameters:

• client (VergeClient)

• tenant (Tenant)

Return type:

None

list(filter=None, fields=None, ip=None, **kwargs)

List external IPs assigned to this tenant.

Parameters:

• filter (str | None) – Additional OData filter string.

• fields (list[str] | None) – List of fields to return.

• ip (str | None) – Filter by specific IP address.

• **kwargs (Any) – Additional filter arguments.

Returns:

List of TenantExternalIP objects.

Return type:

list[TenantExternalIP]

get(key=None, *, ip=None, fields=None)

Get an external IP by key or IP address.

Parameters:

• key (int | None) – IP address $key (ID).

• ip (str | None) – IP address to find.

• fields (list[str] | None) – List of fields to return.

Returns:

TenantExternalIP object.

Raises:

• NotFoundError – If external IP not found.

• ValueError – If neither key nor ip provided.

Return type:

TenantExternalIP

create(ip, network=None, network_name=None, hostname=None, description='')

Assign an external IP to this tenant.

Parameters:

• ip (str) – IP address to assign (e.g., “192.168.1.100”).

• network (int | None) – Network $key (ID) to assign IP from.

• network_name (str | None) – Network name (alternative to network key).

• hostname (str | None) – Optional hostname for DNS.

• description (str) – Optional description for the IP.

Returns:

Created TenantExternalIP object.

Raises:

• ValueError – If tenant is a snapshot or neither network nor network_name provided.

• NotFoundError – If network not found.

• ConflictError – If IP already exists.

Return type:

TenantExternalIP

delete(key)

Remove an external IP assignment.

Parameters:

key (int) – IP address $key (ID).

Return type:

None

Warning

Removing an external IP may disrupt connectivity for services using that address. Firewall rules referencing the IP must be removed first.

delete_by_ip(ip)

Remove an external IP by IP address.

Parameters:

ip (str) – IP address to remove.

Raises:

NotFoundError – If no IP with this address exists.

Return type:

None

Tenant Snapshots

Tenant snapshot resource manager.

class pyvergeos.resources.tenant_snapshots.TenantSnapshot

Bases: ResourceObject

Tenant Snapshot resource object.

property tenant_key: int

Get the tenant key this snapshot belongs to.

property created_at: datetime | None

Get creation timestamp as datetime.

property expires_at: datetime | None

Get expiration timestamp as datetime.

property never_expires: bool

Check if snapshot never expires.

property profile: str | None

Get the snapshot profile name (if created by a profile).

property period: str | None

Get the snapshot period (if created by a profile).

property min_snapshots: int

Get minimum snapshots to keep.

restore()

Restore the tenant to this snapshot.

The tenant must be powered off before restoration.

Returns:

Restore task information.

Raises:

ValueError – If the tenant is running.

Return type:

dict[str, Any] | None

class pyvergeos.resources.tenant_snapshots.TenantSnapshotManager

Bases: ResourceManager[TenantSnapshot]

Manager for Tenant Snapshot operations.

This manager is accessed through a Tenant object’s snapshots property or via client.tenants.snapshots(tenant_key).

__init__(client, tenant)

Parameters:

• client (VergeClient)

• tenant (Tenant)

Return type:

None

list(filter=None, fields=None, **kwargs)

List snapshots for this tenant.

Parameters:

• filter (str | None) – Additional OData filter string.

• fields (list[str] | None) – List of fields to return.

• **kwargs (Any) – Additional filter arguments.

Returns:

List of TenantSnapshot objects.

Return type:

list[TenantSnapshot]

get(key=None, *, name=None, fields=None)

Get a snapshot by key or name.

Parameters:

• key (int | None) – Snapshot $key (ID).

• name (str | None) – Snapshot name.

• fields (list[str] | None) – List of fields to return.

Returns:

TenantSnapshot object.

Raises:

• NotFoundError – If snapshot not found.

• ValueError – If neither key nor name provided.

Return type:

TenantSnapshot

create(name, description='', expires_in_days=0, expires_at=None)

Create a new snapshot for this tenant.

Parameters:

• name (str) – Snapshot name (required).

• description (str) – Snapshot description.

• expires_in_days (int) – Days until snapshot expires. Use 0 for never expires.

• expires_at (datetime | None) – Specific expiration datetime (overrides expires_in_days).

Returns:

Created TenantSnapshot object.

Raises:

• ValueError – If tenant is a snapshot.

• ConflictError – If a snapshot with this name already exists.

Return type:

TenantSnapshot

delete(key)

Delete a snapshot.

Parameters:

key (int) – Snapshot $key (ID).

Return type:

None

restore(key)

Restore the tenant to a snapshot.

The tenant must be powered off before restoration. WARNING: All changes made after the snapshot was created will be lost.

Parameters:

key (int) – Snapshot $key (ID).

Returns:

Restore task information.

Raises:

ValueError – If tenant is running.

Return type:

dict[str, Any] | None

Tenant Layer 2 Networks

Tenant Layer 2 network resource manager.

class pyvergeos.resources.tenant_layer2.TenantLayer2Network

Bases: ResourceObject

Tenant Layer 2 Network resource object.

Represents a Layer 2 network assignment that provides bridged connectivity between a parent network and a tenant. Layer 2 networks allow tenants direct access to parent network segments.

property tenant_key: int

Get the tenant key this L2 network is assigned to.

property tenant_name: str | None

Get the tenant name.

property network_key: int

Get the network key (vnet).

property network_name: str | None

Get the network name.

property network_type: str | None

Get the network type (internal, external, bgp, vpn, etc.).

property is_enabled: bool

Check if the Layer 2 network assignment is enabled.

enable()

Enable this Layer 2 network assignment.

Returns:

Updated TenantLayer2Network object.

Return type:

TenantLayer2Network

disable()

Disable this Layer 2 network assignment.

Returns:

Updated TenantLayer2Network object.

Return type:

TenantLayer2Network

delete()

Delete this Layer 2 network assignment.

Return type:

None

class pyvergeos.resources.tenant_layer2.TenantLayer2Manager

Bases: ResourceManager[TenantLayer2Network]

Manager for Tenant Layer 2 Network operations.

This manager handles Layer 2 network assignments for tenants. Layer 2 networks provide bridged connectivity between parent and tenant networks, allowing tenants direct access to parent network segments.

Only certain network types can be assigned: internal, external, bgp, vpn, or bridged physical networks. A maximum of 28 Layer 2 networks can be assigned per tenant.

This manager is accessed through a Tenant object’s l2_networks property or via client.tenants.l2_networks(tenant_key).

Example

>>> tenant = client.tenants.get(name="my-tenant")
>>> # List Layer 2 networks
>>> for l2 in tenant.l2_networks.list():
...     print(f"{l2.network_name}: {l2.is_enabled}")
>>> # Assign a Layer 2 network
>>> tenant.l2_networks.create(network_name="VLAN100")

__init__(client, tenant)

Parameters:

• client (VergeClient)

• tenant (Tenant)

Return type:

None

list(filter=None, fields=None, **kwargs)

List Layer 2 networks assigned to this tenant.

Parameters:

• filter (str | None) – Additional OData filter string.

• fields (list[str] | None) – List of fields to return.

• **kwargs (Any) – Additional filter arguments.

Returns:

List of TenantLayer2Network objects.

Return type:

list[TenantLayer2Network]

get(key=None, *, network_name=None, fields=None)

Get a Layer 2 network by key or network name.

Parameters:

• key (int | None) – Layer 2 network assignment $key (ID).

• network_name (str | None) – Network name to find.

• fields (list[str] | None) – List of fields to return.

Returns:

TenantLayer2Network object.

Raises:

• NotFoundError – If Layer 2 network not found.

• ValueError – If neither key nor network_name provided.

Return type:

TenantLayer2Network

create(network=None, network_name=None, enabled=True)

Assign a Layer 2 network to this tenant.

Only certain network types can be assigned as Layer 2 networks: internal, external, bgp, vpn, or bridged physical networks. A maximum of 28 Layer 2 networks can be assigned per tenant.

Parameters:

• network (int | None) – Network $key (ID) to assign.

• network_name (str | None) – Network name (alternative to network key).

• enabled (bool) – Whether the assignment should be enabled (default True).

Returns:

Created TenantLayer2Network object.

Raises:

• ValueError – If tenant is a snapshot or neither network nor network_name provided.

• NotFoundError – If network not found.

• ConflictError – If network already assigned or max limit reached.

Return type:

TenantLayer2Network

update(key, enabled)

Update a Layer 2 network assignment.

Only the enabled status can be modified. To change the network assignment, remove and recreate it.

Parameters:

• key (int) – Layer 2 network assignment $key (ID).

• enabled (bool) – Whether the assignment should be enabled.

Returns:

Updated TenantLayer2Network object.

Return type:

TenantLayer2Network

delete(key)

Remove a Layer 2 network assignment.

Parameters:

key (int) – Layer 2 network assignment $key (ID).

Return type:

None

Warning

Removing a Layer 2 network disconnects the bridged connectivity between the parent and tenant networks. This may affect tenant workloads using that network segment.

delete_by_network(network_name)

Remove a Layer 2 network assignment by network name.

Parameters:

network_name (str) – Name of the network to remove.

Raises:

NotFoundError – If no assignment with this network exists.

Return type:

None

Tenant Nodes

Tenant node (compute resource) allocation manager.

class pyvergeos.resources.tenant_nodes.TenantNode

Bases: ResourceObject

Tenant Node resource object.

Represents a virtual node allocated to a tenant. Each tenant can have one or more nodes providing CPU and RAM resources.

property tenant_key: int

Get the tenant key this node belongs to.

property name: str

Get the node name (e.g., ‘node1’).

property node_id: int

Get the node ID number within the tenant.

property cpu_cores: int

Get the number of CPU cores allocated.

property ram_mb: int

Get RAM allocation in MB.

property ram_gb: float

Get RAM allocation in GB.

property is_enabled: bool

Check if the node is enabled.

property is_running: bool

Check if the node is currently running.

property status: str

Get the node status.

property host_node: str | None

Get the physical host node name.

property cluster_key: int | None

Get the cluster key.

property cluster_name: str | None

Get the cluster name.

property preferred_node_key: int | None

Get the preferred node key.

property preferred_node_name: str | None

Get the preferred node name.

property on_power_loss: str

Get power loss behavior (power_on, last_state, leave_off).

property machine_key: int | None

Get the machine key for this node.

save(**kwargs)

Save changes to this node.

Parameters:

**kwargs (Any) – Fields to update. Supported fields: - cpu_cores: Number of CPU cores - ram: RAM in MB - enabled: Enable/disable the node - description: Node description

Returns:

Updated TenantNode object.

Return type:

TenantNode

delete()

Delete this node from the tenant.

Return type:

None

class pyvergeos.resources.tenant_nodes.TenantNodeManager

Bases: ResourceManager[TenantNode]

Manager for Tenant Node operations.

This manager handles compute node allocations for tenants. Each tenant can have one or more virtual nodes with CPU and RAM resources.

This manager is accessed through a Tenant object’s nodes property or via client.tenants.nodes(tenant_key).

Example

>>> tenant = client.tenants.get(name="my-tenant")
>>> # List all nodes
>>> for node in tenant.nodes.list():
...     print(f"{node.name}: {node.cpu_cores} cores, {node.ram_gb} GB")
>>> # Add a node with 4 cores and 16 GB RAM
>>> tenant.nodes.create(cpu_cores=4, ram_gb=16, cluster=1)

__init__(client, tenant)

Parameters:

• client (VergeClient)

• tenant (Tenant)

Return type:

None

list(filter=None, fields=None, **kwargs)

List nodes for this tenant.

Parameters:

• filter (str | None) – Additional OData filter string.

• fields (list[str] | None) – List of fields to return.

• **kwargs (Any) – Additional filter arguments.

Returns:

List of TenantNode objects.

Return type:

list[TenantNode]

get(key=None, *, name=None, fields=None)

Get a node by key or name.

Parameters:

• key (int | None) – Node $key (ID).

• name (str | None) – Node name (e.g., ‘node1’).

• fields (list[str] | None) – List of fields to return.

Returns:

TenantNode object.

Raises:

• NotFoundError – If node not found.

• ValueError – If neither key nor name provided.

Return type:

TenantNode

create(cpu_cores=4, ram_mb=None, ram_gb=None, cluster=1, preferred_node=None, name=None, description='')

Create a new node for this tenant.

Parameters:

• cpu_cores (int) – Number of CPU cores (default: 4).

• ram_mb (int | None) – RAM allocation in MB (use this or ram_gb).

• ram_gb (int | None) – RAM allocation in GB (default: 16 GB if neither specified).

• cluster (int) – Cluster key to run the node on (default: 1).

• preferred_node (int | None) – Preferred physical node key.

• name (str | None) – Node name (auto-generated if not specified).

• description (str) – Node description.

Returns:

Created TenantNode object.

Raises:

ValueError – If tenant is a snapshot or invalid parameters.

Return type:

TenantNode

update(key, **kwargs)

Update a node.

Parameters:

• key (int) – Node $key (ID).

• **kwargs (Any) – Fields to update. Supported fields: - cpu_cores: Number of CPU cores - ram: RAM in MB - enabled: Enable/disable the node - description: Node description - cluster: Cluster key - preferred_node: Preferred node key

Returns:

Updated TenantNode object.

Return type:

TenantNode

delete(key)

Delete a node.

Parameters:

key (int) – Node $key (ID).

Return type:

None

Warning

The node must be powered off before it can be deleted.

Storage

NAS Services

NAS service management resources.

class pyvergeos.resources.nas_services.NASService

Bases: ResourceObject

NAS service resource object.

Represents a NAS service VM that manages volumes and file shares.

key

The NAS service unique identifier ($key).

name

NAS service name.

vm

The underlying VM key.

max_imports

Maximum simultaneous import jobs.

max_syncs

Maximum simultaneous sync jobs.

disable_swap

Whether swap is disabled.

read_ahead_kb_default

Read-ahead buffer size in KB.

cifs

CIFS settings key.

nfs

NFS settings key.

property is_running: bool

Check if the NAS service VM is running.

property vm_key: int | None

Get the underlying VM key.

property volume_count: int

Get the number of volumes managed by this service.

property antivirus: NasServiceAntivirusManager

Get antivirus configuration manager for this NAS service.

Returns:

NasServiceAntivirusManager scoped to this service.

Note

NAS service requires 8GB+ RAM for antivirus support.

Example

>>> # Get service antivirus config
>>> svc_av = nas.antivirus.get()

>>> # Update settings
>>> svc_av = nas.antivirus.update(
...     key=svc_av.key,
...     max_recursion=20
... )

class pyvergeos.resources.nas_services.CIFSSettings

Bases: ResourceObject

CIFS/SMB settings resource object.

Represents CIFS/SMB configuration for a NAS service.

key

The CIFS settings unique identifier ($key).

service

The parent NAS service key.

workgroup

NetBIOS workgroup name.

realm

Kerberos realm for AD.

server_type

Server role (default, MEMBER, BDC, PDC).

map_to_guest

How invalid users/passwords are handled.

server_min_protocol

Minimum SMB protocol version.

extended_acl_support

Whether extended ACLs are enabled.

ad_status

Active Directory join status.

class pyvergeos.resources.nas_services.NFSSettings

Bases: ResourceObject

NFS settings resource object.

Represents NFS configuration for a NAS service.

key

The NFS settings unique identifier ($key).

service

The parent NAS service key.

enable_nfsv4

Whether NFSv4 is enabled.

allowed_hosts

List of allowed hosts/networks.

allow_all

Whether all hosts are allowed.

squash

User/group squashing mode.

data_access

Read-only or read-write.

anonuid

Anonymous user ID.

anongid

Anonymous group ID.

class pyvergeos.resources.nas_services.NASServiceManager

Bases: ResourceManager[NASService]

Manager for NAS service operations.

NAS services are specialized VMs that manage NAS volumes and file shares (CIFS/SMB and NFS).

Example

>>> # List all NAS services
>>> for service in client.nas_services.list():
...     print(f"{service.name}: {service.volume_count} volumes")

>>> # Get a specific NAS service
>>> nas = client.nas_services.get(name="NAS01")

>>> # Get CIFS settings
>>> cifs = client.nas_services.get_cifs_settings(nas.key)
>>> print(f"Workgroup: {cifs.workgroup}")

>>> # Update NFS settings
>>> client.nas_services.set_nfs_settings(nas.key, enable_nfsv4=True)

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, status=None, **filter_kwargs)

List NAS services with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• status (str | None) – Filter by VM status (running, stopped, etc.).

• **filter_kwargs (Any) – Shorthand filter arguments (name, etc.).

Returns:

List of NASService objects.

Return type:

list[NASService]

Example

>>> # List all NAS services
>>> services = client.nas_services.list()

>>> # List running services only
>>> running = client.nas_services.list(status="running")

>>> # Filter by name
>>> nas01 = client.nas_services.list(name="NAS01")

list_running()

List all running NAS services.

Returns:

List of running NASService objects.

Return type:

list[NASService]

list_stopped()

List all stopped NAS services.

Returns:

List of stopped NASService objects.

Return type:

list[NASService]

get(key=None, *, name=None, fields=None)

Get a single NAS service by key or name.

Parameters:

• key (int | None) – NAS service $key (ID).

• name (str | None) – NAS service name.

• fields (list[str] | None) – List of fields to return.

Returns:

NASService object.

Raises:

• NotFoundError – If NAS service not found.

• ValueError – If neither key nor name provided.

Return type:

NASService

Example

>>> # Get by key
>>> service = client.nas_services.get(1)

>>> # Get by name
>>> service = client.nas_services.get(name="NAS01")

create(name, *, hostname=None, network=None, cores=4, memory_gb=8, auto_update=False)

Create a new NAS service by deploying the Services recipe.

Parameters:

• name (str) – Name for the new NAS service.

• hostname (str | None) – Hostname for the NAS VM (defaults to name with invalid chars removed).

• network (int | str | None) – Network to connect to (key or name). Defaults to ‘Internal’.

• cores (int) – Number of CPU cores (default: 4).

• memory_gb (int) – Amount of RAM in GB (default: 8).

• auto_update (bool) – Enable auto-update on power off.

Returns:

Created NASService object.

Raises:

ValueError – If Services recipe not found or NAS service already exists.

Return type:

NASService

Example

>>> # Create with defaults
>>> nas = client.nas_services.create("NAS01")

>>> # Create with custom settings
>>> nas = client.nas_services.create(
...     "FileServer",
...     network="Internal",
...     cores=8,
...     memory_gb=16
... )

update(key, *, description=None, cpu_cores=None, memory_gb=None, max_imports=None, max_syncs=None, disable_swap=None, read_ahead_kb=None)

Update NAS service settings.

Updates both the underlying VM settings (CPU, RAM, description) and NAS-specific settings (max_imports, max_syncs, etc.).

Parameters:

• key (int) – NAS service $key (ID).

• description (str | None) – New description.

• cpu_cores (int | None) – Number of CPU cores (requires restart).

• memory_gb (int | None) – Amount of RAM in GB (requires restart).

• max_imports (int | None) – Maximum simultaneous import jobs (1-10).

• max_syncs (int | None) – Maximum simultaneous sync jobs (1-10).

• disable_swap (bool | None) – Disable swap on the NAS service.

• read_ahead_kb (int | None) – Read-ahead buffer size (0=auto, 64, 128, 256, 512, 1024, 2048, 4096).

Returns:

Updated NASService object.

Return type:

NASService

Example

>>> # Update NAS settings
>>> client.nas_services.update(1, max_imports=5, max_syncs=3)

>>> # Update VM resources (requires restart)
>>> client.nas_services.update(1, cpu_cores=8, memory_gb=16)

delete(key, *, force=False)

Delete a NAS service.

The NAS service VM must be stopped before deletion. If the service has volumes, they must be removed first unless force=True.

Parameters:

• key (int) – NAS service $key (ID).

• force (bool) – Remove even if service has volumes (will delete all data).

Raises:

ValueError – If service is running or has volumes without force.

Return type:

None

Example

>>> # Delete a stopped NAS service
>>> client.nas_services.delete(1)

>>> # Force delete (removes all volumes and data)
>>> client.nas_services.delete(1, force=True)

power_on(key)

Power on a NAS service.

Parameters:

key (int) – NAS service $key (ID).

Returns:

Task information dict or None.

Return type:

dict[str, Any] | None

Example

>>> client.nas_services.power_on(1)

power_off(key, *, force=False)

Power off a NAS service.

Parameters:

• key (int) – NAS service $key (ID).

• force (bool) – Force power off (like pulling the plug).

Returns:

Task information dict or None.

Return type:

dict[str, Any] | None

Example

>>> # Graceful shutdown
>>> client.nas_services.power_off(1)

>>> # Force power off
>>> client.nas_services.power_off(1, force=True)

restart(key)

Restart a NAS service.

Parameters:

key (int) – NAS service $key (ID).

Returns:

Task information dict or None.

Return type:

dict[str, Any] | None

Example

>>> client.nas_services.restart(1)

get_cifs_settings(key)

Get CIFS/SMB settings for a NAS service.

Parameters:

key (int) – NAS service $key (ID).

Returns:

CIFSSettings object.

Raises:

NotFoundError – If CIFS settings not found.

Return type:

CIFSSettings

Example

>>> cifs = client.nas_services.get_cifs_settings(1)
>>> print(f"Workgroup: {cifs.workgroup}")
>>> print(f"Min Protocol: {cifs.server_min_protocol}")

set_cifs_settings(key, *, workgroup=None, min_protocol=None, guest_mapping=None, extended_acl_support=None)

Update CIFS/SMB settings for a NAS service.

Parameters:

• key (int) – NAS service $key (ID).

• workgroup (str | None) – NetBIOS workgroup name.

• min_protocol (str | None) – Minimum SMB protocol version. Valid values: none, SMB2, SMB2_02, SMB2_10, SMB3, SMB3_00, SMB3_02, SMB3_11

• guest_mapping (str | None) – How to handle invalid users/passwords. Valid values: never, bad user, bad password, bad uid

• extended_acl_support (bool | None) – Enable extended ACL support.

Returns:

Updated CIFSSettings object.

Return type:

CIFSSettings

Example

>>> # Set minimum protocol to SMB3
>>> client.nas_services.set_cifs_settings(1, min_protocol="SMB3")

>>> # Update workgroup
>>> client.nas_services.set_cifs_settings(1, workgroup="MYWORKGROUP")

get_nfs_settings(key)

Get NFS settings for a NAS service.

Parameters:

key (int) – NAS service $key (ID).

Returns:

NFSSettings object.

Raises:

NotFoundError – If NFS settings not found.

Return type:

NFSSettings

Example

>>> nfs = client.nas_services.get_nfs_settings(1)
>>> print(f"NFSv4 Enabled: {nfs.enable_nfsv4}")
>>> print(f"Allowed Hosts: {nfs.allowed_hosts}")

set_nfs_settings(key, *, enable_nfsv4=None, allowed_hosts=None, allow_all=None, squash=None, data_access=None, anon_uid=None, anon_gid=None, no_acl=None, insecure=None, async_mode=None)

Update NFS settings for a NAS service.

Parameters:

• key (int) – NAS service $key (ID).

• enable_nfsv4 (bool | None) – Enable NFSv4 protocol support.

• allowed_hosts (str | None) – Comma-separated list of allowed hosts/networks.

• allow_all (bool | None) – Allow all hosts to access NFS exports.

• squash (str | None) – User/group squashing mode. Valid values: root_squash, all_squash, no_root_squash

• data_access (str | None) – Read-only or read-write access. Valid values: ro, rw

• anon_uid (int | None) – Anonymous user ID for squashed users.

• anon_gid (int | None) – Anonymous group ID for squashed users.

• no_acl (bool | None) – Disable ACL support for NFS exports.

• insecure (bool | None) – Allow connections from non-privileged ports.

• async_mode (bool | None) – Enable async mode for better performance.

Returns:

Updated NFSSettings object.

Return type:

NFSSettings

Example

>>> # Enable NFSv4
>>> client.nas_services.set_nfs_settings(1, enable_nfsv4=True)

>>> # Set allowed hosts
>>> client.nas_services.set_nfs_settings(
...     1, allowed_hosts="192.168.1.0/24,10.0.0.0/8"
... )

NAS Volumes

NAS volume and snapshot resources.

class pyvergeos.resources.nas_volumes.NASVolume

Bases: ResourceObject

NAS volume resource object.

Represents a NAS volume (virtual filesystem) managed by a NAS service.

Note

Volume keys are 40-character hex strings, not integers like most other VergeOS resources.

key

The volume unique identifier ($key) - 40-char hex string.

id

The volume ID (same as $key).

name

Volume name.

description

Volume description.

enabled

Whether the volume is enabled.

max_size

Maximum size in bytes.

preferred_tier

Preferred storage tier (1-5).

fs_type

Filesystem type (ext4, cifs, nfs, ybfs, verge_vm_export).

read_only

Whether the volume is read-only.

discard

Whether discard is enabled for deleted files.

owner_user

Volume directory owner user.

owner_group

Volume directory owner group.

encrypt

Whether the volume is encrypted.

automount_snapshots

Whether snapshots are auto-mounted.

is_snapshot

Whether this is a snapshot volume.

service

Parent NAS service key.

snapshot_profile

Associated snapshot profile key.

created

Creation timestamp.

modified

Last modified timestamp.

property key: str

Resource primary key ($key) - 40-character hex string.

Raises:

ValueError – If resource has no $key (not yet persisted).

refresh()

Refresh resource data from API.

Returns:

Updated NASVolume object.

Return type:

NASVolume

save(**kwargs)

Save changes to resource.

Parameters:

**kwargs (Any) – Fields to update.

Returns:

Updated NASVolume object.

Return type:

NASVolume

delete()

Delete this volume.

Return type:

None

property max_size_gb: float

Get the maximum size in GB.

property used_gb: float

Get the used space in GB.

property allocated_gb: float

Get the allocated space in GB.

property is_mounted: bool

Check if the volume is mounted.

property service_key: int | None

Get the parent NAS service key.

property files: NASVolumeFileManager

Get a file manager for browsing this volume’s files.

Returns:

NASVolumeFileManager scoped to this volume.

Example

>>> # Browse volume files
>>> for f in volume.files.list():
...     print(f"{f.name}: {f.size_display}")

>>> # Browse a subdirectory
>>> for f in volume.files.list("/documents"):
...     print(f.name)

property antivirus: VolumeAntivirusManager

Get antivirus manager for this volume.

Returns:

VolumeAntivirusManager scoped to this volume.

Example

>>> # Get antivirus configuration
>>> av = volume.antivirus.get()

>>> # Enable and start scan
>>> av.enable()
>>> av.start_scan()

>>> # Check status
>>> status = av.get_status()
>>> print(f"Status: {status.status}")

class pyvergeos.resources.nas_volumes.NASVolumeSnapshot

Bases: ResourceObject

NAS volume snapshot resource object.

Represents a point-in-time snapshot of a NAS volume.

key

The snapshot unique identifier ($key).

name

Snapshot name.

description

Snapshot description.

volume

Parent volume key.

snap_volume

Mounted snapshot volume key (if mounted).

created

Creation timestamp.

expires

Expiration timestamp (0 for never expires).

expires_type

Expiration type (never, date).

enabled

Whether the snapshot is enabled.

created_manually

Whether created manually.

quiesce

Whether I/O was quiesced during creation.

property volume_key: str | None

Get the parent volume key.

Note: NAS volume keys are 40-character hex strings, not integers.

property never_expires: bool

Check if the snapshot never expires.

class pyvergeos.resources.nas_volumes.NASVolumeManager

Bases: ResourceManager[NASVolume]

Manager for NAS volume operations.

NAS volumes are virtual filesystems that can be shared via CIFS/SMB or NFS.

Example

>>> # List all volumes
>>> for volume in client.nas_volumes.list():
...     print(f"{volume.name}: {volume.max_size_gb}GB")

>>> # Get a specific volume
>>> vol = client.nas_volumes.get(name="FileShare")

>>> # Create a volume
>>> vol = client.nas_volumes.create(
...     name="DataShare",
...     service=1,
...     size_gb=500,
...     tier=1
... )

>>> # Create a snapshot
>>> snap = vol.snapshots.create("pre-update")

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, enabled=None, fs_type=None, service=None, **filter_kwargs)

List NAS volumes with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• enabled (bool | None) – Filter by enabled state.

• fs_type (str | None) – Filter by filesystem type (ext4, cifs, nfs, ybfs, verge_vm_export).

• service (int | str | None) – Filter by NAS service (key or name).

• **filter_kwargs (Any) – Shorthand filter arguments (name, etc.).

Returns:

List of NASVolume objects.

Return type:

list[NASVolume]

Example

>>> # List all volumes
>>> volumes = client.nas_volumes.list()

>>> # List enabled volumes only
>>> enabled = client.nas_volumes.list(enabled=True)

>>> # Filter by filesystem type
>>> ext4_vols = client.nas_volumes.list(fs_type="ext4")

>>> # Filter by NAS service
>>> nas01_vols = client.nas_volumes.list(service="NAS01")

get(key=None, *, name=None, fields=None)

Get a single NAS volume by key or name.

Parameters:

• key (str | None) – Volume $key (40-character hex string).

• name (str | None) – Volume name.

• fields (list[str] | None) – List of fields to return.

Returns:

NASVolume object.

Raises:

• NotFoundError – If volume not found.

• ValueError – If no identifier provided.

Return type:

NASVolume

Example

>>> # Get by key
>>> vol = client.nas_volumes.get("8f73f8bcc9c9f1aaba32f733bfc295acaf548554")

>>> # Get by name
>>> vol = client.nas_volumes.get(name="FileShare")

create(name, service, size_gb, *, tier=None, description=None, read_only=False, discard=True, owner_user=None, owner_group=None, snapshot_profile=None, enabled=True)

Create a new NAS volume.

Parameters:

• name (str) – Volume name (alphanumeric with underscores/hyphens only).

• service (int | str) – NAS service (key or name) to create the volume on.

• size_gb (int) – Maximum size in gigabytes (1-524288).

• tier (int | None) – Preferred storage tier (1-5).

• description (str | None) – Volume description.

• read_only (bool) – Create as read-only volume.

• discard (bool) – Enable automatic discard of deleted files (default True).

• owner_user (str | None) – Volume directory owner user.

• owner_group (str | None) – Volume directory owner group.

• snapshot_profile (int | None) – Snapshot profile key.

• enabled (bool) – Enable the volume (default True).

Returns:

Created NASVolume object.

Raises:

ValueError – If NAS service not found.

Return type:

NASVolume

Example

>>> # Create a basic volume
>>> vol = client.nas_volumes.create("FileShare", "NAS01", 500)

>>> # Create with options
>>> vol = client.nas_volumes.create(
...     "Archive",
...     service="NAS01",
...     size_gb=2000,
...     tier=3,
...     description="Archive storage"
... )

update(key, *, description=None, size_gb=None, tier=None, enabled=None, read_only=None, discard=None, owner_user=None, owner_group=None, snapshot_profile=None, automount_snapshots=None)

Update a NAS volume.

Parameters:

• key (str) – Volume $key (40-character hex string).

• description (str | None) – New description.

• size_gb (int | None) – New maximum size in gigabytes.

• tier (int | None) – New preferred storage tier (1-5).

• enabled (bool | None) – Enable or disable the volume.

• read_only (bool | None) – Set read-only or read-write.

• discard (bool | None) – Enable or disable automatic discard.

• owner_user (str | None) – New owner user.

• owner_group (str | None) – New owner group.

• snapshot_profile (int | None) – New snapshot profile key (or None to remove).

• automount_snapshots (bool | None) – Enable or disable auto-mount of snapshots.

Returns:

Updated NASVolume object.

Return type:

NASVolume

Example

>>> # Increase size
>>> client.nas_volumes.update(vol.key, size_gb=1000)

>>> # Change tier
>>> client.nas_volumes.update(vol.key, tier=3)

>>> # Disable volume
>>> client.nas_volumes.update(vol.key, enabled=False)

delete(key)

Delete a NAS volume.

This operation is destructive and cannot be undone. All data on the volume will be permanently deleted.

Parameters:

key (str) – Volume $key (40-character hex string).

Raises:

NotFoundError – If volume not found.

Return type:

None

Example

>>> client.nas_volumes.delete(vol.key)

enable(key)

Enable a NAS volume.

Parameters:

key (str) – Volume $key (40-character hex string).

Returns:

Updated NASVolume object.

Return type:

NASVolume

Example

>>> client.nas_volumes.enable(vol.key)

disable(key)

Disable a NAS volume.

Parameters:

key (str) – Volume $key (40-character hex string).

Returns:

Updated NASVolume object.

Return type:

NASVolume

Example

>>> client.nas_volumes.disable(vol.key)

reset(key)

Reset a NAS volume.

Resets the volume, which can help recover from error states.

Parameters:

key (str) – Volume $key (40-character hex string).

Returns:

Task information dict or None.

Return type:

dict[str, Any] | None

Example

>>> client.nas_volumes.reset(vol.key)

snapshots(key)

Get a snapshot manager for a specific volume.

Parameters:

key (str) – Volume $key (40-character hex string).

Returns:

NASVolumeSnapshotManager for the volume.

Return type:

NASVolumeSnapshotManager

Example

>>> # List snapshots for a volume
>>> for snap in client.nas_volumes.snapshots(vol.key).list():
...     print(snap.name)

>>> # Create a snapshot
>>> snap = client.nas_volumes.snapshots(vol.key).create("pre-update")

files(key, *, name=None)

Get a file manager for browsing a volume’s files.

Parameters:

• key (str) – Volume $key (40-character hex string).

• name (str | None) – Optional volume name for display purposes.

Returns:

NASVolumeFileManager for browsing the volume.

Return type:

NASVolumeFileManager

Example

>>> # Browse root directory
>>> for f in client.nas_volumes.files(vol.key).list():
...     print(f"{f.name}: {f.size_display}")

>>> # Browse a subdirectory
>>> files = client.nas_volumes.files(vol.key).list("/documents")

>>> # Get a specific file
>>> file = client.nas_volumes.files(vol.key).get("/report.pdf")

class pyvergeos.resources.nas_volumes.NASVolumeSnapshotManager

Bases: ResourceManager[NASVolumeSnapshot]

Manager for NAS volume snapshot operations.

This manager can be used either standalone or scoped to a specific volume.

Example

>>> # List all snapshots (standalone)
>>> for snap in client.nas_volume_snapshots.list():
...     print(f"{snap.name} ({snap.volume_name})")

>>> # List snapshots for a specific volume
>>> for snap in client.nas_volumes.snapshots(vol.key).list():
...     print(snap.name)

>>> # Create a snapshot
>>> snap = client.nas_volumes.snapshots(vol.key).create("pre-update")

__init__(client, *, volume_key=None)

Parameters:

• client (VergeClient)

• volume_key (str | None)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, volume=None, **filter_kwargs)

List volume snapshots with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• volume (str | None) – Filter by volume (key or name). Ignored if manager is scoped.

• **filter_kwargs (Any) – Shorthand filter arguments (name, etc.).

Returns:

List of NASVolumeSnapshot objects.

Return type:

list[NASVolumeSnapshot]

Example

>>> # List all snapshots
>>> snapshots = client.nas_volume_snapshots.list()

>>> # List snapshots for a specific volume by name
>>> snapshots = client.nas_volume_snapshots.list(volume="FileShare")

>>> # List snapshots by name pattern
>>> snapshots = client.nas_volume_snapshots.list(name="Daily-*")

get(key=None, *, name=None, fields=None)

Get a single volume snapshot by key or name.

Parameters:

• key (int | None) – Snapshot $key (row ID).

• name (str | None) – Snapshot name (requires scoped manager or unique name).

• fields (list[str] | None) – List of fields to return.

Returns:

NASVolumeSnapshot object.

Raises:

• NotFoundError – If snapshot not found.

• ValueError – If no identifier provided.

Return type:

NASVolumeSnapshot

Example

>>> # Get by key
>>> snap = client.nas_volume_snapshots.get(1)

>>> # Get by name (scoped to volume)
>>> snap = client.nas_volumes.snapshots(1).get(name="pre-update")

create(name, *, volume=None, description=None, expires_days=3, never_expires=False, quiesce=False)

Create a new volume snapshot.

Parameters:

• name (str) – Snapshot name.

• volume (str | None) – Volume key (40-char hex string, required if manager is not scoped).

• description (str | None) – Snapshot description.

• expires_days (int) – Days until expiration (default 3).

• never_expires (bool) – If True, snapshot never expires.

• quiesce (bool) – If True, freeze I/O during snapshot for consistency.

Returns:

Created NASVolumeSnapshot object.

Raises:

ValueError – If volume not specified and manager not scoped.

Return type:

NASVolumeSnapshot

Example

>>> # Create with scoped manager
>>> snap = client.nas_volumes.snapshots(vol.key).create("pre-update")

>>> # Create with standalone manager
>>> snap = client.nas_volume_snapshots.create("backup", volume=vol.key)

>>> # Create a permanent quiesced snapshot
>>> snap = client.nas_volumes.snapshots(vol.key).create(
...     "before-migration",
...     never_expires=True,
...     quiesce=True
... )

delete(key)

Delete a volume snapshot.

This operation cannot be undone.

Parameters:

key (int) – Snapshot $key (ID).

Return type:

None

Example

>>> client.nas_volume_snapshots.delete(1)

NAS Volume Browser

NAS volume file browser resources.

class pyvergeos.resources.nas_volume_browser.NASVolumeFile

Bases: dict[str, Any]

NAS volume file/directory entry.

Represents a file or directory within a NAS volume. This is a read-only data object returned by the volume browser.

name

File or directory name.

type

Entry type (‘file’ or ‘directory’).

size

Size in bytes.

date

Modification timestamp (Unix).

n_name

Normalized name (lowercase).

__init__(data)

Initialize with data dict.

Parameters:

data (dict[str, Any])

Return type:

None

__getattr__(name)

Allow attribute-style access to dict items.

Parameters:

name (str)

Return type:

Any

property name: str

Get the file/directory name.

property is_directory: bool

Check if this entry is a directory.

property is_file: bool

Check if this entry is a file.

property size: int

Get the size in bytes.

property size_display: str

Get human-readable size.

property modified: datetime | None

Get the modification time as datetime.

property full_path: str

Get the full path of this entry.

property volume_key: str | None

Get the volume key this entry belongs to.

class pyvergeos.resources.nas_volume_browser.NASVolumeFileManager

Bases: object

Manager for browsing NAS volume files.

This manager provides methods to browse files and directories within a NAS volume. It uses the asynchronous volume_browser API.

Note

The NAS service VM must be running to browse volumes. The volume must be mounted (enabled).

Example

>>> # Browse root directory
>>> files = client.nas_volumes.files(vol.key).list()
>>> for f in files:
...     print(f"{f.name}: {f.size_display}")

>>> # Browse a subdirectory
>>> files = client.nas_volumes.files(vol.key).list("/documents")

>>> # Get a specific file
>>> file = client.nas_volumes.files(vol.key).get("/documents/report.pdf")

__init__(client, *, volume_key, volume_name=None)

Initialize the file manager.

Parameters:

• client (VergeClient) – VergeClient instance.

• volume_key (str) – Volume key (40-character hex string).

• volume_name (str | None) – Optional volume name for display purposes.

Return type:

None

list(path='/', *, limit=1000, offset=None, extensions='', sort='', timeout=30)

List files and directories at the specified path.

Parameters:

• path (str) – Directory path to list. Use “/” for root.

• limit (int) – Maximum number of entries to return (default 1000).

• offset (int | None) – Pagination offset.

• extensions (str) – Filter by file extensions (comma-separated).

• sort (str) – Sort field.

• timeout (int) – Maximum seconds to wait for results (default 30).

Returns:

List of NASVolumeFile objects.

Raises:

• APIError – If the browse operation fails.

• VergeTimeoutError – If the operation times out.

Return type:

list[NASVolumeFile]

Example

>>> # List root directory
>>> files = client.nas_volumes.files(vol.key).list()

>>> # List a subdirectory
>>> files = client.nas_volumes.files(vol.key).list("/documents")

>>> # Filter by extension
>>> pdfs = client.nas_volumes.files(vol.key).list("/documents", extensions="pdf")

get(path, *, timeout=30)

Get information about a specific file or directory.

Parameters:

• path (str) – Full path to the file or directory.

• timeout (int) – Maximum seconds to wait for results.

Returns:

NASVolumeFile object.

Raises:

• NotFoundError – If the file/directory is not found.

• APIError – If the browse operation fails.

Return type:

NASVolumeFile

Example

>>> file = client.nas_volumes.files(vol.key).get("/documents/report.pdf")
>>> print(f"{file.name}: {file.size_display}")

NAS Volume Syncs

NAS volume sync resources.

class pyvergeos.resources.nas_volume_syncs.NASVolumeSync

Bases: ResourceObject

NAS volume sync resource object.

Represents a volume synchronization job that copies data between NAS volumes.

key

The sync job unique identifier ($key).

id

The sync job ID (same as key).

name

Sync job name.

description

Sync job description.

enabled

Whether the sync is enabled.

service

Parent NAS service key.

source_volume

Source volume key.

source_path

Starting directory in source volume.

destination_volume

Destination volume key.

destination_path

Destination directory path.

include

File/directory patterns to include.

exclude

File/directory patterns to exclude.

sync_method

Sync method (rsync or ysync).

destination_delete

How to handle deleted files.

workers

Number of simultaneous workers.

preserve_ACLs

Preserve access control lists.

preserve_permissions

Preserve file permissions.

preserve_owner

Preserve file owner.

preserve_groups

Preserve file groups.

preserve_mod_time

Preserve modification time.

preserve_xattrs

Preserve extended attributes.

copy_symlinks

Copy symbolic links.

fsfreeze

Freeze filesystem before snapshot.

status

Current sync status.

syncing

Whether sync is currently running.

files_transferred

Number of files transferred.

bytes_transferred

Number of bytes transferred.

transfer_rate

Current transfer rate.

sync_errors

Number of sync errors.

start_time

Sync start time.

stop_time

Sync stop time.

created

Creation timestamp.

modified

Last modified timestamp.

property key: str

Resource primary key ($key).

Note

Volume sync keys are typically strings.

Raises:

ValueError – If resource has no $key (not yet persisted).

refresh()

Refresh resource data from API.

Returns:

Updated NASVolumeSync object.

Return type:

NASVolumeSync

save(**kwargs)

Save changes to resource.

Parameters:

**kwargs (Any) – Fields to update.

Returns:

Updated NASVolumeSync object.

Return type:

NASVolumeSync

delete()

Delete this sync job.

Return type:

None

start()

Start this sync job.

Return type:

None

stop()

Stop this sync job.

Return type:

None

property is_syncing: bool

Check if the sync is currently running.

property service_key: int | None

Get the parent NAS service key.

property source_volume_key: str | None

Get the source volume key.

property destination_volume_key: str | None

Get the destination volume key.

property sync_method_display: str

Get human-readable sync method.

property destination_delete_display: str

Get human-readable destination delete mode.

property status_display: str

Get human-readable status.

class pyvergeos.resources.nas_volume_syncs.NASVolumeSyncManager

Bases: ResourceManager[NASVolumeSync]

Manager for NAS volume sync operations.

Volume syncs copy data between NAS volumes on a schedule or on-demand.

Example

>>> # List all volume syncs
>>> for sync in client.volume_syncs.list():
...     print(f"{sync.name}: {sync.status_display}")

>>> # Get a specific sync
>>> sync = client.volume_syncs.get(name="DailyBackup")

>>> # Create a sync job
>>> sync = client.volume_syncs.create(
...     name="DailyBackup",
...     service=1,
...     source_volume="8f73...",
...     destination_volume="9a84...",
... )

>>> # Start a sync
>>> client.volume_syncs.start(sync.key)

>>> # Stop a running sync
>>> client.volume_syncs.stop(sync.key)

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, service=None, enabled=None, **filter_kwargs)

List volume sync jobs with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• service (int | str | None) – Filter by NAS service (key or name).

• enabled (bool | None) – Filter by enabled state.

• **filter_kwargs (Any) – Shorthand filter arguments (name, etc.).

Returns:

List of NASVolumeSync objects.

Return type:

list[NASVolumeSync]

Example

>>> # List all syncs
>>> syncs = client.volume_syncs.list()

>>> # List syncs for a specific NAS service
>>> syncs = client.volume_syncs.list(service="NAS01")

>>> # List enabled syncs only
>>> syncs = client.volume_syncs.list(enabled=True)

>>> # Filter by name
>>> syncs = client.volume_syncs.list(name="DailyBackup")

get(key=None, *, name=None, service=None, fields=None)

Get a single volume sync by key or name.

Parameters:

• key (str | None) – Sync job key (ID).

• name (str | None) – Sync job name.

• service (int | str | None) – NAS service (key or name) to narrow name search.

• fields (list[str] | None) – List of fields to return.

Returns:

NASVolumeSync object.

Raises:

• NotFoundError – If sync not found.

• ValueError – If no identifier provided.

Return type:

NASVolumeSync

Example

>>> # Get by key
>>> sync = client.volume_syncs.get("abc123")

>>> # Get by name
>>> sync = client.volume_syncs.get(name="DailyBackup")

>>> # Get by name within specific NAS service
>>> sync = client.volume_syncs.get(name="DailyBackup", service="NAS01")

create(name, service, source_volume, destination_volume, *, source_path=None, destination_path=None, description=None, include=None, exclude=None, sync_method='ysync', destination_delete='never', workers=4, preserve_acls=True, preserve_permissions=True, preserve_owner=True, preserve_groups=True, preserve_mod_time=True, preserve_xattrs=True, copy_symlinks=True, freeze_filesystem=False, enabled=True)

Create a new volume sync job.

Parameters:

• name (str) – Name for the sync job.

• service (int | str) – NAS service (key or name) to create the sync on.

• source_volume (str) – Source volume key (40-char hex string).

• destination_volume (str) – Destination volume key (40-char hex string).

• source_path (str | None) – Starting directory in source volume.

• destination_path (str | None) – Destination directory path.

• description (str | None) – Sync job description.

• include (list[str] | None) – List of file/directory patterns to include.

• exclude (list[str] | None) – List of file/directory patterns to exclude.

• sync_method (str) – Sync method - “rsync” or “ysync” (default: “ysync”).

• destination_delete (str) – How to handle deleted files. Valid values: “never”, “delete”, “delete-before”, “delete-during”, “delete-delay”, “delete-after”

• workers (int) – Number of simultaneous workers (1-128, default: 4).

• preserve_acls (bool) – Preserve access control lists (default: True).

• preserve_permissions (bool) – Preserve file permissions (default: True).

• preserve_owner (bool) – Preserve file owner (default: True).

• preserve_groups (bool) – Preserve file groups (default: True).

• preserve_mod_time (bool) – Preserve modification time (default: True).

• preserve_xattrs (bool) – Preserve extended attributes (default: True).

• copy_symlinks (bool) – Copy symbolic links (default: True).

• freeze_filesystem (bool) – Freeze filesystem before snapshot (default: False).

• enabled (bool) – Enable the sync job (default: True).

Returns:

Created NASVolumeSync object.

Raises:

ValueError – If NAS service not found.

Return type:

NASVolumeSync

Example

>>> # Create a basic sync job
>>> sync = client.volume_syncs.create(
...     name="DailyBackup",
...     service="NAS01",
...     source_volume="8f73f8bcc9c9f1aaba32f733bfc295acaf548554",
...     destination_volume="9a84e7add1d2c3b4a5e6f7890123456789abcdef",
... )

>>> # Create with options
>>> sync = client.volume_syncs.create(
...     name="SelectiveSync",
...     service=1,
...     source_volume=source_vol.key,
...     destination_volume=dest_vol.key,
...     include=["*.docx", "*.xlsx"],
...     exclude=["temp/*"],
...     workers=8,
... )

update(key, *, description=None, source_path=None, destination_path=None, include=None, exclude=None, sync_method=None, destination_delete=None, workers=None, preserve_acls=None, preserve_permissions=None, preserve_owner=None, preserve_groups=None, preserve_mod_time=None, preserve_xattrs=None, copy_symlinks=None, freeze_filesystem=None, enabled=None)

Update a volume sync job.

Parameters:

• key (str) – Sync job key (ID).

• description (str | None) – New description.

• source_path (str | None) – New source path.

• destination_path (str | None) – New destination path.

• include (list[str] | None) – New list of include patterns.

• exclude (list[str] | None) – New list of exclude patterns.

• sync_method (str | None) – New sync method (“rsync” or “ysync”).

• destination_delete (str | None) – New delete mode.

• workers (int | None) – New number of workers (1-128).

• preserve_acls (bool | None) – Preserve access control lists.

• preserve_permissions (bool | None) – Preserve file permissions.

• preserve_owner (bool | None) – Preserve file owner.

• preserve_groups (bool | None) – Preserve file groups.

• preserve_mod_time (bool | None) – Preserve modification time.

• preserve_xattrs (bool | None) – Preserve extended attributes.

• copy_symlinks (bool | None) – Copy symbolic links.

• freeze_filesystem (bool | None) – Freeze filesystem before snapshot.

• enabled (bool | None) – Enable or disable the sync job.

Returns:

Updated NASVolumeSync object.

Return type:

NASVolumeSync

Example

>>> # Update workers
>>> client.volume_syncs.update(sync.key, workers=8)

>>> # Disable a sync
>>> client.volume_syncs.update(sync.key, enabled=False)

delete(key)

Delete a volume sync job.

This operation cannot be undone. Running syncs should be stopped first.

Parameters:

key (str) – Sync job key (ID).

Return type:

None

Example

>>> client.volume_syncs.delete(sync.key)

enable(key)

Enable a volume sync job.

Parameters:

key (str) – Sync job key (ID).

Returns:

Updated NASVolumeSync object.

Return type:

NASVolumeSync

Example

>>> client.volume_syncs.enable(sync.key)

disable(key)

Disable a volume sync job.

Parameters:

key (str) – Sync job key (ID).

Returns:

Updated NASVolumeSync object.

Return type:

NASVolumeSync

Example

>>> client.volume_syncs.disable(sync.key)

start(key)

Start a volume sync job.

Initiates the synchronization process to copy data from source to destination volume.

Parameters:

key (str) – Sync job key (ID).

Return type:

None

Example

>>> client.volume_syncs.start(sync.key)

stop(key)

Stop a running volume sync job.

Aborts the synchronization process at its current progress point.

Parameters:

key (str) – Sync job key (ID).

Return type:

None

Example

>>> client.volume_syncs.stop(sync.key)

CIFS Shares

NAS CIFS/SMB share resources.

class pyvergeos.resources.nas_cifs.NASCIFSShare

Bases: ResourceObject

NAS CIFS/SMB share resource object.

Represents a CIFS (SMB) file share on a NAS volume.

Note

Share keys are 40-character hex strings, not integers like most other VergeOS resources.

key

The share unique identifier ($key) - 40-char hex string.

id

The share ID (same as $key).

name

Share name.

description

Share description.

volume_key

Parent volume key.

volume_name

Parent volume name.

share_path

Path within the volume being shared.

comment

Short comment (visible to clients).

enabled

Whether the share is enabled.

browseable

Whether the share is visible in network browsing.

read_only

Whether the share is read-only.

guest_ok

Whether guest access is allowed.

guest_only

Only guest connections are permitted.

force_user

All file operations performed as this user.

force_group

Default primary group for connecting users.

valid_users

List of users allowed to connect.

valid_groups

List of groups allowed to connect.

admin_users

List of users with admin privileges.

admin_groups

List of groups with admin privileges.

allowed_hosts

List of allowed hosts.

denied_hosts

List of denied hosts.

shadow_copy_enabled

Whether shadow copy (Previous Versions) is enabled.

created

Creation timestamp.

modified

Last modified timestamp.

property key: str

Resource primary key ($key) - 40-character hex string.

Raises:

ValueError – If resource has no $key (not yet persisted).

refresh()

Refresh resource data from API.

Returns:

Updated NASCIFSShare object.

Return type:

NASCIFSShare

save(**kwargs)

Save changes to resource.

Parameters:

**kwargs (Any) – Fields to update.

Returns:

Updated NASCIFSShare object.

Return type:

NASCIFSShare

delete()

Delete this share.

Return type:

None

property volume_key: str | None

Get the parent volume key (40-char hex string).

property volume_name: str | None

Get the parent volume name.

property is_enabled: bool

Check if the share is enabled.

property is_read_only: bool

Check if the share is read-only.

property allows_guests: bool

Check if guest access is allowed.

property shadow_copy_enabled: bool

Check if shadow copy is enabled.

class pyvergeos.resources.nas_cifs.NASCIFSShareManager

Bases: ResourceManager[NASCIFSShare]

Manager for NAS CIFS/SMB share operations.

CIFS shares provide Windows-compatible file sharing (SMB protocol).

Example

>>> # List all CIFS shares
>>> for share in client.cifs_shares.list():
...     print(f"{share.name} on {share.volume_name}")

>>> # Get shares for a specific volume
>>> shares = client.cifs_shares.list(volume="FileShare")

>>> # Create a share
>>> share = client.cifs_shares.create(
...     name="shared",
...     volume="FileShare",
...     guest_ok=True
... )

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, volume=None, enabled=None, **filter_kwargs)

List CIFS shares with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• volume (str | int | None) – Filter by volume (key or name).

• enabled (bool | None) – Filter by enabled state.

• **filter_kwargs (Any) – Shorthand filter arguments (name, etc.).

Returns:

List of NASCIFSShare objects.

Return type:

list[NASCIFSShare]

Example

>>> # List all CIFS shares
>>> shares = client.cifs_shares.list()

>>> # List shares on a specific volume
>>> shares = client.cifs_shares.list(volume="FileShare")

>>> # List enabled shares only
>>> shares = client.cifs_shares.list(enabled=True)

get(key=None, *, name=None, volume=None, fields=None)

Get a single CIFS share by key or name.

Parameters:

• key (str | None) – Share $key (40-character hex string).

• name (str | None) – Share name (requires volume if not unique).

• volume (str | int | None) – Volume key or name (helps disambiguate by name).

• fields (list[str] | None) – List of fields to return.

Returns:

NASCIFSShare object.

Raises:

• NotFoundError – If share not found.

• ValueError – If no identifier provided.

Return type:

NASCIFSShare

Example

>>> # Get by key
>>> share = client.cifs_shares.get("abc123...")

>>> # Get by name on a volume
>>> share = client.cifs_shares.get(name="shared", volume="FileShare")

create(name, volume, *, share_path=None, description=None, comment=None, browseable=True, read_only=False, guest_ok=False, guest_only=False, force_user=None, force_group=None, valid_users=None, valid_groups=None, admin_users=None, admin_groups=None, allowed_hosts=None, denied_hosts=None, shadow_copy=False, enabled=True)

Create a new CIFS share.

Parameters:

• name (str) – Share name (alphanumeric with underscores/hyphens).

• volume (str | int) – Volume key or name to create the share on.

• share_path (str | None) – Path within the volume to share (empty = entire volume).

• description (str | None) – Share description.

• comment (str | None) – Short comment visible to clients.

• browseable (bool) – Make visible in network browsing (default True).

• read_only (bool) – Create as read-only share.

• guest_ok (bool) – Allow guest access.

• guest_only (bool) – Only allow guest connections.

• force_user (str | None) – All operations performed as this user.

• force_group (str | None) – Default primary group for connecting users.

• valid_users (list[str] | None) – List of usernames allowed to connect.

• valid_groups (list[str] | None) – List of group names allowed to connect.

• admin_users (list[str] | None) – List of users with admin privileges.

• admin_groups (list[str] | None) – List of groups with admin privileges.

• allowed_hosts (list[str] | None) – List of allowed hosts (IPs, hostnames, subnets).

• denied_hosts (list[str] | None) – List of denied hosts.

• shadow_copy (bool) – Enable Previous Versions support.

• enabled (bool) – Enable the share (default True).

Returns:

Created NASCIFSShare object.

Raises:

ValueError – If volume not found.

Return type:

NASCIFSShare

Example

>>> # Create a basic share
>>> share = client.cifs_shares.create("shared", "FileShare")

>>> # Create with guest access
>>> share = client.cifs_shares.create(
...     "public", "FileShare",
...     share_path="/public",
...     guest_ok=True
... )

>>> # Create with restricted access
>>> share = client.cifs_shares.create(
...     "secure", "FileShare",
...     valid_users=["admin", "manager"]
... )

update(key, *, description=None, comment=None, enabled=None, browseable=None, read_only=None, guest_ok=None, guest_only=None, force_user=None, force_group=None, valid_users=None, valid_groups=None, admin_users=None, admin_groups=None, allowed_hosts=None, denied_hosts=None, shadow_copy=None)

Update a CIFS share.

Parameters:

• key (str) – Share $key (40-character hex string).

• description (str | None) – New description.

• comment (str | None) – New comment.

• enabled (bool | None) – Enable or disable the share.

• browseable (bool | None) – Show or hide in network browsing.

• read_only (bool | None) – Set read-only or read-write.

• guest_ok (bool | None) – Allow or disallow guest access.

• guest_only (bool | None) – Restrict to guest-only access.

• force_user (str | None) – Set force user (empty string to clear).

• force_group (str | None) – Set force group (empty string to clear).

• valid_users (list[str] | None) – Set valid users (empty list to clear).

• valid_groups (list[str] | None) – Set valid groups (empty list to clear).

• admin_users (list[str] | None) – Set admin users (empty list to clear).

• admin_groups (list[str] | None) – Set admin groups (empty list to clear).

• allowed_hosts (list[str] | None) – Set allowed hosts (empty list to clear).

• denied_hosts (list[str] | None) – Set denied hosts (empty list to clear).

• shadow_copy (bool | None) – Enable or disable shadow copy.

Returns:

Updated NASCIFSShare object.

Return type:

NASCIFSShare

Example

>>> # Make share read-only
>>> client.cifs_shares.update(share.key, read_only=True)

>>> # Update access controls
>>> client.cifs_shares.update(
...     share.key,
...     valid_users=["admin", "manager", "backup"]
... )

delete(key)

Delete a CIFS share.

This removes the share but does not delete the underlying data on the volume.

Parameters:

key (str) – Share $key (40-character hex string).

Return type:

None

Example

>>> client.cifs_shares.delete(share.key)

enable(key)

Enable a CIFS share.

Parameters:

key (str) – Share $key (40-character hex string).

Returns:

Updated NASCIFSShare object.

Return type:

NASCIFSShare

disable(key)

Disable a CIFS share.

Parameters:

key (str) – Share $key (40-character hex string).

Returns:

Updated NASCIFSShare object.

Return type:

NASCIFSShare

NFS Shares

NAS NFS share resources.

class pyvergeos.resources.nas_nfs.NASNFSShare

Bases: ResourceObject

NAS NFS share resource object.

Represents an NFS file share on a NAS volume.

Note

Share keys are 40-character hex strings, not integers like most other VergeOS resources.

key

The share unique identifier ($key) - 40-char hex string.

id

The share ID (same as $key).

name

Share name.

description

Share description.

volume_key

Parent volume key.

volume_name

Parent volume name.

share_path

Path within the volume being shared.

allowed_hosts

Comma-delimited list of allowed hosts.

allow_all

Whether all hosts are allowed.

data_access

Read-only (ro) or read-write (rw).

squash

User/group squashing mode.

filesystem_id

Filesystem ID for the export.

anonymous_uid

User ID for anonymous/squashed users.

anonymous_gid

Group ID for anonymous/squashed users.

no_acl

Whether ACLs are disabled.

insecure

Whether non-privileged ports are allowed.

async_mode

Whether async mode is enabled.

enabled

Whether the share is enabled.

created

Creation timestamp.

modified

Last modified timestamp.

property key: str

Resource primary key ($key) - 40-character hex string.

Raises:

ValueError – If resource has no $key (not yet persisted).

refresh()

Refresh resource data from API.

Returns:

Updated NASNFSShare object.

Return type:

NASNFSShare

save(**kwargs)

Save changes to resource.

Parameters:

**kwargs (Any) – Fields to update.

Returns:

Updated NASNFSShare object.

Return type:

NASNFSShare

delete()

Delete this share.

Return type:

None

property volume_key: str | None

Get the parent volume key (40-char hex string).

property volume_name: str | None

Get the parent volume name.

property is_enabled: bool

Check if the share is enabled.

property is_read_only: bool

Check if the share is read-only.

property allows_all_hosts: bool

Check if all hosts are allowed.

property squash_display: str

Get human-readable squash mode.

property data_access_display: str

Get human-readable data access mode.

class pyvergeos.resources.nas_nfs.NASNFSShareManager

Bases: ResourceManager[NASNFSShare]

Manager for NAS NFS share operations.

NFS shares provide Unix/Linux-compatible file sharing.

Example

>>> # List all NFS shares
>>> for share in client.nfs_shares.list():
...     print(f"{share.name} on {share.volume_name}")

>>> # Get shares for a specific volume
>>> shares = client.nfs_shares.list(volume="FileShare")

>>> # Create a share
>>> share = client.nfs_shares.create(
...     name="exports",
...     volume="FileShare",
...     allowed_hosts="192.168.1.0/24"
... )

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, volume=None, enabled=None, **filter_kwargs)

List NFS shares with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• volume (str | int | None) – Filter by volume (key or name).

• enabled (bool | None) – Filter by enabled state.

• **filter_kwargs (Any) – Shorthand filter arguments (name, etc.).

Returns:

List of NASNFSShare objects.

Return type:

list[NASNFSShare]

Example

>>> # List all NFS shares
>>> shares = client.nfs_shares.list()

>>> # List shares on a specific volume
>>> shares = client.nfs_shares.list(volume="FileShare")

>>> # List enabled shares only
>>> shares = client.nfs_shares.list(enabled=True)

get(key=None, *, name=None, volume=None, fields=None)

Get a single NFS share by key or name.

Parameters:

• key (str | None) – Share $key (40-character hex string).

• name (str | None) – Share name (requires volume if not unique).

• volume (str | int | None) – Volume key or name (helps disambiguate by name).

• fields (list[str] | None) – List of fields to return.

Returns:

NASNFSShare object.

Raises:

• NotFoundError – If share not found.

• ValueError – If no identifier provided.

Return type:

NASNFSShare

Example

>>> # Get by key
>>> share = client.nfs_shares.get("abc123...")

>>> # Get by name on a volume
>>> share = client.nfs_shares.get(name="exports", volume="FileShare")

create(name, volume, *, share_path=None, description=None, allowed_hosts=None, allow_all=False, data_access='ro', squash='root_squash', anonymous_uid=None, anonymous_gid=None, async_mode=False, insecure=False, no_acl=False, filesystem_id=None, enabled=True)

Create a new NFS share.

Parameters:

• name (str) – Share name (alphanumeric with underscores/hyphens).

• volume (str | int) – Volume key or name to create the share on.

• share_path (str | None) – Path within the volume to share (empty = entire volume).

• description (str | None) – Share description.

• allowed_hosts (str | None) – Comma-delimited list of allowed hosts (FQDNs, IPs, networks, NIS netgroups). Required unless allow_all is True.

• allow_all (bool) – Allow connections from any host.

• data_access (str) – Data access mode - “ro” (read-only) or “rw” (read-write).

• squash (str) – User/group squashing - “root_squash”, “all_squash”, “no_root_squash”.

• anonymous_uid (str | None) – User ID for anonymous/squashed users (default 65534).

• anonymous_gid (str | None) – Group ID for anonymous/squashed users (default 65534).

• async_mode (bool) – Enable async mode for better performance (risk of data loss).

• insecure (bool) – Allow connections from non-privileged ports.

• no_acl (bool) – Disable access control lists.

• filesystem_id (str | None) – Filesystem ID for the export (must be unique per volume).

• enabled (bool) – Enable the share (default True).

Returns:

Created NASNFSShare object.

Raises:

ValueError – If volume not found or if neither allowed_hosts nor allow_all is specified.

Return type:

NASNFSShare

Example

>>> # Create a share for a subnet
>>> share = client.nfs_shares.create(
...     "exports", "FileShare",
...     allowed_hosts="192.168.1.0/24"
... )

>>> # Create a read-write share for specific hosts
>>> share = client.nfs_shares.create(
...     "data", "FileShare",
...     allowed_hosts="10.0.0.5,10.0.0.6",
...     data_access="rw",
...     squash="no_root_squash"
... )

>>> # Create a share accessible from anywhere
>>> share = client.nfs_shares.create(
...     "public", "FileShare",
...     allow_all=True,
...     data_access="ro"
... )

update(key, *, description=None, allowed_hosts=None, allow_all=None, data_access=None, squash=None, anonymous_uid=None, anonymous_gid=None, async_mode=None, insecure=None, no_acl=None, filesystem_id=None, enabled=None)

Update an NFS share.

Parameters:

• key (str) – Share $key (40-character hex string).

• description (str | None) – New description.

• allowed_hosts (str | None) – New allowed hosts list.

• allow_all (bool | None) – Allow all hosts.

• data_access (str | None) – Data access mode - “ro” or “rw”.

• squash (str | None) – Squash mode - “root_squash”, “all_squash”, “no_root_squash”.

• anonymous_uid (str | None) – Anonymous user ID.

• anonymous_gid (str | None) – Anonymous group ID.

• async_mode (bool | None) – Enable or disable async mode.

• insecure (bool | None) – Allow or disallow non-privileged ports.

• no_acl (bool | None) – Enable or disable ACL support.

• filesystem_id (str | None) – New filesystem ID.

• enabled (bool | None) – Enable or disable the share.

Returns:

Updated NASNFSShare object.

Return type:

NASNFSShare

Example

>>> # Change to read-write
>>> client.nfs_shares.update(share.key, data_access="rw")

>>> # Update allowed hosts
>>> client.nfs_shares.update(
...     share.key,
...     allowed_hosts="192.168.1.0/24,10.0.0.0/8"
... )

delete(key)

Delete an NFS share.

This removes the share but does not delete the underlying data on the volume.

Parameters:

key (str) – Share $key (40-character hex string).

Return type:

None

Example

>>> client.nfs_shares.delete(share.key)

enable(key)

Enable an NFS share.

Parameters:

key (str) – Share $key (40-character hex string).

Returns:

Updated NASNFSShare object.

Return type:

NASNFSShare

disable(key)

Disable an NFS share.

Parameters:

key (str) – Share $key (40-character hex string).

Returns:

Updated NASNFSShare object.

Return type:

NASNFSShare

NAS Users

NAS local user resources.

class pyvergeos.resources.nas_users.NASUser

Bases: ResourceObject

NAS local user resource object.

Represents a local user account on a NAS service for CIFS/SMB authentication. Local users are used when not using Active Directory integration.

Note

User keys are 40-character hex strings, not integers like most other VergeOS resources.

key

The user unique identifier ($key) - 40-char hex string.

name

Username.

displayname

Display name.

description

User description.

enabled

Whether the account is enabled.

service_key

Parent NAS service key.

service_name

Parent NAS service name.

home_share_key

Home share key.

home_share_name

Home share name.

home_drive

Home drive letter (e.g., “H”).

status

Account status (online=Enabled, offline=Disabled, error=Error).

status_info

Additional status information.

user_sid

Windows SID.

group_sid

Group SID.

user_id

Unix UID.

group_id

Unix GID.

created

Creation timestamp.

property key: str

Resource primary key ($key) - 40-character hex string.

Raises:

ValueError – If resource has no $key (not yet persisted).

refresh()

Refresh resource data from API.

Returns:

Updated NASUser object.

Return type:

NASUser

save(**kwargs)

Save changes to resource.

Parameters:

**kwargs (Any) – Fields to update.

Returns:

Updated NASUser object.

Return type:

NASUser

delete()

Delete this user.

Return type:

None

property service_key: int | None

Get the parent NAS service key.

property service_name: str | None

Get the parent NAS service name.

property home_share_key: int | None

Get the home share key.

property home_share_name: str | None

Get the home share name.

property home_drive: str | None

Get the home drive letter.

property displayname: str | None

Get the display name.

property is_enabled: bool

Check if the user account is enabled.

property status: str | None

Get the user status (online=Enabled, offline=Disabled, error=Error).

property status_display: str

Get the user status as a human-readable string.

property user_sid: str | None

Get the Windows SID.

property group_sid: str | None

Get the group SID.

property user_id: int | None

Get the Unix UID.

property group_id: int | None

Get the Unix GID.

class pyvergeos.resources.nas_users.NASUserManager

Bases: ResourceManager[NASUser]

Manager for NAS local user operations.

NAS local users are used for CIFS/SMB authentication when not using Active Directory integration.

Example

>>> # List all users on a NAS service
>>> for user in client.nas_users.list(service=1):
...     print(f"{user.name}: {'Enabled' if user.is_enabled else 'Disabled'}")

>>> # Create a user
>>> user = client.nas_users.create(
...     service=1,
...     name="backup",
...     password="SecurePass123!"
... )

>>> # Enable/disable users
>>> client.nas_users.disable(user.key)
>>> client.nas_users.enable(user.key)

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, service=None, enabled=None, **filter_kwargs)

List NAS local users with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• service (int | str | None) – Filter by NAS service (key or name).

• enabled (bool | None) – Filter by enabled state.

• **filter_kwargs (Any) – Shorthand filter arguments (name, etc.).

Returns:

List of NASUser objects.

Return type:

list[NASUser]

Example

>>> # List all users for a NAS service
>>> users = client.nas_users.list(service=1)

>>> # List enabled users only
>>> users = client.nas_users.list(service=1, enabled=True)

>>> # List by name pattern
>>> users = client.nas_users.list(service=1, name="backup")

get(key=None, *, name=None, service=None, fields=None)

Get a single NAS user by key or name.

Parameters:

• key (str | None) – User $key (40-character hex string).

• name (str | None) – Username (requires service if not unique).

• service (int | str | None) – NAS service key or name (required when looking up by name).

• fields (list[str] | None) – List of fields to return.

Returns:

NASUser object.

Raises:

• NotFoundError – If user not found.

• ValueError – If no identifier provided or name without service.

Return type:

NASUser

Example

>>> # Get by key
>>> user = client.nas_users.get("abc123...")

>>> # Get by name on a service
>>> user = client.nas_users.get(name="backup", service=1)

create(service, name, password, *, displayname=None, description=None, home_share=None, home_drive=None, enabled=True)

Create a new NAS local user.

Parameters:

• service (int | str) – NAS service key or name.

• name (str) – Username (1-32 chars, starts with letter, alphanumeric/underscore/hyphen).

• password (str) – User password.

• displayname (str | None) – Display name for the user.

• description (str | None) – User description.

• home_share (str | int | None) – Home share key or name (CIFS share on this NAS service).

• home_drive (str | None) – Home drive letter (single letter A-Z, e.g., “H”).

• enabled (bool) – Enable the user account (default True).

Returns:

Created NASUser object.

Raises:

ValueError – If service not found.

Return type:

NASUser

Example

>>> # Create a basic user
>>> user = client.nas_users.create(
...     service=1,
...     name="backup",
...     password="SecurePass123!"
... )

>>> # Create with home share
>>> user = client.nas_users.create(
...     service=1,
...     name="admin",
...     password="AdminPass!",
...     displayname="Administrator",
...     home_share="AdminDocs",
...     home_drive="H"
... )

update(key, *, password=None, displayname=None, description=None, home_share=None, home_drive=None, enabled=None)

Update a NAS user.

Parameters:

• key (str) – User $key (40-character hex string).

• password (str | None) – New password.

• displayname (str | None) – New display name.

• description (str | None) – New description.

• home_share (str | int | None) – New home share key or name (empty string to clear).

• home_drive (str | None) – New home drive letter (empty string to clear).

• enabled (bool | None) – Enable or disable the user.

Returns:

Updated NASUser object.

Return type:

NASUser

Example

>>> # Change password
>>> client.nas_users.update(user.key, password="NewPass123!")

>>> # Update display name
>>> client.nas_users.update(user.key, displayname="Backup User")

>>> # Disable user
>>> client.nas_users.update(user.key, enabled=False)

delete(key)

Delete a NAS user.

This permanently removes the user account.

Parameters:

key (str) – User $key (40-character hex string).

Return type:

None

Example

>>> client.nas_users.delete(user.key)

enable(key)

Enable a NAS user account.

Parameters:

key (str) – User $key (40-character hex string).

Returns:

Updated NASUser object.

Return type:

NASUser

Example

>>> client.nas_users.enable(user.key)

disable(key)

Disable a NAS user account.

Parameters:

key (str) – User $key (40-character hex string).

Returns:

Updated NASUser object.

Return type:

NASUser

Example

>>> client.nas_users.disable(user.key)

Storage Tiers

Storage tier management for VergeOS vSAN.

class pyvergeos.resources.storage_tiers.StorageTier

Bases: ResourceObject

Represents a storage tier in the VergeOS vSAN.

Storage tiers represent different performance levels of storage. Tier 1 is typically the fastest (SSD/NVMe), while higher tiers may be slower but offer more capacity.

property tier: int

Tier number (1-5).

property description: str

Tier description.

property capacity_bytes: int

Total capacity in bytes.

property capacity_gb: float

Total capacity in GB.

property used_bytes: int

Used space in bytes.

property used_gb: float

Used space in GB.

property free_bytes: int

Free space in bytes.

property free_gb: float

Free space in GB.

property allocated_bytes: int

Allocated space in bytes.

property allocated_gb: float

Allocated space in GB.

property used_inflated_bytes: int

Used space before deduplication in bytes.

property used_inflated_gb: float

Used space before deduplication in GB.

property used_percent: float

Percentage of capacity used.

property dedupe_ratio: float

Deduplication ratio (e.g., 1.5 = 50% savings).

property dedupe_savings_percent: float

Deduplication savings as percentage.

property modified: datetime | None

Last modification timestamp.

property stats: dict[str, Any]

Raw stats dictionary.

property read_ops: int

Current read operations per second.

property write_ops: int

Current write operations per second.

property read_bytes_per_sec: int

Current read throughput in bytes per second.

property write_bytes_per_sec: int

Current write throughput in bytes per second.

property total_reads: int

Total read operations.

property total_writes: int

Total write operations.

property total_read_bytes: int

Total bytes read.

property total_write_bytes: int

Total bytes written.

class pyvergeos.resources.storage_tiers.StorageTierManager

Bases: ResourceManager[StorageTier]

Manages storage tier information in VergeOS.

Storage tiers represent different levels of storage performance in the vSAN. Each tier has its own capacity, usage statistics, and I/O metrics.

Example

>>> # List all storage tiers
>>> for tier in client.storage_tiers.list():
...     print(f"Tier {tier.tier}: {tier.used_percent}% used")

>>> # Get a specific tier
>>> tier1 = client.storage_tiers.get(tier=1)
>>> print(f"Free: {tier1.free_gb} GB")

>>> # Check tiers with high usage
>>> high_usage = [t for t in client.storage_tiers.list() if t.used_percent > 80]

list(filter=None, fields=None, include_stats=True, **filter_kwargs)

List all storage tiers.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• include_stats (bool) – Include I/O statistics (default True).

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of StorageTier objects.

Return type:

list[StorageTier]

Example

>>> tiers = client.storage_tiers.list()
>>> for tier in tiers:
...     print(f"Tier {tier.tier}: {tier.used_percent}% used, "
...           f"{tier.read_ops} IOPS read, {tier.write_ops} IOPS write")

get(key=None, *, tier=None, fields=None)

Get a storage tier by key or tier number.

Parameters:

• key (int | None) – Storage tier $key.

• tier (int | None) – Tier number (1-5) - alternative to key.

• fields (list[str] | None) – List of fields to return.

Returns:

StorageTier object.

Raises:

• NotFoundError – If tier not found.

• ValueError – If neither key nor tier provided.

Return type:

StorageTier

Example

>>> tier1 = client.storage_tiers.get(tier=1)
>>> print(f"Tier 1 has {tier1.free_gb} GB free")

get_summary()

Get a summary of all storage tiers.

Returns:

Dictionary with aggregate storage information.

Return type:

dict[str, Any]

Example

>>> summary = client.storage_tiers.get_summary()
>>> print(f"Total: {summary['total_capacity_gb']} GB")
>>> print(f"Used: {summary['total_used_gb']} GB ({summary['used_percent']}%)")

Recipes & Catalogs

VM Recipes

Automated VM provisioning templates.

VM Recipe resources for VergeOS provisioning system.

VM recipes are customizable templates for deploying virtual machines. They consist of a golden image (base VM) and configurable options via questions that allow users to customize each deployment.

Key concepts:

• Recipe: A template based on a golden image VM, stored in a catalog

• Instance: A VM created from a recipe (remains linked until detached)

• Questions: Configuration inputs grouped into sections

• Sections: Logical groups like “Virtual Machine”, “Network”, “Drives”

Common question variable names:

• YB_CPU_CORES: Number of CPU cores

• YB_RAM: RAM amount in MB

• YB_HOSTNAME: VM hostname

• YB_IP_ADDR_TYPE: IP type (dhcp/static)

• YB_NIC_ETH0: Network selection for eth0

• YB_DRIVE_OS_SIZE: OS disk size in bytes

• YB_USER: Username for guest OS

• YB_PASSWORD: Password for guest OS

• OS_DL_URL: Cloud image download URL (for cloud-init images)

Question types:

• string, number, boolean, password, list, hidden

• ram, cluster, network, disk_size, row_selection, text_area

• database_create, database_edit, database_find (for API automation)

Example

>>> # List available recipes
>>> for recipe in client.vm_recipes.list(downloaded=True):
...     print(f"{recipe.name} (v{recipe.version})")

>>> # Deploy a recipe
>>> recipe = client.vm_recipes.get(name="Ubuntu Server 22.04")
>>> instance = recipe.deploy("my-ubuntu", answers={
...     "YB_CPU_CORES": 4,
...     "YB_RAM": 8192,
...     "YB_HOSTNAME": "my-ubuntu-server",
...     "YB_IP_ADDR_TYPE": "dhcp",
... })

class pyvergeos.resources.vm_recipes.VmRecipe

Bases: ResourceObject

VM Recipe resource object.

Represents a VM recipe template that can be deployed to create new VMs.

Note

Recipe keys are 40-character hex strings, not integers like most other VergeOS resources.

key

The recipe unique identifier ($key) - 40-char hex string.

id

The recipe ID (same as $key).

name

Recipe name.

description

Recipe description.

version

Recipe version string.

build

Recipe build number.

icon

Bootstrap icon name for UI display.

catalog

Parent catalog key.

status

Recipe status row key.

downloaded

Whether the recipe has been downloaded.

update_available

Whether an update is available.

needs_republish

Whether the recipe needs republishing.

vm

Associated VM key (for local recipes).

vm_snapshot

Associated VM snapshot key.

creator

Username who created the recipe.

property key: str

Resource primary key ($key) - 40-character hex string.

Raises:

ValueError – If resource has no $key (not yet persisted).

refresh()

Refresh resource data from API.

Returns:

Updated VmRecipe object.

Return type:

VmRecipe

save(**kwargs)

Save changes to resource.

Parameters:

**kwargs (Any) – Fields to update.

Returns:

Updated VmRecipe object.

Return type:

VmRecipe

delete()

Delete this recipe.

Return type:

None

property is_downloaded: bool

Check if the recipe has been downloaded.

property has_update: bool

Check if an update is available.

property status_info: str | None

Get the recipe status string.

property catalog_key: str | None

Get the parent catalog key.

property vm_key: int | None

Get the associated VM key.

property instance_count: int

Get the number of deployed instances.

property instances: VmRecipeInstanceManager

Get an instance manager scoped to this recipe.

Returns:

VmRecipeInstanceManager for this recipe.

property logs: VmRecipeLogManager

Get a log manager scoped to this recipe.

Returns:

VmRecipeLogManager for this recipe.

download()

Download this recipe from the catalog repository.

Returns:

Task information dict or None.

Return type:

dict[str, Any] | None

deploy(name, *, answers=None, auto_update=False)

Deploy this recipe to create a new VM.

Parameters:

• name (str) – Name for the new VM.

• answers (dict[str, Any] | None) – Recipe question answers.

• auto_update (bool) – Auto-update when recipe updates are available.

Returns:

Created VmRecipeInstance object.

Return type:

VmRecipeInstance

class pyvergeos.resources.vm_recipes.VmRecipeInstance

Bases: ResourceObject

VM Recipe instance resource object.

Represents a deployed instance of a VM recipe.

key

Instance $key (integer row ID).

recipe

Recipe key that this instance was deployed from.

vm

VM key that was created.

name

Instance/VM name.

version

Recipe version when deployed.

build

Recipe build when deployed.

answers

Recipe question answers used.

auto_update

Whether auto-update is enabled.

created

Creation timestamp.

modified

Last modified timestamp.

property recipe_key: str | None

Get the recipe key this instance was deployed from.

property vm_key: int | None

Get the VM key that was created.

property is_auto_update: bool

Check if auto-update is enabled.

class pyvergeos.resources.vm_recipes.VmRecipeLog

Bases: ResourceObject

VM Recipe log entry resource object.

Represents a log entry from recipe operations.

key

Log entry $key (integer row ID).

vm_recipe

Recipe key.

level

Log level (message, warning, error, critical, etc.).

text

Log message text.

timestamp

Log timestamp (microseconds).

user

User who triggered the log.

property recipe_key: str | None

Get the recipe key.

property is_error: bool

Check if this is an error log entry.

property is_warning: bool

Check if this is a warning log entry.

class pyvergeos.resources.vm_recipes.VmRecipeManager

Bases: ResourceManager[VmRecipe]

Manager for VM recipe operations.

VM recipes are templates for automated VM provisioning.

Example

>>> # List all recipes
>>> for recipe in client.vm_recipes.list():
...     print(f"{recipe.name}: {recipe.version}")

>>> # Get a specific recipe
>>> recipe = client.vm_recipes.get(name="Ubuntu Server")

>>> # Deploy a recipe
>>> instance = recipe.deploy("my-ubuntu", answers={"ram": 4096})

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, catalog=None, downloaded=None, **filter_kwargs)

List VM recipes with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• catalog (str | int | None) – Filter by catalog (key or name).

• downloaded (bool | None) – Filter by downloaded state.

• **filter_kwargs (Any) – Shorthand filter arguments (name, etc.).

Returns:

List of VmRecipe objects.

Return type:

list[VmRecipe]

Example

>>> # List all recipes
>>> recipes = client.vm_recipes.list()

>>> # List downloaded recipes only
>>> downloaded = client.vm_recipes.list(downloaded=True)

>>> # Filter by name
>>> ubuntu = client.vm_recipes.list(name="Ubuntu*")

get(key=None, *, name=None, fields=None)

Get a single VM recipe by key or name.

Parameters:

• key (str | None) – Recipe $key (40-character hex string).

• name (str | None) – Recipe name.

• fields (list[str] | None) – List of fields to return.

Returns:

VmRecipe object.

Raises:

• NotFoundError – If recipe not found.

• ValueError – If no identifier provided.

Return type:

VmRecipe

Example

>>> # Get by key
>>> recipe = client.vm_recipes.get("8f73f8bcc9c9f1aaba32f733bfc295acaf548554")

>>> # Get by name
>>> recipe = client.vm_recipes.get(name="Ubuntu Server")

update(key, *, name=None, description=None, icon=None, version=None)

Update a VM recipe.

Parameters:

• key (str) – Recipe $key (40-character hex string).

• name (str | None) – New name.

• description (str | None) – New description.

• icon (str | None) – New icon name.

• version (str | None) – New version string.

Returns:

Updated VmRecipe object.

Return type:

VmRecipe

Example

>>> client.vm_recipes.update(recipe.key, description="Updated description")

delete(key)

Delete a VM recipe.

This operation is destructive and cannot be undone.

Parameters:

key (str) – Recipe $key (40-character hex string).

Raises:

NotFoundError – If recipe not found.

Return type:

None

Example

>>> client.vm_recipes.delete(recipe.key)

download(key)

Download a recipe from the catalog repository.

Parameters:

key (str) – Recipe $key (40-character hex string).

Returns:

Task information dict or None.

Return type:

dict[str, Any] | None

Example

>>> client.vm_recipes.download(recipe.key)

deploy(key, name, *, answers=None, auto_update=False)

Deploy a recipe to create a new VM.

Parameters:

• key (str) – Recipe $key (40-character hex string).

• name (str) – Name for the new VM.

• answers (dict[str, Any] | None) – Recipe question answers.

• auto_update (bool) – Auto-update when recipe updates are available.

Returns:

Created VmRecipeInstance object.

Return type:

VmRecipeInstance

Example

>>> instance = client.vm_recipes.deploy(
...     recipe.key,
...     "my-vm",
...     answers={"ram": 4096, "cpu_cores": 2}
... )

instances(key)

Get an instance manager scoped to a specific recipe.

Parameters:

key (str) – Recipe $key (40-character hex string).

Returns:

VmRecipeInstanceManager for the recipe.

Return type:

VmRecipeInstanceManager

logs(key)

Get a log manager scoped to a specific recipe.

Parameters:

key (str) – Recipe $key (40-character hex string).

Returns:

VmRecipeLogManager for the recipe.

Return type:

VmRecipeLogManager

class pyvergeos.resources.vm_recipes.VmRecipeInstanceManager

Bases: ResourceManager[VmRecipeInstance]

Manager for VM recipe instance operations.

Recipe instances represent deployed VMs created from recipes.

Example

>>> # List all instances
>>> for inst in client.vm_recipe_instances.list():
...     print(f"{inst.name}: {inst.version}")

>>> # List instances for a specific recipe
>>> for inst in client.vm_recipes.get(name="Ubuntu").instances.list():
...     print(inst.name)

__init__(client, *, recipe_key=None)

Parameters:

• client (VergeClient)

• recipe_key (str | None)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, recipe=None, **filter_kwargs)

List recipe instances with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• recipe (str | None) – Filter by recipe key. Ignored if manager is scoped.

• **filter_kwargs (Any) – Shorthand filter arguments (name, etc.).

Returns:

List of VmRecipeInstance objects.

Return type:

list[VmRecipeInstance]

get(key=None, *, name=None, fields=None)

Get a single recipe instance by key or name.

Parameters:

• key (int | None) – Instance $key (row ID).

• name (str | None) – Instance/VM name.

• fields (list[str] | None) – List of fields to return.

Returns:

VmRecipeInstance object.

Raises:

• NotFoundError – If instance not found.

• ValueError – If no identifier provided.

Return type:

VmRecipeInstance

create(recipe, name, *, answers=None, auto_update=False)

Create a new recipe instance (deploy a recipe).

Parameters:

• recipe (str) – Recipe $key (40-character hex string).

• name (str) – Name for the new VM.

• answers (dict[str, Any] | None) – Recipe question answers.

• auto_update (bool) – Auto-update when recipe updates are available.

Returns:

Created VmRecipeInstance object.

Return type:

VmRecipeInstance

Example

>>> instance = client.vm_recipe_instances.create(
...     recipe="8f73f8bcc9c9...",
...     name="my-vm",
...     answers={"ram": 4096}
... )

update(key, *, auto_update=None, answers=None)

Update a recipe instance.

Parameters:

• key (int) – Instance $key (row ID).

• auto_update (bool | None) – Enable or disable auto-update.

• answers (dict[str, Any] | None) – Update recipe answers.

Returns:

Updated VmRecipeInstance object.

Return type:

VmRecipeInstance

delete(key)

Delete a recipe instance.

Note: This typically does NOT delete the created VM.

Parameters:

key (int) – Instance $key (row ID).

Return type:

None

class pyvergeos.resources.vm_recipes.VmRecipeLogManager

Bases: ResourceManager[VmRecipeLog]

Manager for VM recipe log operations.

Example

>>> # List all recipe logs
>>> for log in client.vm_recipe_logs.list():
...     print(f"{log.level}: {log.text}")

>>> # List logs for a specific recipe
>>> for log in client.vm_recipes.get(name="Ubuntu").logs.list():
...     print(f"{log.level}: {log.text}")

__init__(client, *, recipe_key=None)

Parameters:

• client (VergeClient)

• recipe_key (str | None)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, vm_recipe=None, level=None, **filter_kwargs)

List recipe logs with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• vm_recipe (str | None) – Filter by recipe key. Ignored if manager is scoped.

• level (str | None) – Filter by log level.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of VmRecipeLog objects.

Return type:

list[VmRecipeLog]

get(key=None, *, fields=None)

Get a single log entry by key.

Parameters:

• key (int | None) – Log entry $key (row ID).

• fields (list[str] | None) – List of fields to return.

Returns:

VmRecipeLog object.

Raises:

• NotFoundError – If log entry not found.

• ValueError – If key not provided.

Return type:

VmRecipeLog

list_errors(limit=None)

List error and critical log entries.

Parameters:

limit (int | None) – Maximum number of results.

Returns:

List of error/critical log entries.

Return type:

list[VmRecipeLog]

list_warnings(limit=None)

List warning log entries.

Parameters:

limit (int | None) – Maximum number of results.

Returns:

List of warning log entries.

Return type:

list[VmRecipeLog]

Tenant Recipes

Automated tenant provisioning templates.

Tenant Recipe resources for VergeOS provisioning system.

Tenant recipes enable automated deployment of complete virtual data centers. A tenant recipe includes everything needed to spawn a functional tenant instance: tenant settings, networking configuration, VMs, and automation for tasks like creating passwords, establishing hostnames, registering DNS entries, etc.

Key concepts:

• Recipe: A template based on a powered-off tenant, stored in a catalog

• Instance: A tenant created from a recipe (remains linked until detached)

• Questions: Configuration inputs for customizing each tenant deployment

• Sections: Logical groups organizing questions on the deployment form

Benefits:

• Rapid deployment of entire tenants with consistent configurations

• Golden images for compliance and standardization

• Reduced manual setup time and human error

• Customizable via questions for tenant-specific settings

Database Context:

Tenant recipe questions can interact with either the parent system database or the newly-created tenant’s database using the database_context field. This enables powerful automation like creating users, registering DNS, etc.

Example

>>> # List available tenant recipes
>>> for recipe in client.tenant_recipes.list(downloaded=True):
...     print(f"{recipe.name} (v{recipe.version})")

>>> # Deploy a tenant recipe
>>> recipe = client.tenant_recipes.get(name="30-Day Trial (POC)")
>>> instance = recipe.deploy("customer-tenant", answers={
...     "TENANT_NAME": "Acme Corp",
...     "ADMIN_USER": "admin",
...     "ADMIN_PASSWORD": "secure-password",
... })

class pyvergeos.resources.tenant_recipes.TenantRecipe

Bases: ResourceObject

Tenant Recipe resource object.

Represents a tenant recipe template that can be deployed to create new tenants.

Note

Recipe keys are 40-character hex strings, not integers like most other VergeOS resources.

key

The recipe unique identifier ($key) - 40-char hex string.

id

The recipe ID (same as $key).

name

Recipe name.

description

Recipe description.

version

Recipe version string.

build

Recipe build number.

icon

Bootstrap icon name for UI display.

catalog

Parent catalog key.

status

Recipe status row key.

downloaded

Whether the recipe has been downloaded.

update_available

Whether an update is available.

needs_republish

Whether the recipe needs republishing.

tenant

Associated tenant key (for local recipes).

tenant_snapshot

Associated tenant snapshot key.

preserve_certs

Whether to preserve SSL certificates during deployment.

creator

Username who created the recipe.

property key: str

Resource primary key ($key) - 40-character hex string.

Raises:

ValueError – If resource has no $key (not yet persisted).

refresh()

Refresh resource data from API.

Returns:

Updated TenantRecipe object.

Return type:

TenantRecipe

save(**kwargs)

Save changes to resource.

Parameters:

**kwargs (Any) – Fields to update.

Returns:

Updated TenantRecipe object.

Return type:

TenantRecipe

delete()

Delete this recipe.

Return type:

None

property is_downloaded: bool

Check if the recipe has been downloaded.

property has_update: bool

Check if an update is available.

property status_info: str | None

Get the recipe status string.

property catalog_key: str | None

Get the parent catalog key.

property tenant_key: int | None

Get the associated tenant key.

property instance_count: int

Get the number of deployed instances.

property instances: TenantRecipeInstanceManager

Get an instance manager scoped to this recipe.

Returns:

TenantRecipeInstanceManager for this recipe.

property logs: TenantRecipeLogManager

Get a log manager scoped to this recipe.

Returns:

TenantRecipeLogManager for this recipe.

download()

Download this recipe from the catalog repository.

Returns:

Task information dict or None.

Return type:

dict[str, Any] | None

deploy(name, *, answers=None)

Deploy this recipe to create a new tenant.

Parameters:

• name (str) – Name for the new tenant.

• answers (dict[str, Any] | None) – Recipe question answers.

Returns:

Created TenantRecipeInstance object.

Return type:

TenantRecipeInstance

class pyvergeos.resources.tenant_recipes.TenantRecipeInstance

Bases: ResourceObject

Tenant Recipe instance resource object.

Represents a deployed instance of a tenant recipe.

key

Instance $key (integer row ID).

recipe

Recipe key that this instance was deployed from.

tenant

Tenant key that was created.

name

Instance/tenant name.

version

Recipe version when deployed.

build

Recipe build when deployed.

answers

Recipe question answers used.

created

Creation timestamp.

modified

Last modified timestamp.

property recipe_key: str | None

Get the recipe key this instance was deployed from.

property tenant_key: int | None

Get the tenant key that was created.

class pyvergeos.resources.tenant_recipes.TenantRecipeLog

Bases: ResourceObject

Tenant Recipe log entry resource object.

Represents a log entry from recipe operations.

key

Log entry $key (integer row ID).

tenant_recipe

Recipe key.

level

Log level (message, warning, error, critical, etc.).

text

Log message text.

timestamp

Log timestamp (microseconds).

user

User who triggered the log.

property recipe_key: str | None

Get the recipe key.

property is_error: bool

Check if this is an error log entry.

property is_warning: bool

Check if this is a warning log entry.

class pyvergeos.resources.tenant_recipes.TenantRecipeManager

Bases: ResourceManager[TenantRecipe]

Manager for tenant recipe operations.

Tenant recipes are templates for automated tenant provisioning.

Example

>>> # List all recipes
>>> for recipe in client.tenant_recipes.list():
...     print(f"{recipe.name}: {recipe.version}")

>>> # Get a specific recipe
>>> recipe = client.tenant_recipes.get(name="Standard Tenant")

>>> # Deploy a recipe
>>> instance = recipe.deploy("my-tenant", answers={"storage_gb": 500})

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, catalog=None, downloaded=None, **filter_kwargs)

List tenant recipes with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• catalog (str | int | None) – Filter by catalog (key or name).

• downloaded (bool | None) – Filter by downloaded state.

• **filter_kwargs (Any) – Shorthand filter arguments (name, etc.).

Returns:

List of TenantRecipe objects.

Return type:

list[TenantRecipe]

Example

>>> # List all recipes
>>> recipes = client.tenant_recipes.list()

>>> # List downloaded recipes only
>>> downloaded = client.tenant_recipes.list(downloaded=True)

>>> # Filter by name
>>> standard = client.tenant_recipes.list(name="Standard*")

get(key=None, *, name=None, fields=None)

Get a single tenant recipe by key or name.

Parameters:

• key (str | None) – Recipe $key (40-character hex string).

• name (str | None) – Recipe name.

• fields (list[str] | None) – List of fields to return.

Returns:

TenantRecipe object.

Raises:

• NotFoundError – If recipe not found.

• ValueError – If no identifier provided.

Return type:

TenantRecipe

Example

>>> # Get by key
>>> recipe = client.tenant_recipes.get("8f73f8bcc9c9f1aaba32f733bfc295acaf548554")

>>> # Get by name
>>> recipe = client.tenant_recipes.get(name="Standard Tenant")

update(key, *, name=None, description=None, icon=None, version=None, preserve_certs=None)

Update a tenant recipe.

Parameters:

• key (str) – Recipe $key (40-character hex string).

• name (str | None) – New name.

• description (str | None) – New description.

• icon (str | None) – New icon name.

• version (str | None) – New version string.

• preserve_certs (bool | None) – Whether to preserve SSL certs during deployment.

Returns:

Updated TenantRecipe object.

Return type:

TenantRecipe

Example

>>> client.tenant_recipes.update(recipe.key, description="Updated description")

delete(key)

Delete a tenant recipe.

This operation is destructive and cannot be undone.

Parameters:

key (str) – Recipe $key (40-character hex string).

Raises:

NotFoundError – If recipe not found.

Return type:

None

Example

>>> client.tenant_recipes.delete(recipe.key)

download(key)

Download a recipe from the catalog repository.

Parameters:

key (str) – Recipe $key (40-character hex string).

Returns:

Task information dict or None.

Return type:

dict[str, Any] | None

Example

>>> client.tenant_recipes.download(recipe.key)

deploy(key, name, *, answers=None)

Deploy a recipe to create a new tenant.

Parameters:

• key (str) – Recipe $key (40-character hex string).

• name (str) – Name for the new tenant.

• answers (dict[str, Any] | None) – Recipe question answers.

Returns:

Created TenantRecipeInstance object.

Return type:

TenantRecipeInstance

Example

>>> instance = client.tenant_recipes.deploy(
...     recipe.key,
...     "my-tenant",
...     answers={"storage_gb": 500, "cpu_cores": 4}
... )

instances(key)

Get an instance manager scoped to a specific recipe.

Parameters:

key (str) – Recipe $key (40-character hex string).

Returns:

TenantRecipeInstanceManager for the recipe.

Return type:

TenantRecipeInstanceManager

logs(key)

Get a log manager scoped to a specific recipe.

Parameters:

key (str) – Recipe $key (40-character hex string).

Returns:

TenantRecipeLogManager for the recipe.

Return type:

TenantRecipeLogManager

class pyvergeos.resources.tenant_recipes.TenantRecipeInstanceManager

Bases: ResourceManager[TenantRecipeInstance]

Manager for tenant recipe instance operations.

Recipe instances represent deployed tenants created from recipes.

Example

>>> # List all instances
>>> for inst in client.tenant_recipe_instances.list():
...     print(f"{inst.name}: {inst.version}")

>>> # List instances for a specific recipe
>>> for inst in client.tenant_recipes.get(name="Standard").instances.list():
...     print(inst.name)

__init__(client, *, recipe_key=None)

Parameters:

• client (VergeClient)

• recipe_key (str | None)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, recipe=None, **filter_kwargs)

List recipe instances with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• recipe (str | None) – Filter by recipe key. Ignored if manager is scoped.

• **filter_kwargs (Any) – Shorthand filter arguments (name, etc.).

Returns:

List of TenantRecipeInstance objects.

Return type:

list[TenantRecipeInstance]

get(key=None, *, name=None, fields=None)

Get a single recipe instance by key or name.

Parameters:

• key (int | None) – Instance $key (row ID).

• name (str | None) – Instance/tenant name.

• fields (list[str] | None) – List of fields to return.

Returns:

TenantRecipeInstance object.

Raises:

• NotFoundError – If instance not found.

• ValueError – If no identifier provided.

Return type:

TenantRecipeInstance

create(recipe, name, *, answers=None)

Create a new recipe instance (deploy a recipe).

Parameters:

• recipe (str) – Recipe $key (40-character hex string).

• name (str) – Name for the new tenant.

• answers (dict[str, Any] | None) – Recipe question answers.

Returns:

Created TenantRecipeInstance object.

Return type:

TenantRecipeInstance

Example

>>> instance = client.tenant_recipe_instances.create(
...     recipe="8f73f8bcc9c9...",
...     name="my-tenant",
...     answers={"storage_gb": 500}
... )

delete(key)

Delete a recipe instance.

Note: This typically does NOT delete the created tenant.

Parameters:

key (int) – Instance $key (row ID).

Return type:

None

class pyvergeos.resources.tenant_recipes.TenantRecipeLogManager

Bases: ResourceManager[TenantRecipeLog]

Manager for tenant recipe log operations.

Example

>>> # List all recipe logs
>>> for log in client.tenant_recipe_logs.list():
...     print(f"{log.level}: {log.text}")

>>> # List logs for a specific recipe
>>> for log in client.tenant_recipes.get(name="Standard").logs.list():
...     print(f"{log.level}: {log.text}")

__init__(client, *, recipe_key=None)

Parameters:

• client (VergeClient)

• recipe_key (str | None)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, tenant_recipe=None, level=None, **filter_kwargs)

List recipe logs with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• tenant_recipe (str | None) – Filter by recipe key. Ignored if manager is scoped.

• level (str | None) – Filter by log level.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of TenantRecipeLog objects.

Return type:

list[TenantRecipeLog]

get(key=None, *, fields=None)

Get a single log entry by key.

Parameters:

• key (int | None) – Log entry $key (row ID).

• fields (list[str] | None) – List of fields to return.

Returns:

TenantRecipeLog object.

Raises:

• NotFoundError – If log entry not found.

• ValueError – If key not provided.

Return type:

TenantRecipeLog

list_errors(limit=None)

List error and critical log entries.

Parameters:

limit (int | None) – Maximum number of results.

Returns:

List of error/critical log entries.

Return type:

list[TenantRecipeLog]

list_warnings(limit=None)

List warning log entries.

Parameters:

limit (int | None) – Maximum number of results.

Returns:

List of warning log entries.

Return type:

list[TenantRecipeLog]

Recipe Components

Questions and sections used in recipes.

Recipe Questions and Sections shared between VM and Tenant recipes.

Recipe questions define the configuration options presented to users when deploying a recipe. Questions are organized into sections that group related options together.

Question Types:

User Input Types:

• string: Free-form text input

• number: Numeric value (supports min/max)

• boolean: Checkbox (true/false)

• password: Masked text with confirmation

• list: Dropdown selection from predefined options

• text_area: Multi-line text input

• hidden: Not shown on form (for internal values)

VergeOS-Specific Types:

• ram: RAM selector with unit conversion

• disk_size: Disk size selector

• cluster: Cluster selection dropdown

• network: Network selection dropdown

• row_selection: Database row picker

Database Automation Types:

• database_create: Create a database record

• database_edit: Modify a database record

• database_find: Look up database values

Common Sections:

• “Virtual Machine”: Core VM settings (CPU, RAM, hostname)

• “Network”: Network and IP configuration

• “Drives”: Storage/disk settings

• “Static IP Configuration”: Manual IP settings

• “User Configuration”: Guest OS user accounts

• “$database”: Database automation (hidden from users)

Variable Naming Convention:

Question names serve as variable names in recipe scripts. Common prefixes: - YB_* : VergeOS built-in variables (YB_RAM, YB_CPU_CORES, etc.) - SELECT_* : Selection/boolean options - Custom names for recipe-specific variables

Example

>>> # List questions for a recipe
>>> recipe = client.vm_recipes.get(name="Ubuntu Server")
>>> questions = client.recipe_questions.list(
...     recipe_ref=f"vm_recipes/{recipe.key}"
... )
>>> for q in questions:
...     print(f"{q.name}: {q.question_type} - {q.get('display')}")

>>> # Get sections for a recipe
>>> sections = client.recipe_sections.list(
...     recipe_ref=f"vm_recipes/{recipe.key}"
... )
>>> for s in sections:
...     print(f"{s.name}: {s.get('description', 'No description')}")

class pyvergeos.resources.recipe_common.RecipeQuestion

Bases: ResourceObject

Recipe question resource object.

Represents a configuration question for a recipe. Questions are used to gather input during recipe deployment.

key

Question $key (integer row ID).

recipe

Recipe reference (e.g., “vm_recipes/{id}” or “tenant_recipes/{id}”).

section

Section key this question belongs to.

name

Question variable name (used in recipe scripts).

display

Display label for the question.

hint

Placeholder text shown in input field.

help

Tooltip text shown on hover.

note

Note text displayed below the field.

type

Question type (string, bool, num, password, list, etc.).

default

Default value for the question.

required

Whether the question is required.

enabled

Whether the question is enabled.

readonly

Whether the question is read-only after creation.

orderid

Display order within the section.

property recipe_ref: str | None

Get the recipe reference string.

property section_key: int | None

Get the section key this question belongs to.

property question_type: str | None

Get the question type.

property is_required: bool

Check if the question is required.

property is_enabled: bool

Check if the question is enabled.

property is_readonly: bool

Check if the question is read-only.

property is_password: bool

Check if this is a password question.

property is_hidden: bool

Check if this is a hidden question.

property list_options: dict[str, Any] | None

Get list options if this is a list-type question.

class pyvergeos.resources.recipe_common.RecipeSection

Bases: ResourceObject

Recipe section resource object.

Represents a section that groups related questions in a recipe form.

key

Section $key (integer row ID).

recipe

Recipe reference (e.g., “vm_recipes/{id}” or “tenant_recipes/{id}”).

name

Section name.

description

Section description.

orderid

Display order.

property recipe_ref: str | None

Get the recipe reference string.

class pyvergeos.resources.recipe_common.RecipeQuestionManager

Bases: ResourceManager[RecipeQuestion]

Manager for recipe question operations.

Recipe questions define the configuration options available when deploying a recipe. Questions are organized into sections.

Example

>>> # List all questions for a VM recipe
>>> questions = client.recipe_questions.list(
...     recipe_ref="vm_recipes/8f73f8bcc9c9..."
... )
>>> for q in questions:
...     print(f"{q.name}: {q.question_type} (required={q.is_required})")

>>> # List questions for a specific section
>>> questions = client.recipe_questions.list(section=123)

__init__(client, *, recipe_ref=None, section_key=None)

Parameters:

• client (VergeClient)

• recipe_ref (str | None)

• section_key (int | None)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, recipe_ref=None, section=None, enabled=None, **filter_kwargs)

List recipe questions with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• recipe_ref (str | None) – Filter by recipe reference (e.g., “vm_recipes/{id}”).

• section (int | None) – Filter by section key.

• enabled (bool | None) – Filter by enabled state.

• **filter_kwargs (Any) – Shorthand filter arguments (name, type, etc.).

Returns:

List of RecipeQuestion objects.

Return type:

list[RecipeQuestion]

Example

>>> # List all questions for a VM recipe
>>> questions = client.recipe_questions.list(
...     recipe_ref="vm_recipes/8f73f8bcc9c9..."
... )

>>> # List enabled questions only
>>> enabled = client.recipe_questions.list(enabled=True)

get(key=None, *, name=None, fields=None)

Get a single recipe question by key or name.

Parameters:

• key (int | None) – Question $key (row ID).

• name (str | None) – Question name (variable name).

• fields (list[str] | None) – List of fields to return.

Returns:

RecipeQuestion object.

Raises:

• NotFoundError – If question not found.

• ValueError – If no identifier provided.

Return type:

RecipeQuestion

create(name, recipe_ref, section, question_type, *, display=None, hint=None, help_text=None, note=None, default=None, required=False, enabled=True, readonly=False, min_value=None, max_value=None, regex=None, list_options=None, table=None, fields=None, db_filter=None, database_context=None, hide_none=False, conditions=None, on_change=None, postprocess_string=None, dont_store=False)

Create a new recipe question.

Parameters:

• name (str) – Variable name for the question (alphanumeric with underscores).

• recipe_ref (str) – Recipe reference (e.g., “vm_recipes/{id}”).

• section (int) – Section key to add the question to.

• question_type (str) – Question type (string, bool, num, password, list, etc.).

• display (str | None) – Display label.

• hint (str | None) – Placeholder text.

• help_text (str | None) – Tooltip text.

• note (str | None) – Note text below field.

• default (str | None) – Default value.

• required (bool) – Whether the question is required.

• enabled (bool) – Whether the question is enabled.

• readonly (bool) – Whether the question is read-only after creation.

• min_value (int | None) – Minimum value (for numeric types).

• max_value (int | None) – Maximum value (for numeric types).

• regex (str | None) – Validation regex.

• list_options (dict[str, str] | None) – Options for list type (key: value dict).

• table (str | None) – Database table for row selection type.

• fields (str | None) – Database fields for row selection.

• db_filter (str | None) – Database filter for row selection.

• database_context (str | None) – Database context (local or tenant).

• hide_none (bool) – Hide the “None” option in lists.

• conditions (dict[str, Any] | None) – Conditional visibility rules.

• on_change (dict[str, Any] | None) – On-change actions.

• postprocess_string (str | None) – Post-processing type.

• dont_store (bool) – Don’t store the answer in the database.

Returns:

Created RecipeQuestion object.

Return type:

RecipeQuestion

Example

>>> question = client.recipe_questions.create(
...     name="vm_ram",
...     recipe_ref="vm_recipes/8f73f8bcc9c9...",
...     section=123,
...     question_type="ram",
...     display="RAM",
...     default="4096",
...     required=True
... )

update(key, *, display=None, hint=None, help_text=None, note=None, default=None, required=None, enabled=None, readonly=None, min_value=None, max_value=None, orderid=None)

Update a recipe question.

Parameters:

• key (int) – Question $key (row ID).

• display (str | None) – New display label.

• hint (str | None) – New placeholder text.

• help_text (str | None) – New tooltip text.

• note (str | None) – New note text.

• default (str | None) – New default value.

• required (bool | None) – Set required state.

• enabled (bool | None) – Set enabled state.

• readonly (bool | None) – Set readonly state.

• min_value (int | None) – New minimum value.

• max_value (int | None) – New maximum value.

• orderid (int | None) – New display order.

Returns:

Updated RecipeQuestion object.

Return type:

RecipeQuestion

delete(key)

Delete a recipe question.

Parameters:

key (int) – Question $key (row ID).

Return type:

None

class pyvergeos.resources.recipe_common.RecipeSectionManager

Bases: ResourceManager[RecipeSection]

Manager for recipe section operations.

Recipe sections organize questions into logical groups.

Example

>>> # List all sections for a VM recipe
>>> sections = client.recipe_sections.list(
...     recipe_ref="vm_recipes/8f73f8bcc9c9..."
... )
>>> for s in sections:
...     print(f"{s.name}: {s.description}")

>>> # Create a new section
>>> section = client.recipe_sections.create(
...     name="Network Settings",
...     recipe_ref="vm_recipes/8f73f8bcc9c9...",
...     description="Network configuration options"
... )

__init__(client, *, recipe_ref=None)

Parameters:

• client (VergeClient)

• recipe_ref (str | None)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, recipe_ref=None, **filter_kwargs)

List recipe sections with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• recipe_ref (str | None) – Filter by recipe reference (e.g., “vm_recipes/{id}”).

• **filter_kwargs (Any) – Shorthand filter arguments (name, etc.).

Returns:

List of RecipeSection objects.

Return type:

list[RecipeSection]

Example

>>> # List all sections for a VM recipe
>>> sections = client.recipe_sections.list(
...     recipe_ref="vm_recipes/8f73f8bcc9c9..."
... )

get(key=None, *, name=None, fields=None)

Get a single recipe section by key or name.

Parameters:

• key (int | None) – Section $key (row ID).

• name (str | None) – Section name.

• fields (list[str] | None) – List of fields to return.

Returns:

RecipeSection object.

Raises:

• NotFoundError – If section not found.

• ValueError – If no identifier provided.

Return type:

RecipeSection

create(name, recipe_ref, *, description=None)

Create a new recipe section.

Parameters:

• name (str) – Section name.

• recipe_ref (str) – Recipe reference (e.g., “vm_recipes/{id}”).

• description (str | None) – Section description.

Returns:

Created RecipeSection object.

Return type:

RecipeSection

Example

>>> section = client.recipe_sections.create(
...     name="Network Settings",
...     recipe_ref="vm_recipes/8f73f8bcc9c9...",
...     description="Network configuration options"
... )

update(key, *, name=None, description=None, orderid=None)

Update a recipe section.

Parameters:

• key (int) – Section $key (row ID).

• name (str | None) – New name.

• description (str | None) – New description.

• orderid (int | None) – New display order.

Returns:

Updated RecipeSection object.

Return type:

RecipeSection

delete(key)

Delete a recipe section.

Note: This will also delete all questions in the section.

Parameters:

key (int) – Section $key (row ID).

Return type:

None

questions(key)

Get a question manager scoped to a specific section.

Parameters:

key (int) – Section $key (row ID).

Returns:

RecipeQuestionManager for the section.

Return type:

RecipeQuestionManager

Catalogs

Recipe catalog and repository management.

Catalog management resources for VergeOS recipe repositories.

Catalogs organize recipes (VM and tenant templates) into logical groups. Catalog repositories define where catalogs are sourced from - local, remote, or from the Verge.io marketplace.

Key concepts:

• Repository: A source of catalogs (local, remote, git, Verge.io marketplace)

• Catalog: A collection of related recipes within a repository

• Status: Current state of a repository (online, refreshing, error, etc.)

Repository types:

• local: Locally created catalogs and recipes

• provider: Service provider catalogs (inherited from parent)

• remote: Remote HTTP/HTTPS URL

• remote-git: Remote Git repository

• yottabyte: Verge.io official marketplace

Example

>>> # List all catalog repositories
>>> for repo in client.catalog_repositories.list():
...     print(f"{repo.name} ({repo.type}): {repo.status_info}")

>>> # Get repository with catalogs
>>> repo = client.catalog_repositories.get(name="Verge.io Recipes")
>>> for catalog in repo.catalogs.list():
...     print(f"  {catalog.name}: {catalog.description}")

>>> # Refresh a repository to get latest recipes
>>> repo.refresh_catalogs()

>>> # View repository logs
>>> for log in repo.logs.list(limit=10):
...     print(f"{log.level}: {log.text}")

class pyvergeos.resources.catalogs.CatalogRepositoryStatus

Bases: ResourceObject

Catalog repository status resource object.

Represents the current operational status of a catalog repository.

key

Status $key (row ID).

repository

Parent repository key.

status

Current status (online, refreshing, downloading, etc.).

state

State indicator (online, offline, warning, error).

info

Additional status information text.

last_update

Timestamp of last status change.

property repository_key: int | None

Get the parent repository key.

property is_online: bool

Check if repository is online.

property is_error: bool

Check if repository is in error state.

property is_busy: bool

Check if repository is currently busy (refreshing, downloading, etc.).

class pyvergeos.resources.catalogs.CatalogRepositoryStatusManager

Bases: ResourceManager[CatalogRepositoryStatus]

Manager for catalog repository status operations.

Status objects are read-only and automatically created for each repository.

Example

>>> # Get status for all repositories
>>> for status in client.catalog_repository_status.list():
...     print(f"{status.repository_key}: {status.status}")

>>> # Get status for a specific repository
>>> status = client.catalog_repository_status.get_for_repository(1)

__init__(client, *, repository_key=None)

Parameters:

• client (VergeClient)

• repository_key (int | None)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, repository=None, **filter_kwargs)

List repository status records with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• repository (int | None) – Filter by repository key. Ignored if manager is scoped.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of CatalogRepositoryStatus objects.

Return type:

list[CatalogRepositoryStatus]

get(key=None, *, fields=None)

Get a single status record by key.

Parameters:

• key (int | None) – Status $key (row ID).

• fields (list[str] | None) – List of fields to return.

Returns:

CatalogRepositoryStatus object.

Raises:

• NotFoundError – If status not found.

• ValueError – If key not provided.

Return type:

CatalogRepositoryStatus

get_for_repository(repository_key)

Get status for a specific repository.

Parameters:

repository_key (int) – Repository $key.

Returns:

CatalogRepositoryStatus object.

Raises:

NotFoundError – If status not found.

Return type:

CatalogRepositoryStatus

class pyvergeos.resources.catalogs.CatalogRepositoryLog

Bases: ResourceObject

Catalog repository log entry resource object.

Represents a log entry from repository operations.

key

Log entry $key (row ID).

catalog_repository

Repository key.

level

Log level (message, warning, error, critical, etc.).

text

Log message text.

timestamp

Log timestamp (microseconds).

user

User who triggered the log.

property repository_key: int | None

Get the repository key.

property is_error: bool

Check if this is an error log entry.

property is_warning: bool

Check if this is a warning log entry.

class pyvergeos.resources.catalogs.CatalogRepositoryLogManager

Bases: ResourceManager[CatalogRepositoryLog]

Manager for catalog repository log operations.

Example

>>> # List all repository logs
>>> for log in client.catalog_repository_logs.list():
...     print(f"{log.level}: {log.text}")

>>> # List logs for a specific repository
>>> for log in repo.logs.list():
...     print(f"{log.level}: {log.text}")

__init__(client, *, repository_key=None)

Parameters:

• client (VergeClient)

• repository_key (int | None)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, catalog_repository=None, level=None, **filter_kwargs)

List repository logs with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• catalog_repository (int | None) – Filter by repository key. Ignored if scoped.

• level (str | None) – Filter by log level.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of CatalogRepositoryLog objects.

Return type:

list[CatalogRepositoryLog]

get(key=None, *, fields=None)

Get a single log entry by key.

Parameters:

• key (int | None) – Log entry $key (row ID).

• fields (list[str] | None) – List of fields to return.

Returns:

CatalogRepositoryLog object.

Raises:

• NotFoundError – If log entry not found.

• ValueError – If key not provided.

Return type:

CatalogRepositoryLog

list_errors(limit=None)

List error and critical log entries.

Parameters:

limit (int | None) – Maximum number of results.

Returns:

List of error/critical log entries.

Return type:

list[CatalogRepositoryLog]

list_warnings(limit=None)

List warning log entries.

Parameters:

limit (int | None) – Maximum number of results.

Returns:

List of warning log entries.

Return type:

list[CatalogRepositoryLog]

class pyvergeos.resources.catalogs.CatalogLog

Bases: ResourceObject

Catalog log entry resource object.

Represents a log entry from catalog operations.

key

Log entry $key (row ID).

catalog

Catalog key (40-char hex string).

level

Log level (message, warning, error, critical, etc.).

text

Log message text.

timestamp

Log timestamp (microseconds).

user

User who triggered the log.

property catalog_key: str | None

Get the catalog key.

property is_error: bool

Check if this is an error log entry.

property is_warning: bool

Check if this is a warning log entry.

class pyvergeos.resources.catalogs.CatalogLogManager

Bases: ResourceManager[CatalogLog]

Manager for catalog log operations.

Example

>>> # List all catalog logs
>>> for log in client.catalog_logs.list():
...     print(f"{log.level}: {log.text}")

>>> # List logs for a specific catalog
>>> for log in catalog.logs.list():
...     print(f"{log.level}: {log.text}")

__init__(client, *, catalog_key=None)

Parameters:

• client (VergeClient)

• catalog_key (str | None)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, catalog=None, level=None, **filter_kwargs)

List catalog logs with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• catalog (str | None) – Filter by catalog key. Ignored if manager is scoped.

• level (str | None) – Filter by log level.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of CatalogLog objects.

Return type:

list[CatalogLog]

get(key=None, *, fields=None)

Get a single log entry by key.

Parameters:

• key (int | None) – Log entry $key (row ID).

• fields (list[str] | None) – List of fields to return.

Returns:

CatalogLog object.

Raises:

• NotFoundError – If log entry not found.

• ValueError – If key not provided.

Return type:

CatalogLog

list_errors(limit=None)

List error and critical log entries.

Parameters:

limit (int | None) – Maximum number of results.

Returns:

List of error/critical log entries.

Return type:

list[CatalogLog]

list_warnings(limit=None)

List warning log entries.

Parameters:

limit (int | None) – Maximum number of results.

Returns:

List of warning log entries.

Return type:

list[CatalogLog]

class pyvergeos.resources.catalogs.Catalog

Bases: ResourceObject

Catalog resource object.

Represents a catalog containing recipes.

Note

Catalog keys are 40-character hex strings, not integers like most other VergeOS resources.

key

The catalog unique identifier ($key) - 40-char hex string.

id

The catalog ID (same as $key).

repository

Parent repository key.

name

Catalog name.

description

Catalog description.

publishing_scope

Scope (private, global, tenant, none).

enabled

Whether the catalog is enabled.

created

Creation timestamp.

property key: str

Resource primary key ($key) - 40-character hex string.

Raises:

ValueError – If resource has no $key (not yet persisted).

refresh()

Refresh resource data from API.

Returns:

Updated Catalog object.

Return type:

Catalog

save(**kwargs)

Save changes to resource.

Parameters:

**kwargs (Any) – Fields to update.

Returns:

Updated Catalog object.

Return type:

Catalog

delete()

Delete this catalog.

Return type:

None

property repository_key: int | None

Get the parent repository key.

property is_enabled: bool

Check if the catalog is enabled.

property scope: str

Get the publishing scope.

property logs: CatalogLogManager

Get a log manager scoped to this catalog.

Returns:

CatalogLogManager for this catalog.

class pyvergeos.resources.catalogs.CatalogManager

Bases: ResourceManager[Catalog]

Manager for catalog operations.

Catalogs organize recipes into logical groups within repositories.

Example

>>> # List all catalogs
>>> for catalog in client.catalogs.list():
...     print(f"{catalog.name}: {catalog.description}")

>>> # List catalogs in a specific repository
>>> for catalog in client.catalogs.list(repository=1):
...     print(f"{catalog.name}")

>>> # Get a specific catalog
>>> catalog = client.catalogs.get(name="VergeOS Recipes")

__init__(client, *, repository_key=None)

Parameters:

• client (VergeClient)

• repository_key (int | None)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, repository=None, enabled=None, **filter_kwargs)

List catalogs with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• repository (int | None) – Filter by repository key. Ignored if manager is scoped.

• enabled (bool | None) – Filter by enabled state.

• **filter_kwargs (Any) – Shorthand filter arguments (name, etc.).

Returns:

List of Catalog objects.

Return type:

list[Catalog]

Example

>>> # List all catalogs
>>> catalogs = client.catalogs.list()

>>> # List enabled catalogs only
>>> catalogs = client.catalogs.list(enabled=True)

>>> # Filter by name
>>> catalogs = client.catalogs.list(name="VergeOS*")

get(key=None, *, name=None, fields=None)

Get a single catalog by key or name.

Parameters:

• key (str | None) – Catalog $key (40-character hex string).

• name (str | None) – Catalog name.

• fields (list[str] | None) – List of fields to return.

Returns:

Catalog object.

Raises:

• NotFoundError – If catalog not found.

• ValueError – If no identifier provided.

Return type:

Catalog

Example

>>> # Get by key
>>> catalog = client.catalogs.get("8f73f8bcc9c9f1aaba32f733bfc295acaf548554")

>>> # Get by name
>>> catalog = client.catalogs.get(name="VergeOS Recipes")

create(name, *, repository, description=None, publishing_scope='private', enabled=True)

Create a new catalog.

Parameters:

• name (str) – Catalog name.

• repository (int) – Parent repository key.

• description (str | None) – Catalog description.

• publishing_scope (str) – Scope (private, global, tenant, none).

• enabled (bool) – Whether the catalog is enabled.

Returns:

Created Catalog object.

Return type:

Catalog

Example

>>> catalog = client.catalogs.create(
...     name="My Recipes",
...     repository=1,
...     description="Custom VM recipes",
...     publishing_scope="private"
... )

update(key, *, name=None, description=None, publishing_scope=None, enabled=None)

Update a catalog.

Parameters:

• key (str) – Catalog $key (40-character hex string).

• name (str | None) – New name.

• description (str | None) – New description.

• publishing_scope (str | None) – New scope.

• enabled (bool | None) – Enable or disable.

Returns:

Updated Catalog object.

Return type:

Catalog

Example

>>> client.catalogs.update(catalog.key, description="Updated description")

delete(key)

Delete a catalog.

This operation is destructive and cannot be undone. All recipes in the catalog will be deleted.

Parameters:

key (str) – Catalog $key (40-character hex string).

Raises:

NotFoundError – If catalog not found.

Return type:

None

Example

>>> client.catalogs.delete(catalog.key)

logs(key)

Get a log manager scoped to a specific catalog.

Parameters:

key (str) – Catalog $key (40-character hex string).

Returns:

CatalogLogManager for the catalog.

Return type:

CatalogLogManager

class pyvergeos.resources.catalogs.CatalogRepository

Bases: ResourceObject

Catalog repository resource object.

Represents a source of catalogs and recipes.

key

Repository $key (row ID).

name

Repository name.

description

Repository description.

type

Repository type (local, provider, remote, remote-git, yottabyte).

url

URL for remote repositories.

user

Username for authentication.

allow_insecure

Allow insecure SSL certificates.

auto_refresh

Automatically refresh repository.

max_tier

Maximum storage tier for downloaded recipes.

override_default_scope

Override default publishing scope.

enabled

Whether the repository is enabled.

last_refreshed

Timestamp of last refresh.

property is_enabled: bool

Check if the repository is enabled.

property is_local: bool

Check if this is a local repository.

property is_remote: bool

Check if this is a remote repository.

property repository_type: str

Get the repository type.

property status_info: str | None

Get the current status from the status object.

Note: This may require fetching status separately for full details.

property status: CatalogRepositoryStatusManager

Get a status manager scoped to this repository.

Returns:

CatalogRepositoryStatusManager for this repository.

property catalogs: CatalogManager

Get a catalog manager scoped to this repository.

Returns:

CatalogManager for this repository.

property logs: CatalogRepositoryLogManager

Get a log manager scoped to this repository.

Returns:

CatalogRepositoryLogManager for this repository.

refresh_catalogs()

Refresh this repository to fetch latest catalogs/recipes.

Returns:

Task information dict or None.

Return type:

dict[str, Any] | None

get_status()

Get the current status for this repository.

Returns:

CatalogRepositoryStatus object.

Return type:

CatalogRepositoryStatus

class pyvergeos.resources.catalogs.CatalogRepositoryManager

Bases: ResourceManager[CatalogRepository]

Manager for catalog repository operations.

Catalog repositories define where catalogs and recipes are sourced from.

Example

>>> # List all repositories
>>> for repo in client.catalog_repositories.list():
...     print(f"{repo.name} ({repo.type})")

>>> # Get the local repository
>>> local = client.catalog_repositories.get(name="Local")

>>> # Get the Verge.io marketplace
>>> marketplace = client.catalog_repositories.get(name="Verge.io Recipes")

>>> # Refresh a repository
>>> repo.refresh()

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, type=None, enabled=None, **filter_kwargs)

List repositories with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• type (str | None) – Filter by repository type.

• enabled (bool | None) – Filter by enabled state.

• **filter_kwargs (Any) – Shorthand filter arguments (name, etc.).

Returns:

List of CatalogRepository objects.

Return type:

list[CatalogRepository]

Example

>>> # List all repositories
>>> repos = client.catalog_repositories.list()

>>> # List enabled repositories only
>>> repos = client.catalog_repositories.list(enabled=True)

>>> # List remote repositories
>>> repos = client.catalog_repositories.list(type="remote")

get(key=None, *, name=None, fields=None)

Get a single repository by key or name.

Parameters:

• key (int | None) – Repository $key (row ID).

• name (str | None) – Repository name.

• fields (list[str] | None) – List of fields to return.

Returns:

CatalogRepository object.

Raises:

• NotFoundError – If repository not found.

• ValueError – If no identifier provided.

Return type:

CatalogRepository

Example

>>> # Get by key
>>> repo = client.catalog_repositories.get(1)

>>> # Get by name
>>> repo = client.catalog_repositories.get(name="Local")

create(name, *, type='local', description=None, url=None, user=None, password=None, allow_insecure=False, auto_refresh=True, max_tier='1', override_default_scope='none', enabled=True)

Create a new catalog repository.

Parameters:

• name (str) – Repository name.

• type (str) – Repository type (local, remote, remote-git, yottabyte).

• description (str | None) – Repository description.

• url (str | None) – URL for remote repositories.

• user (str | None) – Username for authentication.

• password (str | None) – Password for authentication.

• allow_insecure (bool) – Allow insecure SSL certificates.

• auto_refresh (bool) – Automatically refresh repository.

• max_tier (str) – Maximum storage tier for downloads (1-5).

• override_default_scope (str) – Override default publishing scope.

• enabled (bool) – Whether the repository is enabled.

Returns:

Created CatalogRepository object.

Return type:

CatalogRepository

Example

>>> # Create a local repository
>>> repo = client.catalog_repositories.create(
...     name="My Recipes",
...     type="local",
...     description="Custom local recipes"
... )

>>> # Create a remote repository
>>> repo = client.catalog_repositories.create(
...     name="Partner Recipes",
...     type="remote",
...     url="https://recipes.example.com/api/v4",
...     user="api-user",
...     password="api-key"
... )

update(key, *, name=None, description=None, url=None, user=None, password=None, allow_insecure=None, auto_refresh=None, max_tier=None, override_default_scope=None, enabled=None)

Update a catalog repository.

Parameters:

• key (int) – Repository $key (row ID).

• name (str | None) – New name.

• description (str | None) – New description.

• url (str | None) – New URL.

• user (str | None) – New username.

• password (str | None) – New password.

• allow_insecure (bool | None) – Allow insecure SSL certificates.

• auto_refresh (bool | None) – Automatically refresh repository.

• max_tier (str | None) – Maximum storage tier.

• override_default_scope (str | None) – Override default scope.

• enabled (bool | None) – Enable or disable.

Returns:

Updated CatalogRepository object.

Return type:

CatalogRepository

Example

>>> client.catalog_repositories.update(
...     repo.key,
...     description="Updated description",
...     auto_refresh=False
... )

delete(key)

Delete a catalog repository.

This operation is destructive and cannot be undone. All catalogs and recipes in the repository will be deleted.

Note: The default “Local” repository (key=1) cannot be deleted.

Parameters:

key (int) – Repository $key (row ID).

Raises:

• NotFoundError – If repository not found.

• APIError – If repository cannot be deleted.

Return type:

None

Example

>>> client.catalog_repositories.delete(repo.key)

refresh(key)

Refresh a repository to fetch latest catalogs/recipes.

This triggers a refresh operation that connects to the remote source and downloads any new or updated catalogs and recipes.

Parameters:

key (int) – Repository $key (row ID).

Returns:

Task information dict or None.

Return type:

dict[str, Any] | None

Example

>>> result = client.catalog_repositories.refresh(repo.key)

get_status(key)

Get the current status for a repository.

Parameters:

key (int) – Repository $key (row ID).

Returns:

CatalogRepositoryStatus object.

Return type:

CatalogRepositoryStatus

catalogs(key)

Get a catalog manager scoped to a specific repository.

Parameters:

key (int) – Repository $key (row ID).

Returns:

CatalogManager for the repository.

Return type:

CatalogManager

logs(key)

Get a log manager scoped to a specific repository.

Parameters:

key (int) – Repository $key (row ID).

Returns:

CatalogRepositoryLogManager for the repository.

Return type:

CatalogRepositoryLogManager

Task Scheduling

Tasks

Task management and waiting.

Task resource manager with wait functionality and scheduling support.

The VergeOS Task Engine enables automated operations triggered either by specific events or scheduled times. Tasks define the action to perform (e.g., power off a VM, send a notification, take a snapshot).

Task Engine Components:

• Tasks: Define the action to perform on a target object

• Schedules: Specify when and how often a task should run

• Events: Define conditions that trigger a task (e.g., user login)

• Schedule Triggers: Link tasks to schedules

• Event Triggers: Link tasks to events

Event-Based Examples:

• Power on a VM when a designated user logs into VergeOS

• Send email notification when a system update completes

• Use a webhook to notify an external system when sync errors occur

Schedule-Based Examples:

• Check for system updates every Saturday at 5:00 PM

• Power off a tenant on a specific date

• Run backup tasks daily at 2 AM

Example

>>> # List all tasks
>>> for task in client.tasks.list():
...     print(f"{task.name}: {task.status}")

>>> # Create a task to power on VMs with a specific tag
>>> task = client.tasks.create(
...     name="Power On Dev VMs",
...     owner=vm.key,
...     action="poweron",
...     description="Power on development VMs when user logs in",
... )

>>> # Link task to a schedule (e.g., Fridays at 6 PM)
>>> trigger = client.task_schedule_triggers.create(
...     task=task.key,
...     schedule=friday_schedule.key,
... )

>>> # Execute a task manually
>>> task.execute()
>>> task.wait(timeout=300)

class pyvergeos.resources.tasks.Task

Bases: ResourceObject

Task resource object.

Represents a scheduled or running task in VergeOS.

Properties:

name: Task name. description: Task description. status: Task status (‘idle’ or ‘running’). is_complete: True if task is complete (idle). is_running: True if task is currently running. is_enabled: True if task is enabled. has_error: True if task has an error status. progress: Task progress percentage (0-100). action: The action type this task performs. action_display: Human-readable action description. owner_key: Key of the owner object. owner_display: Display name of the owner. creator_key: Key of the user who created the task. creator_display: Display name of the creator. last_run: Timestamp of last run. delete_after_run: Whether task deletes itself after running. task_id: Unique task identifier (40-char hex string).

property is_complete: bool

Check if task is complete (idle).

property is_running: bool

Check if task is running.

property is_enabled: bool

Check if task is enabled.

property has_error: bool

Check if task has an error.

property progress: int

Get task progress percentage.

property owner_key: int | None

Get owner object key.

property owner_display: str

Get owner display name.

property creator_key: int | None

Get creator user key.

property creator_display: str

Get creator display name.

property task_id: str

Get unique task ID (40-char hex string).

property owner_table: str | None

Get owner table name (resource type).

property action_type: str | None

Get the action type this task performs.

property action_display_name: str | None

Get human-readable action description.

property is_delete_after_run: bool

Check if task deletes itself after running.

property is_system_created: bool

Check if task was created by system.

property trigger_count: int

Get number of schedule triggers.

property event_count: int

Get number of event triggers.

property triggers: TaskScheduleTriggerManager

Get trigger manager scoped to this task.

Returns:

TaskScheduleTriggerManager for this task’s triggers.

Example

>>> for trigger in task.triggers.list():
...     print(f"Schedule: {trigger.schedule_display}")

property events: TaskEventManager

Get event manager scoped to this task.

Returns:

TaskEventManager for this task’s events.

Example

>>> for event in task.events.list():
...     print(f"Event: {event.event_name_display}")

enable()

Enable this task.

Returns:

Updated Task object.

Return type:

Task

disable()

Disable this task.

Returns:

Updated Task object.

Return type:

Task

execute(**params)

Execute this task immediately.

Parameters:

**params (Any) – Optional parameters to pass to the task.

Returns:

Updated Task object.

Return type:

Task

wait(timeout=300, poll_interval=2, raise_on_error=True)

Wait for this task to complete.

Parameters:

• timeout (int) – Maximum wait time in seconds (0 = infinite).

• poll_interval (int) – Seconds between status checks.

• raise_on_error (bool) – Raise TaskError if task fails.

Returns:

Completed Task object.

Raises:

• TaskTimeoutError – If timeout exceeded.

• TaskError – If task fails and raise_on_error=True.

Return type:

Task

class pyvergeos.resources.tasks.TaskManager

Bases: ResourceManager[Task]

Manager for Task operations with wait functionality.

Tasks in VergeOS represent scheduled automation operations. They can be scheduled to run at specific times or triggered by events. Tasks can also be run manually.

Example

>>> # List all tasks
>>> tasks = client.tasks.list()
>>> for task in tasks:
...     print(f"{task.name}: {task.status}")

>>> # List running tasks
>>> running = client.tasks.list_running()

>>> # Wait for a task to complete
>>> task = client.tasks.wait(task_key, timeout=300)

>>> # Enable/disable a task
>>> client.tasks.enable(task_key)
>>> client.tasks.disable(task_key)

>>> # Execute a task manually
>>> task = client.tasks.execute(task_key)

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, status=None, running=None, enabled=None, name=None, **filter_kwargs)

List tasks with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• status (str | None) – Filter by status (‘running’ or ‘idle’).

• running (bool | None) – If True, filter for running tasks only.

• enabled (bool | None) – Filter by enabled state.

• name (str | None) – Filter by name (supports partial match with ‘ct’ operator).

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of Task objects.

Return type:

list[Task]

Example

>>> # All tasks
>>> tasks = client.tasks.list()

>>> # Running tasks only
>>> running = client.tasks.list(running=True)

>>> # Disabled tasks
>>> disabled = client.tasks.list(enabled=False)

>>> # Tasks by name pattern
>>> backup_tasks = client.tasks.list(name="Backup")

list_running(fields=None, limit=None)

List running tasks.

Parameters:

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

Returns:

List of running Task objects.

Return type:

list[Task]

list_idle(fields=None, limit=None)

List idle tasks.

Parameters:

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

Returns:

List of idle Task objects.

Return type:

list[Task]

list_enabled(fields=None, limit=None)

List enabled tasks.

Parameters:

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

Returns:

List of enabled Task objects.

Return type:

list[Task]

list_disabled(fields=None, limit=None)

List disabled tasks.

Parameters:

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

Returns:

List of disabled Task objects.

Return type:

list[Task]

get(key=None, *, name=None, fields=None)

Get a task by key or name.

Parameters:

• key (int | None) – Task $key (ID).

• name (str | None) – Task name.

• fields (list[str] | None) – List of fields to return.

Returns:

Task object.

Raises:

• NotFoundError – If task not found.

• ValueError – If neither key nor name provided.

Return type:

Task

wait(key, timeout=300, poll_interval=2, raise_on_error=True)

Wait for a task to complete.

Polls the task status until it becomes idle or an error occurs.

Parameters:

• key (int) – Task $key.

• timeout (int) – Maximum wait time in seconds (0 = infinite).

• poll_interval (int) – Seconds between status checks.

• raise_on_error (bool) – Raise TaskError if task fails.

Returns:

Completed Task object.

Raises:

• TaskTimeoutError – If timeout exceeded.

• TaskError – If task fails and raise_on_error=True.

Return type:

Task

Example

>>> # Wait for task with 5 minute timeout
>>> task = client.tasks.wait(task_key, timeout=300)

>>> # Wait indefinitely
>>> task = client.tasks.wait(task_key, timeout=0)

>>> # Don't raise on error, handle manually
>>> task = client.tasks.wait(task_key, raise_on_error=False)
>>> if task.has_error:
...     print(f"Task failed: {task.get('error')}")

enable(key)

Enable a task.

Enables a previously disabled task so it can run according to its schedule or event triggers.

Parameters:

key (int) – Task $key.

Returns:

Updated Task object.

Return type:

Task

Example

>>> task = client.tasks.enable(task_key)
>>> print(task.is_enabled)  # True

disable(key)

Disable a task.

Disables a task to prevent it from running. If the task is currently running, it will complete but won’t run again until re-enabled.

Parameters:

key (int) – Task $key.

Returns:

Updated Task object.

Return type:

Task

Example

>>> task = client.tasks.disable(task_key)
>>> print(task.is_enabled)  # False

execute(key, **params)

Execute a task immediately.

Triggers a task to run now, regardless of its schedule.

Parameters:

• key (int) – Task $key.

• **params (Any) – Optional parameters to pass to the task.

Returns:

Updated Task object.

Return type:

Task

Example

>>> # Run a backup task immediately
>>> task = client.tasks.execute(backup_task_key)
>>> task.wait()  # Wait for completion

cancel(key)

Cancel a running task.

Attempts to cancel a task that is currently running.

Parameters:

key (int) – Task $key.

Returns:

Updated Task object.

Return type:

Task

Note

Not all tasks support cancellation. Some tasks may complete their current operation before stopping.

create(name, owner, action, *, table, description=None, enabled=True, delete_after_run=False, settings_args=None)

Create a new task.

Parameters:

• name (str) – Task name (required).

• owner (int) – Owner resource $key (required).

• action (str) – Action type to perform (required).

• table (str) – Owner table name (required, e.g. "vms"). Combined with owner to form the "table/key" reference.

• description (str | None) – Task description.

• enabled (bool) – Whether task is enabled (default True).

• delete_after_run (bool) – Delete task after execution (default False).

• settings_args (dict[str, Any] | None) – Task settings arguments (JSON).

Returns:

Created Task object.

Return type:

Task

Example

>>> # Create a snapshot task for a VM
>>> task = client.tasks.create(
...     name="Daily Snapshot",
...     owner=vm.key,
...     action="snapshot",
...     table="vms",
...     description="Daily snapshot of production VM",
... )

>>> # Create a one-time task that deletes itself
>>> task = client.tasks.create(
...     name="One-time Backup",
...     owner=vm.key,
...     action="snapshot",
...     table="vms",
...     delete_after_run=True,
... )

update(key, *, name=None, description=None, enabled=None, delete_after_run=None, settings_args=None)

Update an existing task.

Parameters:

• key (int) – Task $key (ID).

• name (str | None) – New name.

• description (str | None) – New description.

• enabled (bool | None) – Enable/disable task.

• delete_after_run (bool | None) – Update delete after run setting.

• settings_args (dict[str, Any] | None) – New task settings.

Returns:

Updated Task object.

Return type:

Task

Example

>>> task = client.tasks.update(
...     task.key,
...     description="Updated description",
...     enabled=False,
... )

delete(key)

Delete a task.

Removes the task and its associated triggers and events.

Parameters:

key (int) – Task $key (ID).

Return type:

None

Example

>>> client.tasks.delete(task.key)

triggers(key)

Get trigger manager scoped to a specific task.

Parameters:

key (int) – Task $key (ID).

Returns:

TaskScheduleTriggerManager for the task.

Return type:

TaskScheduleTriggerManager

Example

>>> for trigger in client.tasks.triggers(task.key).list():
...     print(f"Schedule: {trigger.schedule_display}")

events(key)

Get event manager scoped to a specific task.

Parameters:

key (int) – Task $key (ID).

Returns:

TaskEventManager for the task.

Return type:

TaskEventManager

Example

>>> for event in client.tasks.events(task.key).list():
...     print(f"Event: {event.event_name_display}")

list_by_owner(owner_key, fields=None, limit=None)

List tasks for a specific owner resource.

Parameters:

• owner_key (int) – Owner resource $key.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

Returns:

List of Task objects.

Return type:

list[Task]

list_by_action(action, fields=None, limit=None)

List tasks by action type.

Parameters:

• action (str) – Action type (e.g., “snapshot”, “poweron”).

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

Returns:

List of Task objects.

Return type:

list[Task]

Task Schedules

Cron-style schedule definitions.

Task schedule resource manager for VergeOS scheduling system.

Task schedules specify when and how often tasks should run (e.g., daily, weekly, monthly). Schedules are reusable - you can create a schedule once and apply it to multiple tasks for consistent configuration management.

Supported repeat intervals:

• minute: Run every N minutes

• hour: Run every N hours

• day: Run every N days

• week: Run every N weeks (with day-of-week options)

• month: Run every N months (with day-of-month options)

• year: Run every N years

• never: Does not repeat (run once)

Schedule-Based Task Examples:

• Check for and download system updates every Saturday at 5:00 PM

• Power off a tenant on a specific date

• Disable a user account 30 days after creation

Example

>>> # Create a schedule that runs every hour
>>> schedule = client.task_schedules.create(
...     name="Hourly Backup",
...     repeat_every="hour",
...     repeat_iteration=1,
... )

>>> # Create a schedule for Fridays at 6:00 PM (64800 seconds from midnight)
>>> schedule = client.task_schedules.create(
...     name="Friday EOB",
...     repeat_every="week",
...     start_time_of_day=64800,  # 18:00 (6 PM)
...     monday=False,
...     tuesday=False,
...     wednesday=False,
...     thursday=False,
...     friday=True,
...     saturday=False,
...     sunday=False,
... )

>>> # Create a weekday-only schedule
>>> schedule = client.task_schedules.create(
...     name="Weekday Reports",
...     repeat_every="day",
...     saturday=False,
...     sunday=False,
... )

class pyvergeos.resources.task_schedules.TaskSchedule

Bases: ResourceObject

Task schedule resource object.

Represents a schedule definition for task automation.

Properties:

name: Schedule name. description: Schedule description. is_enabled: Whether the schedule is enabled. repeat_every: Repeat interval (minute, hour, day, week, month, year, never). repeat_iteration: Number of intervals between executions. start_date: Start date in YYYY-MM-DD format. end_date: Expiration date in YYYY-MM-DD HH:MM:SS format. start_time_of_day: Start time in seconds from midnight. end_time_of_day: End time in seconds from midnight. day_of_month: Day of month setting for monthly schedules. monday-sunday: Boolean flags for weekly schedules. task_key: Bound task key (if schedule is task-specific). is_system_created: Whether created by system. creator_key: Key of the user who created the schedule.

property is_enabled: bool

Check if the schedule is enabled.

property repeat_every_display: str

Get human-readable repeat interval.

property repeat_count: int

Get the repeat iteration count.

property task_key: int | None

Get the bound task key if any.

property is_system_created: bool

Check if created by system.

property creator_key: int | None

Get creator user key.

property runs_on_monday: bool

Check if schedule runs on Monday.

property runs_on_tuesday: bool

Check if schedule runs on Tuesday.

property runs_on_wednesday: bool

Check if schedule runs on Wednesday.

property runs_on_thursday: bool

Check if schedule runs on Thursday.

property runs_on_friday: bool

Check if schedule runs on Friday.

property runs_on_saturday: bool

Check if schedule runs on Saturday.

property runs_on_sunday: bool

Check if schedule runs on Sunday.

property active_days: list[str]

Get list of days when schedule is active.

property triggers: TaskScheduleTriggerManager

Get trigger manager scoped to this schedule.

Returns:

TaskScheduleTriggerManager for this schedule.

enable()

Enable this schedule.

Returns:

Updated TaskSchedule object.

Return type:

TaskSchedule

disable()

Disable this schedule.

Returns:

Updated TaskSchedule object.

Return type:

TaskSchedule

get_schedule(max_results=100, start_time=None, end_time=None)

Get upcoming scheduled execution times.

Parameters:

• max_results (int) – Maximum number of results (1-1440).

• start_time (int | None) – Start timestamp for range.

• end_time (int | None) – End timestamp for range.

Returns:

List of scheduled execution time dicts.

Return type:

list[dict[str, Any]]

class pyvergeos.resources.task_schedules.TaskScheduleManager

Bases: ResourceManager[TaskSchedule]

Manager for task schedule operations.

Task schedules define when and how often tasks should run.

Example

>>> # List all schedules
>>> for schedule in client.task_schedules.list():
...     print(f"{schedule.name}: {schedule.repeat_every_display}")

>>> # Create a daily schedule
>>> schedule = client.task_schedules.create(
...     name="Daily Backup",
...     repeat_every="day",
...     start_time_of_day=7200,  # 2 AM
... )

>>> # Enable/disable
>>> schedule.disable()
>>> schedule.enable()

>>> # Get upcoming execution times
>>> times = schedule.get_schedule(max_results=10)

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, enabled=None, repeat_every=None, name=None, **filter_kwargs)

List task schedules with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• enabled (bool | None) – Filter by enabled state.

• repeat_every (str | None) – Filter by repeat interval.

• name (str | None) – Filter by name.

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of TaskSchedule objects.

Return type:

list[TaskSchedule]

Example

>>> # All schedules
>>> schedules = client.task_schedules.list()

>>> # Enabled daily schedules
>>> daily = client.task_schedules.list(enabled=True, repeat_every="day")

>>> # Schedules by name pattern
>>> backups = client.task_schedules.list(name="Backup*")

get(key=None, *, name=None, fields=None)

Get a task schedule by key or name.

Parameters:

• key (int | None) – Schedule $key (ID).

• name (str | None) – Schedule name.

• fields (list[str] | None) – List of fields to return.

Returns:

TaskSchedule object.

Raises:

• NotFoundError – If schedule not found.

• ValueError – If neither key nor name provided.

Return type:

TaskSchedule

create(name, *, description=None, enabled=True, repeat_every='hour', repeat_iteration=1, start_date=None, end_date=None, start_time_of_day=0, end_time_of_day=86400, day_of_month='start_date', monday=True, tuesday=True, wednesday=True, thursday=True, friday=True, saturday=True, sunday=True, task=None)

Create a new task schedule.

Parameters:

• name (str) – Schedule name (required).

• description (str | None) – Schedule description.

• enabled (bool) – Whether schedule is enabled (default True).

• repeat_every (str) – Repeat interval (minute, hour, day, week, month, year, never).

• repeat_iteration (int) – Number of intervals between executions (default 1).

• start_date (str | None) – Start date in YYYY-MM-DD format.

• end_date (str | None) – Expiration date in YYYY-MM-DD HH:MM:SS format.

• start_time_of_day (int) – Start time in seconds from midnight (0-86400).

• end_time_of_day (int) – End time in seconds from midnight (0-86400).

• day_of_month (str) – Day of month for monthly schedules (first, last, 15th, start_date).

• monday-sunday – Boolean flags for weekly schedules.

• task (int | None) – Bind to specific task key.

• monday (bool)

• tuesday (bool)

• wednesday (bool)

• thursday (bool)

• friday (bool)

• saturday (bool)

• sunday (bool)

Returns:

Created TaskSchedule object.

Return type:

TaskSchedule

Example

>>> # Hourly schedule
>>> schedule = client.task_schedules.create(
...     name="Hourly Check",
...     repeat_every="hour",
...     repeat_iteration=1,
... )

>>> # Daily at 2 AM (7200 seconds from midnight)
>>> schedule = client.task_schedules.create(
...     name="Nightly Backup",
...     repeat_every="day",
...     start_time_of_day=7200,
... )

>>> # Weekly on weekdays only
>>> schedule = client.task_schedules.create(
...     name="Weekday Report",
...     repeat_every="week",
...     saturday=False,
...     sunday=False,
... )

update(key, *, name=None, description=None, enabled=None, repeat_every=None, repeat_iteration=None, start_date=None, end_date=None, start_time_of_day=None, end_time_of_day=None, day_of_month=None, monday=None, tuesday=None, wednesday=None, thursday=None, friday=None, saturday=None, sunday=None)

Update an existing task schedule.

Parameters:

• key (int) – Schedule $key (ID).

• name (str | None) – New name.

• description (str | None) – New description.

• enabled (bool | None) – Enable/disable.

• repeat_every (str | None) – New repeat interval.

• repeat_iteration (int | None) – New iteration count.

• start_date (str | None) – New start date.

• end_date (str | None) – New expiration date.

• start_time_of_day (int | None) – New start time.

• end_time_of_day (int | None) – New end time.

• day_of_month (str | None) – New day of month setting.

• monday-sunday – Day flags.

• monday (bool | None)

• tuesday (bool | None)

• wednesday (bool | None)

• thursday (bool | None)

• friday (bool | None)

• saturday (bool | None)

• sunday (bool | None)

Returns:

Updated TaskSchedule object.

Return type:

TaskSchedule

delete(key)

Delete a task schedule.

Note

Schedules with active triggers cannot be deleted.

Parameters:

key (int) – Schedule $key (ID).

Raises:

ConflictError – If schedule has active triggers.

Return type:

None

enable(key)

Enable a task schedule.

Parameters:

key (int) – Schedule $key (ID).

Returns:

Updated TaskSchedule object.

Return type:

TaskSchedule

disable(key)

Disable a task schedule.

Parameters:

key (int) – Schedule $key (ID).

Returns:

Updated TaskSchedule object.

Return type:

TaskSchedule

get_schedule(key, max_results=100, start_time=None, end_time=None)

Get upcoming scheduled execution times for a schedule.

Parameters:

• key (int) – Schedule $key (ID).

• max_results (int) – Maximum number of results (1-1440, default 100).

• start_time (int | None) – Start timestamp for range.

• end_time (int | None) – End timestamp for range.

Returns:

List of scheduled execution time dicts.

Return type:

list[dict[str, Any]]

Example

>>> # Get next 10 scheduled times
>>> times = client.task_schedules.get_schedule(schedule.key, max_results=10)
>>> for t in times:
...     print(t)

list_enabled(fields=None, limit=None)

List enabled schedules.

Parameters:

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

Returns:

List of enabled TaskSchedule objects.

Return type:

list[TaskSchedule]

list_disabled(fields=None, limit=None)

List disabled schedules.

Parameters:

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

Returns:

List of disabled TaskSchedule objects.

Return type:

list[TaskSchedule]

triggers(key)

Get trigger manager scoped to a specific schedule.

Parameters:

key (int) – Schedule $key (ID).

Returns:

TaskScheduleTriggerManager for the schedule.

Return type:

TaskScheduleTriggerManager

Task Schedule Triggers

Task schedule trigger resource manager for VergeOS scheduling system.

Task schedule triggers link tasks to schedules. When a schedule’s trigger time arrives, all tasks linked via triggers are executed.

Example

>>> # Get a task and schedule
>>> task = client.tasks.get(name="Backup Task")
>>> schedule = client.task_schedules.get(name="Nightly")

>>> # Create a trigger to link them
>>> trigger = client.task_schedule_triggers.create(
...     task=task.key,
...     schedule=schedule.key,
... )

>>> # List all triggers for a schedule
>>> for trigger in schedule.triggers.list():
...     print(f"Task: {trigger.task_display}")

class pyvergeos.resources.task_schedule_triggers.TaskScheduleTrigger

Bases: ResourceObject

Task schedule trigger resource object.

Represents a link between a task and a schedule.

Properties:

task_key: The linked task’s $key. task_display: Display name of the linked task. schedule_key: The linked schedule’s $key. schedule_display: Display name of the linked schedule. schedule_enabled: Whether the linked schedule is enabled. trigger: Timer value for the trigger.

property task_key: int | None

Get the linked task key.

property task_display: str

Get the linked task display name.

property schedule_key: int | None

Get the linked schedule key.

property schedule_display: str

Get the linked schedule display name.

property is_schedule_enabled: bool

Check if the linked schedule is enabled.

property schedule_repeat_every: str | None

Get the schedule’s repeat interval.

property schedule_start_time: int | None

Get the schedule’s start time of day in seconds.

trigger_now()

Trigger the task immediately.

Returns:

Action response dict or None.

Return type:

dict[str, Any] | None

class pyvergeos.resources.task_schedule_triggers.TaskScheduleTriggerManager

Bases: ResourceManager[TaskScheduleTrigger]

Manager for task schedule trigger operations.

Task schedule triggers link tasks to schedules for execution.

Example

>>> # List all triggers
>>> for trigger in client.task_schedule_triggers.list():
...     print(f"{trigger.task_display} -> {trigger.schedule_display}")

>>> # Create a trigger
>>> trigger = client.task_schedule_triggers.create(
...     task=task_key,
...     schedule=schedule_key,
... )

>>> # List triggers for a specific task
>>> triggers = client.task_schedule_triggers.list(task=task_key)

>>> # List triggers for a specific schedule
>>> triggers = client.task_schedule_triggers.list(schedule=schedule_key)

__init__(client, *, task_key=None, schedule_key=None)

Initialize the trigger manager.

Parameters:

• client (VergeClient) – VergeClient instance.

• task_key (int | None) – Optional task key to scope the manager.

• schedule_key (int | None) – Optional schedule key to scope the manager.

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, task=None, schedule=None, **filter_kwargs)

List task schedule triggers with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• task (int | None) – Filter by task key. Ignored if manager is scoped to a task.

• schedule (int | None) – Filter by schedule key. Ignored if manager is scoped to a schedule.

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of TaskScheduleTrigger objects.

Return type:

list[TaskScheduleTrigger]

Example

>>> # All triggers
>>> triggers = client.task_schedule_triggers.list()

>>> # Triggers for a specific task
>>> triggers = client.task_schedule_triggers.list(task=task_key)

>>> # Triggers for a specific schedule
>>> triggers = client.task_schedule_triggers.list(schedule=schedule_key)

get(key=None, *, fields=None)

Get a task schedule trigger by key.

Parameters:

• key (int | None) – Trigger $key (ID).

• fields (list[str] | None) – List of fields to return.

Returns:

TaskScheduleTrigger object.

Raises:

• NotFoundError – If trigger not found.

• ValueError – If key not provided.

Return type:

TaskScheduleTrigger

create(task, schedule)

Create a task schedule trigger.

Links a task to a schedule so it runs when the schedule fires.

Parameters:

• task (int) – Task $key to link.

• schedule (int) – Schedule $key to link.

Returns:

Created TaskScheduleTrigger object.

Return type:

TaskScheduleTrigger

Example

>>> trigger = client.task_schedule_triggers.create(
...     task=backup_task.key,
...     schedule=nightly_schedule.key,
... )

delete(key)

Delete a task schedule trigger.

Removes the link between a task and schedule.

Parameters:

key (int) – Trigger $key (ID).

Return type:

None

trigger(key)

Trigger execution immediately.

Fires the trigger, causing the linked task to execute.

Parameters:

key (int) – Trigger $key (ID).

Returns:

Action response dict or None.

Return type:

dict[str, Any] | None

list_for_task(task_key, limit=None)

List all triggers for a specific task.

Parameters:

• task_key (int) – Task $key.

• limit (int | None) – Maximum number of results.

Returns:

List of TaskScheduleTrigger objects.

Return type:

list[TaskScheduleTrigger]

list_for_schedule(schedule_key, limit=None)

List all triggers for a specific schedule.

Parameters:

• schedule_key (int) – Schedule $key.

• limit (int | None) – Maximum number of results.

Returns:

List of TaskScheduleTrigger objects.

Return type:

list[TaskScheduleTrigger]

Task Events

Event definitions for task triggers.

Task event resource manager for VergeOS event-driven automation.

Task events (event triggers) link tasks to system events, enabling event-driven automation. When a specific event occurs on a resource, tasks linked via task events are automatically executed.

Event triggers allow tasks to run in response to specific system occurrences. A single task can be triggered by multiple distinct events, enabling you to consolidate logic and reuse task definitions across scenarios.

Event-Based Task Examples:

• Power on a VM when a designated user logs into VergeOS

• Power off VMs when the user logs out

• Send an email notification when a system update completes

• Use a webhook to notify Slack when a sync error is detected

Event Configuration:

• Type: The object class (e.g., users, virtual machines, tenants, alarms)

• Event: The event type (e.g., login, logout, poweron, error)

• Object Instance: A specific resource, or use tags to match multiple

• Filter Settings: For logs/alarms, filter by severity or log type

Example

>>> # List all task events
>>> for event in client.task_events.list():
...     print(f"{event.event_name_display} -> {event.task_display}")

>>> # Get events linked to a specific task
>>> task = client.tasks.get(name="Power On Dev VMs")
>>> for event in task.events.list():
...     print(f"Triggered by: {event.event_name_display}")

>>> # Create event trigger for user login
>>> event = client.task_events.create(
...     task=task.key,
...     owner=user.key,
...     event="login",
...     table="users",
... )

>>> # Manually trigger an event for testing
>>> event.trigger_now(context={"custom": "data"})

class pyvergeos.resources.task_events.TaskEvent

Bases: ResourceObject

Task event resource object.

Represents a link between a task and a system event.

Properties:

owner_key: The owner resource $key. owner_table: The owner resource table name. event: Event identifier. event_name: Human-readable event name. task_key: Linked task $key. task_display: Linked task display name. filters: Event filter conditions (JSON). context: Event context data (JSON). trigger: Timer value for the event trigger.

property owner_key: int | None

Get the owner resource key.

Note: Some events have non-integer owner values (e.g., ‘update_settings/1’). In those cases, this property returns None.

property owner_table: str | None

Get the owner resource table name.

property event_type: str | None

Get the event identifier.

property event_name_display: str | None

Get the human-readable event name.

property task_key: int | None

Get the linked task key.

property task_display: str

Get the linked task display name.

property event_filters: dict[str, Any] | None

Get the event filter conditions.

property event_context: dict[str, Any] | None

Get the event context data.

trigger_now(context=None)

Manually trigger this event.

Parameters:

context (dict[str, Any] | None) – Optional context data to pass to the task.

Returns:

Action response dict or None.

Return type:

dict[str, Any] | None

class pyvergeos.resources.task_events.TaskEventManager

Bases: ResourceManager[TaskEvent]

Manager for task event operations.

Task events enable event-driven automation by linking tasks to system events.

Example

>>> # List all task events
>>> for event in client.task_events.list():
...     print(f"{event.event_name_display}: {event.task_display}")

>>> # List events for a specific task
>>> events = client.task_events.list(task=task_key)

>>> # List events for a specific owner
>>> events = client.task_events.list(owner=vm_key)

>>> # Manually trigger an event
>>> client.task_events.trigger(event_key, context={"key": "value"})

__init__(client, *, task_key=None, owner_key=None)

Initialize the event manager.

Parameters:

• client (VergeClient) – VergeClient instance.

• task_key (int | None) – Optional task key to scope the manager.

• owner_key (int | None) – Optional owner resource key to scope the manager.

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, task=None, owner=None, table=None, event=None, **filter_kwargs)

List task events with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• task (int | None) – Filter by task key. Ignored if manager is scoped to a task.

• owner (int | None) – Filter by owner resource key. Ignored if manager is scoped.

• table (str | None) – Filter by owner table name.

• event (str | None) – Filter by event identifier.

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of TaskEvent objects.

Return type:

list[TaskEvent]

Example

>>> # All events
>>> events = client.task_events.list()

>>> # Events for a specific task
>>> events = client.task_events.list(task=task_key)

>>> # Events for VMs only
>>> events = client.task_events.list(table="vms")

>>> # Events for a specific event type
>>> events = client.task_events.list(event="poweron")

get(key=None, *, fields=None)

Get a task event by key.

Parameters:

• key (int | None) – Event $key (ID).

• fields (list[str] | None) – List of fields to return.

Returns:

TaskEvent object.

Raises:

• NotFoundError – If event not found.

• ValueError – If key not provided.

Return type:

TaskEvent

create(task, event, *, table, event_name=None, table_event_filters=None, context=None)

Create a task event.

Links a task to a system event for event-driven execution. The owner is auto-populated from the parent task.

Parameters:

• task (int) – Task $key to link (create the task first).

• event (str) – Event identifier (e.g. "lowered").

• table (str) – Event source table (required, e.g. "alarms"). The table whose events will trigger the task.

• event_name (str | None) – Human-readable event name.

• table_event_filters (dict[str, Any] | None) – JSON filter conditions for the event.

• context (dict[str, Any] | None) – JSON context data to pass to the task.

Returns:

Created TaskEvent object.

Return type:

TaskEvent

Example

>>> # Create a task first, then link an event
>>> task = client.tasks.create(
...     name="Alert on alarm",
...     owner=1,
...     action="send",
...     table="smtp_settings",
... )
>>> # Trigger task when an alarm is lowered
>>> event = client.task_events.create(
...     task=task.key,
...     event="lowered",
...     table="alarms",
...     table_event_filters={"level": "summary"},
... )

update(key, *, table_event_filters=None, context=None)

Update a task event.

Parameters:

• key (int) – Event $key (ID).

• table_event_filters (dict[str, Any] | None) – New filter conditions.

• context (dict[str, Any] | None) – New context data.

Returns:

Updated TaskEvent object.

Return type:

TaskEvent

delete(key)

Delete a task event.

Removes the link between a task and event.

Parameters:

key (int) – Event $key (ID).

Return type:

None

trigger(key, context=None)

Manually trigger a task event.

Fires the event, causing the linked task to execute.

Parameters:

• key (int) – Event $key (ID).

• context (dict[str, Any] | None) – Optional context data to pass to the task.

Returns:

Action response dict or None.

Return type:

dict[str, Any] | None

Example

>>> # Trigger an event
>>> client.task_events.trigger(event_key)

>>> # Trigger with context
>>> client.task_events.trigger(event_key, context={"key": "value"})

list_for_task(task_key, limit=None)

List all events for a specific task.

Parameters:

• task_key (int) – Task $key.

• limit (int | None) – Maximum number of results.

Returns:

List of TaskEvent objects.

Return type:

list[TaskEvent]

list_for_owner(owner_key, limit=None)

List all events for a specific owner resource.

Parameters:

• owner_key (int) – Owner resource $key.

• limit (int | None) – Maximum number of results.

Returns:

List of TaskEvent objects.

Return type:

list[TaskEvent]

list_by_table(table, limit=None)

List all events for a specific table/resource type.

Parameters:

• table (str) – Table name (e.g., “vms”, “vnets”, “tenants”).

• limit (int | None) – Maximum number of results.

Returns:

List of TaskEvent objects.

Return type:

list[TaskEvent]

Task Scripts

Task script resource manager for VergeOS automation scripts.

Task scripts are GCS (VergeOS scripting) code that can be executed as tasks. Scripts can define questions (settings) that are prompted when running, allowing for reusable automation with configurable parameters.

Example

>>> # List all scripts
>>> for script in client.task_scripts.list():
...     print(f"{script.name}: {script.task_count} tasks")

>>> # Create a simple script
>>> script = client.task_scripts.create(
...     name="Cleanup Script",
...     description="Removes old temporary files",
...     script="# GCS script code here\nlog('Cleanup started')",
...     task_settings={"questions": []},
... )

>>> # Run a script
>>> result = script.run()

class pyvergeos.resources.task_scripts.TaskScript

Bases: ResourceObject

Task script resource object.

Represents a GCS automation script that can be executed as tasks.

Properties:

name: Script name (unique). description: Script description. script_code: The GCS script code. task_settings: JSON settings/questions for the script. task_count: Number of tasks using this script.

property script_code: str | None

Get the script code.

property settings: dict[str, Any] | None

Get the script settings/questions.

property task_count: int

Get the number of tasks using this script.

run(**params)

Run this script.

Parameters:

**params (Any) – Parameters to pass to the script.

Returns:

Run action response dict or None.

Return type:

dict[str, Any] | None

class pyvergeos.resources.task_scripts.TaskScriptManager

Bases: ResourceManager[TaskScript]

Manager for task script operations.

Task scripts provide reusable GCS automation code.

Example

>>> # List all scripts
>>> for script in client.task_scripts.list():
...     print(f"{script.name}: {script.description}")

>>> # Create a script
>>> script = client.task_scripts.create(
...     name="My Script",
...     script="log('Hello World')",
...     task_settings={"questions": []},
... )

>>> # Get a script by name
>>> script = client.task_scripts.get(name="My Script")

>>> # Run a script
>>> result = client.task_scripts.run(script.key)

>>> # Update script code
>>> script = client.task_scripts.update(
...     script.key,
...     script="log('Updated code')"
... )

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, name=None, **filter_kwargs)

List task scripts with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• name (str | None) – Filter by name.

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of TaskScript objects.

Return type:

list[TaskScript]

Example

>>> # All scripts
>>> scripts = client.task_scripts.list()

>>> # Scripts by name pattern
>>> scripts = client.task_scripts.list(name="Backup*")

get(key=None, *, name=None, fields=None)

Get a task script by key or name.

Parameters:

• key (int | None) – Script $key (ID).

• name (str | None) – Script name (unique).

• fields (list[str] | None) – List of fields to return.

Returns:

TaskScript object.

Raises:

• NotFoundError – If script not found.

• ValueError – If neither key nor name provided.

Return type:

TaskScript

create(name, script, *, description=None, task_settings=None)

Create a new task script.

Parameters:

• name (str) – Script name (unique, required).

• script (str) – GCS script code (required).

• description (str | None) – Script description.

• task_settings (dict[str, Any] | None) – JSON settings/questions for the script.

Returns:

Created TaskScript object.

Return type:

TaskScript

Example

>>> script = client.task_scripts.create(
...     name="My Script",
...     description="Does something useful",
...     script="log('Hello World')",
...     task_settings={"questions": []},
... )

update(key, *, name=None, description=None, script=None, task_settings=None)

Update an existing task script.

Parameters:

• key (int) – Script $key (ID).

• name (str | None) – New name.

• description (str | None) – New description.

• script (str | None) – New GCS script code.

• task_settings (dict[str, Any] | None) – New settings/questions.

Returns:

Updated TaskScript object.

Return type:

TaskScript

Example

>>> script = client.task_scripts.update(
...     script.key,
...     script="log('Updated code')"
... )

delete(key)

Delete a task script.

Note

Scripts with associated tasks cannot be deleted. The tasks will be cascade deleted.

Parameters:

key (int) – Script $key (ID).

Return type:

None

run(key, **params)

Run a task script.

Executes the script, optionally with provided parameters.

Parameters:

• key (int) – Script $key (ID).

• **params (Any) – Parameters to pass to the script.

Returns:

Run action response dict or None.

Return type:

dict[str, Any] | None

Example

>>> # Run a script
>>> result = client.task_scripts.run(script.key)

>>> # Run with parameters
>>> result = client.task_scripts.run(
...     script.key,
...     target_vm=123,
...     cleanup=True,
... )

Users and Groups

Users

User resource manager for VergeOS system users.

class pyvergeos.resources.users.User

Bases: ResourceObject

User resource object.

Represents a user account in VergeOS. Users can be normal users, API users, or VDI users.

key

User primary key ($key).

name

Username (login name).

displayname

Display name.

email

Email address.

user_type

User type (‘normal’, ‘api’, ‘vdi’).

enabled

Whether the account is enabled.

created

Creation timestamp (Unix epoch).

last_login

Last login timestamp (Unix epoch).

change_password

Whether password change is required on next login.

physical_access

Whether console/SSH access is enabled (admin privilege).

two_factor_enabled

Whether 2FA is enabled.

two_factor_type

Type of 2FA (‘email’ or ‘authenticator’).

two_factor_setup_required

Whether 2FA setup is required on next login.

account_locked

Timestamp when account was locked (0 if not locked).

failed_attempts

Number of failed login attempts.

auth_source

Authentication source key.

auth_source_name

Authentication source name.

remote_name

Remote username (for external auth).

identity

Identity key.

creator

Username of the user who created this account.

ssh_keys

SSH public keys (newline-separated).

property user_type: str

Get the user type (normal, api, vdi).

property user_type_display: str

Get the user type as a human-readable string.

property displayname: str | None

Get the display name.

property email: str | None

Get the email address.

property is_enabled: bool

Check if user account is enabled.

property created: int | None

Get the creation timestamp (Unix epoch).

property last_login: int | None

Get the last login timestamp (Unix epoch).

property change_password: bool

Check if password change is required on next login.

property physical_access: bool

Check if physical (console/SSH) access is enabled.

Note: Users with physical access have administrator privileges.

property two_factor_enabled: bool

Check if two-factor authentication is enabled.

property two_factor_type: str | None

Get the 2FA type (‘email’ or ‘authenticator’).

property two_factor_type_display: str

Get the 2FA type as a human-readable string.

property two_factor_setup_required: bool

Check if 2FA setup is required on next login.

Note: This is a write-only field in the API, so this property will always return False. Use it only for setting during create/update operations.

property account_locked: int | None

Get the account locked timestamp (Unix epoch), or None if not locked.

property is_locked: bool

Check if account is currently locked.

property failed_attempts: int

Get the number of failed login attempts.

property auth_source: int | None

Get the authentication source key.

property auth_source_name: str | None

Get the authentication source name.

property remote_name: str | None

Get the remote username (for external auth).

property identity: int | None

Get the identity key.

property creator: str | None

Get the username of who created this account.

property ssh_keys: str | None

Get the SSH public keys (newline-separated).

enable()

Enable this user account.

Returns:

Updated User object.

Return type:

User

disable()

Disable this user account.

Returns:

Updated User object.

Return type:

User

class pyvergeos.resources.users.UserManager

Bases: ResourceManager[User]

Manager for VergeOS user operations.

Provides CRUD operations and management for user accounts.

Example

>>> # List all users
>>> for user in client.users.list():
...     print(f"{user.name}: {user.user_type_display}")

>>> # List only API users
>>> api_users = client.users.list(user_type="api")

>>> # Create a user
>>> user = client.users.create(
...     name="jsmith",
...     password="SecurePass123!",
...     displayname="John Smith",
...     email="jsmith@company.com"
... )

>>> # Enable/disable users
>>> client.users.disable(user.key)
>>> client.users.enable(user.key)

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, user_type=None, enabled=None, include_system=False, **filter_kwargs)

List users with optional filtering.

By default, excludes system user types (site_sync, site_user).

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• user_type (Literal['normal', 'api', 'vdi'] | None) – Filter by user type (‘normal’, ‘api’, ‘vdi’).

• enabled (bool | None) – Filter by enabled status.

• include_system (bool) – Include system user types (site_sync, site_user).

• **filter_kwargs (Any) – Shorthand filter arguments (name, etc.).

Returns:

List of User objects.

Return type:

list[User]

Example

>>> # List all users
>>> users = client.users.list()

>>> # List only API users
>>> api_users = client.users.list(user_type="api")

>>> # List disabled users
>>> disabled = client.users.list(enabled=False)

>>> # List by name pattern (exact match)
>>> users = client.users.list(name="admin")

list_enabled()

List all enabled users.

Returns:

List of enabled User objects.

Return type:

list[User]

list_disabled()

List all disabled users.

Returns:

List of disabled User objects.

Return type:

list[User]

list_api_users()

List all API users.

Returns:

List of API User objects.

Return type:

list[User]

list_vdi_users()

List all VDI users.

Returns:

List of VDI User objects.

Return type:

list[User]

get(key=None, *, name=None, fields=None)

Get a single user by key or name.

Parameters:

• key (int | None) – User $key (ID).

• name (str | None) – Username.

• fields (list[str] | None) – List of fields to return.

Returns:

User object.

Raises:

• NotFoundError – If user not found.

• ValueError – If neither key nor name provided.

Return type:

User

Example

>>> # Get by key
>>> user = client.users.get(123)

>>> # Get by name
>>> user = client.users.get(name="admin")

create(name, password, *, displayname=None, email=None, user_type='normal', enabled=True, change_password=False, physical_access=False, two_factor_enabled=False, two_factor_type='email', two_factor_setup_required=False, ssh_keys=None)

Create a new user.

Parameters:

• name (str) – Username (1-128 chars, no forward slashes, will be lowercased).

• password (str) – User password.

• displayname (str | None) – Display name for the user.

• email (str | None) – Email address (required if enabling 2FA).

• user_type (Literal['normal', 'api', 'vdi']) – User type (‘normal’, ‘api’, ‘vdi’). Default ‘normal’.

• enabled (bool) – Enable the account. Default True.

• change_password (bool) – Require password change on next login. Default False.

• physical_access (bool) – Enable console/SSH access (grants admin). Default False.

• two_factor_enabled (bool) – Enable two-factor authentication. Default False.

• two_factor_type (Literal['email', 'authenticator']) – Type of 2FA (‘email’ or ‘authenticator’). Default ‘email’.

• two_factor_setup_required (bool) – Require 2FA setup on next login. Default False.

• ssh_keys (list[str] | str | None) – SSH public keys (list or newline-separated string).

Returns:

Created User object.

Raises:

ValueError – If email not provided when enabling 2FA.

Return type:

User

Example

>>> # Create a basic user
>>> user = client.users.create(
...     name="jsmith",
...     password="SecurePass123!",
...     displayname="John Smith",
...     email="jsmith@company.com"
... )

>>> # Create an API user
>>> api_user = client.users.create(
...     name="api_service",
...     password="ApiSecret!",
...     user_type="api"
... )

>>> # Create with 2FA enabled
>>> user = client.users.create(
...     name="secure_user",
...     password="Pass123!",
...     email="secure@company.com",
...     two_factor_enabled=True,
...     two_factor_type="authenticator"
... )

update(key, *, password=None, displayname=None, email=None, enabled=None, change_password=None, physical_access=None, two_factor_enabled=None, two_factor_type=None, two_factor_setup_required=None, ssh_keys=None)

Update a user.

Parameters:

• key (int) – User $key (ID).

• password (str | None) – New password.

• displayname (str | None) – New display name.

• email (str | None) – New email address.

• enabled (bool | None) – Enable or disable the account.

• change_password (bool | None) – Require password change on next login.

• physical_access (bool | None) – Enable or disable console/SSH access.

• two_factor_enabled (bool | None) – Enable or disable 2FA.

• two_factor_type (Literal['email', 'authenticator'] | None) – Type of 2FA (‘email’ or ‘authenticator’).

• two_factor_setup_required (bool | None) – Require 2FA setup on next login.

• ssh_keys (list[str] | str | None) – SSH public keys (list, string, or empty string to clear).

Returns:

Updated User object.

Return type:

User

Example

>>> # Change password
>>> client.users.update(user.key, password="NewPass123!")

>>> # Update display name and email
>>> client.users.update(
...     user.key,
...     displayname="John Q. Smith",
...     email="john.smith@company.com"
... )

>>> # Enable 2FA
>>> client.users.update(
...     user.key,
...     two_factor_enabled=True,
...     two_factor_type="authenticator"
... )

enable(key)

Enable a user account.

Parameters:

key (int) – User $key (ID).

Returns:

Updated User object.

Return type:

User

Example

>>> client.users.enable(user.key)

disable(key)

Disable a user account.

The account is not deleted and can be re-enabled later.

Parameters:

key (int) – User $key (ID).

Returns:

Updated User object.

Return type:

User

Example

>>> client.users.disable(user.key)

Groups

Group resource manager for VergeOS groups.

class pyvergeos.resources.groups.GroupMember

Bases: ResourceObject

Group member resource object.

Represents a membership record linking a user or group to a parent group.

key

Membership primary key ($key).

group_key

Parent group key.

member_type

Type of member (‘User’ or ‘Group’).

member_key

Key of the member (user or group).

member_name

Display name of the member.

member_ref

API reference to the member.

creator

Username of who created this membership.

property group_key: int

Get the parent group key.

property member_ref: str

Get the member API reference (e.g., ‘/v4/users/1’).

property member_type: str

Get the member type (‘User’ or ‘Group’).

property member_key: int | None

Get the member key (user or group ID).

property member_name: str | None

Get the member display name.

property creator: str | None

Get the username of who created this membership.

remove()

Remove this member from the group.

Raises:

ValueError – If membership key is not available.

Return type:

None

class pyvergeos.resources.groups.GroupMemberManager

Bases: ResourceManager[GroupMember]

Manager for group membership operations.

This manager handles adding and removing users/groups from a parent group. It can be accessed via group.members or directly via client.groups.members().

Example

>>> # List members of a group
>>> for member in client.groups.members(group_key).list():
...     print(f"{member.member_name} ({member.member_type})")

>>> # Add a user to a group
>>> client.groups.members(group_key).add_user(user_key)

>>> # Remove a member
>>> client.groups.members(group_key).remove(membership_key)

__init__(client, group_key)

Parameters:

• client (VergeClient)

• group_key (int)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List members of this group.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of GroupMember objects.

Return type:

list[GroupMember]

Example

>>> members = client.groups.members(group_key).list()
>>> for m in members:
...     print(f"{m.member_name}: {m.member_type}")

add_user(user_key)

Add a user to this group.

Parameters:

user_key (int) – User $key (ID) to add.

Returns:

Created GroupMember object with full details.

Raises:

ConflictError – If user is already a member.

Return type:

GroupMember

Example

>>> member = client.groups.members(group_key).add_user(user.key)

add_group(member_group_key)

Add a group as a member of this group (nested group).

Parameters:

member_group_key (int) – Group $key (ID) to add as member.

Returns:

Created GroupMember object with full details.

Raises:

ConflictError – If group is already a member.

Return type:

GroupMember

Example

>>> # Add Developers group to AllUsers group
>>> member = client.groups.members(all_users_key).add_group(developers_key)

remove(membership_key)

Remove a membership by its key.

Parameters:

membership_key (int) – Membership $key (ID) to remove.

Return type:

None

Example

>>> client.groups.members(group_key).remove(membership.key)

remove_user(user_key)

Remove a user from this group.

Parameters:

user_key (int) – User $key (ID) to remove.

Raises:

NotFoundError – If user is not a member of this group.

Return type:

None

Example

>>> client.groups.members(group_key).remove_user(user.key)

remove_group(member_group_key)

Remove a group from this group.

Parameters:

member_group_key (int) – Group $key (ID) to remove.

Raises:

NotFoundError – If group is not a member of this group.

Return type:

None

Example

>>> client.groups.members(parent_key).remove_group(child_key)

class pyvergeos.resources.groups.Group

Bases: ResourceObject

Group resource object.

Represents a group in VergeOS that can contain users and other groups. Groups are used for organizing users and assigning permissions.

key

Group primary key ($key).

name

Group name.

description

Group description.

enabled

Whether the group is enabled.

email

Group email address.

identifier

Group identifier (id field).

identity

Identity key.

is_system_group

Whether this is a system group.

member_count

Number of members in the group.

created

Creation timestamp (Unix epoch).

creator

Username of who created this group.

property description: str | None

Get the group description.

property is_enabled: bool

Check if group is enabled.

property email: str | None

Get the group email address.

property identifier: str | None

Get the group identifier.

property identity: int | None

Get the identity key.

property is_system_group: bool

Check if this is a system group.

property member_count: int

Get the number of members in the group.

property created: int | None

Get the creation timestamp (Unix epoch).

property creator: str | None

Get the username of who created this group.

property members: GroupMemberManager

Access group member operations for this group.

Returns:

GroupMemberManager for this group.

Example

>>> # List members
>>> for member in group.members.list():
...     print(member.member_name)

>>> # Add a user
>>> group.members.add_user(user.key)

enable()

Enable this group.

Returns:

Updated Group object.

Return type:

Group

disable()

Disable this group.

Returns:

Updated Group object.

Return type:

Group

class pyvergeos.resources.groups.GroupManager

Bases: ResourceManager[Group]

Manager for VergeOS group operations.

Provides CRUD operations and management for groups.

Example

>>> # List all groups
>>> for group in client.groups.list():
...     print(f"{group.name}: {group.member_count} members")

>>> # List only enabled groups
>>> enabled_groups = client.groups.list(enabled=True)

>>> # Create a group
>>> group = client.groups.create(
...     name="Developers",
...     description="Development team",
...     email="dev@company.com"
... )

>>> # Enable/disable groups
>>> client.groups.disable(group.key)
>>> client.groups.enable(group.key)

>>> # Manage members
>>> client.groups.members(group.key).add_user(user.key)

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, enabled=None, include_system=True, **filter_kwargs)

List groups with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• enabled (bool | None) – Filter by enabled status.

• include_system (bool) – Include system groups (default True).

• **filter_kwargs (Any) – Shorthand filter arguments (name, etc.).

Returns:

List of Group objects.

Return type:

list[Group]

Example

>>> # List all groups
>>> groups = client.groups.list()

>>> # List only enabled groups
>>> enabled = client.groups.list(enabled=True)

>>> # List non-system groups only
>>> user_groups = client.groups.list(include_system=False)

>>> # List by name pattern (exact match)
>>> groups = client.groups.list(name="Administrators")

list_enabled()

List all enabled groups.

Returns:

List of enabled Group objects.

Return type:

list[Group]

list_disabled()

List all disabled groups.

Returns:

List of disabled Group objects.

Return type:

list[Group]

get(key=None, *, name=None, fields=None)

Get a single group by key or name.

Parameters:

• key (int | None) – Group $key (ID).

• name (str | None) – Group name.

• fields (list[str] | None) – List of fields to return.

Returns:

Group object.

Raises:

• NotFoundError – If group not found.

• ValueError – If neither key nor name provided.

Return type:

Group

Example

>>> # Get by key
>>> group = client.groups.get(123)

>>> # Get by name
>>> group = client.groups.get(name="Administrators")

create(name, *, description=None, email=None, enabled=True)

Create a new group.

Parameters:

• name (str) – Group name (1-128 characters, must be unique).

• description (str | None) – Group description (optional).

• email (str | None) – Group email address (optional).

• enabled (bool) – Whether the group is enabled (default True).

Returns:

Created Group object.

Return type:

Group

Example

>>> # Create a basic group
>>> group = client.groups.create(name="Developers")

>>> # Create with all options
>>> group = client.groups.create(
...     name="QA Team",
...     description="Quality Assurance team",
...     email="qa@company.com"
... )

update(key, *, name=None, description=None, email=None, enabled=None)

Update a group.

Parameters:

• key (int) – Group $key (ID).

• name (str | None) – New group name.

• description (str | None) – New description.

• email (str | None) – New email address.

• enabled (bool | None) – Enable or disable the group.

Returns:

Updated Group object.

Return type:

Group

Example

>>> # Update description
>>> client.groups.update(group.key, description="New description")

>>> # Rename group
>>> client.groups.update(group.key, name="NewName")

enable(key)

Enable a group.

Parameters:

key (int) – Group $key (ID).

Returns:

Updated Group object.

Return type:

Group

Example

>>> client.groups.enable(group.key)

disable(key)

Disable a group.

The group is not deleted and can be re-enabled later.

Parameters:

key (int) – Group $key (ID).

Returns:

Updated Group object.

Return type:

Group

Example

>>> client.groups.disable(group.key)

members(group_key)

Get a member manager for a specific group.

Parameters:

group_key (int) – Group $key (ID).

Returns:

GroupMemberManager for the specified group.

Return type:

GroupMemberManager

Example

>>> # List members
>>> members = client.groups.members(group.key).list()

>>> # Add user to group
>>> client.groups.members(group.key).add_user(user.key)

API Keys

API Key resource manager for VergeOS user API keys.

class pyvergeos.resources.api_keys.APIKeyCreated

Bases: object

Response from creating an API key containing the secret.

The secret is only available once at creation time and cannot be retrieved later.

key

The API key ID ($key).

name

The API key name.

user_key

The user’s $key.

user_name

The username.

secret

The API key secret (only shown once).

__init__(key, name, user_key, user_name, secret)

Parameters:

• key (int)

• name (str)

• user_key (int)

• user_name (str | None)

• secret (str)

Return type:

None

class pyvergeos.resources.api_keys.APIKey

Bases: ResourceObject

API Key resource object.

Represents an API key associated with a user account.

key

API key primary key ($key).

name

API key name.

description

API key description.

user_key

The user’s $key this key belongs to.

user_name

The username this key belongs to.

created

Creation timestamp (Unix epoch).

expires

Expiration timestamp (Unix epoch), or None if never expires.

last_login

Last login timestamp (Unix epoch).

last_login_ip

IP address of last login.

ip_allow_list

List of allowed IP addresses/CIDR ranges.

ip_deny_list

List of denied IP addresses/CIDR ranges.

property description: str | None

Get the API key description.

property user_key: int

Get the user $key this key belongs to.

property user_name: str | None

Get the username this key belongs to.

property created: int | None

Get the creation timestamp (Unix epoch).

property created_datetime: datetime | None

Get the creation time as a datetime object.

property expires: int | None

Get the expiration timestamp (Unix epoch), or None if never expires.

property expires_datetime: datetime | None

Get the expiration time as a datetime object.

property is_expired: bool

Check if the API key has expired.

property last_login: int | None

Get the last login timestamp (Unix epoch).

property last_login_datetime: datetime | None

Get the last login time as a datetime object.

property last_login_ip: str | None

Get the IP address of the last login.

property ip_allow_list: list[str]

Get the list of allowed IP addresses/CIDR ranges.

property ip_deny_list: list[str]

Get the list of denied IP addresses/CIDR ranges.

delete()

Delete this API key.

Example

>>> api_key.delete()

Return type:

None

class pyvergeos.resources.api_keys.APIKeyManager

Bases: ResourceManager[APIKey]

Manager for VergeOS API key operations.

Provides CRUD operations for user API keys.

Example

>>> # List all API keys
>>> for key in client.api_keys.list():
...     print(f"{key.name}: user={key.user_name}")

>>> # List API keys for a specific user
>>> user_keys = client.api_keys.list(user=123)

>>> # Create an API key
>>> result = client.api_keys.create(
...     user=123,
...     name="automation-key",
...     description="CI/CD automation"
... )
>>> print(f"Secret: {result.secret}")  # Only shown once!

>>> # Delete an API key
>>> client.api_keys.delete(key_id)

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, user=None, **filter_kwargs)

List API keys with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• user (int | str | None) – Filter by user - can be user $key (int) or username (str).

• **filter_kwargs (Any) – Shorthand filter arguments (name, etc.).

Returns:

List of APIKey objects.

Return type:

list[APIKey]

Example

>>> # List all API keys
>>> keys = client.api_keys.list()

>>> # List keys for a specific user by key
>>> keys = client.api_keys.list(user=123)

>>> # List keys for a specific user by name
>>> keys = client.api_keys.list(user="admin")

>>> # List by name
>>> keys = client.api_keys.list(name="automation")

get(key=None, *, name=None, user=None, fields=None)

Get a single API key by key or name.

Parameters:

• key (int | None) – API key $key (ID).

• name (str | None) – API key name (requires user parameter).

• user (int | str | None) – User $key or username (required when looking up by name).

• fields (list[str] | None) – List of fields to return.

Returns:

APIKey object.

Raises:

• NotFoundError – If API key not found.

• ValueError – If neither key nor name provided, or name without user.

Return type:

APIKey

Example

>>> # Get by key
>>> api_key = client.api_keys.get(5)

>>> # Get by name for a user
>>> api_key = client.api_keys.get(name="automation", user="admin")

create(user, name, *, description=None, expires_in=None, expires=None, ip_allow_list=None, ip_deny_list=None)

Create a new API key.

IMPORTANT: The API key secret is only returned once at creation time. Store it securely as it cannot be retrieved later.

Parameters:

• user (int | str) – User $key (int) or username (str) to create the key for.

• name (str) – Name for the API key (1-128 chars, unique per user).

• description (str | None) – Optional description for the API key.

• expires_in (str | None) – Duration until expiration (‘30d’, ‘1w’, ‘3m’, ‘1y’, or ‘never’). Supported units: d (days), w (weeks), m (months), y (years). Default is ‘never’ (no expiration).

• expires (datetime | None) – Specific datetime when the key should expire.

• ip_allow_list (list[str] | None) – List of IP addresses or CIDR ranges allowed to use this key.

• ip_deny_list (list[str] | None) – List of IP addresses or CIDR ranges denied from using this key.

Returns:

APIKeyCreated object containing the key ID and secret.

Raises:

• NotFoundError – If user not found.

• ValueError – If invalid expires_in format.

Return type:

APIKeyCreated

Example

>>> # Create a basic API key
>>> result = client.api_keys.create(
...     user="admin",
...     name="automation-key"
... )
>>> print(f"Secret: {result.secret}")  # Store this!

>>> # Create with expiration
>>> result = client.api_keys.create(
...     user=123,
...     name="temp-key",
...     expires_in="90d",
...     description="Temporary CI/CD key"
... )

>>> # Create with IP restrictions
>>> result = client.api_keys.create(
...     user="apiuser",
...     name="restricted-key",
...     ip_allow_list=["10.0.0.0/8", "192.168.1.100"]
... )

delete(key)

Delete an API key.

This action is permanent and the key will no longer be usable.

Parameters:

key (int) – API key $key (ID) to delete.

Return type:

None

Example

>>> client.api_keys.delete(5)

Permissions

Permission resource manager for VergeOS permissions.

class pyvergeos.resources.permissions.Permission

Bases: ResourceObject

Permission resource object.

Represents a permission grant in VergeOS that controls access to resources for users or groups.

key

Permission primary key ($key).

identity_key

Identity key (links to user or group identity).

identity_name

Display name of the identity (user/group name).

table

Resource table name (e.g., ‘vms’, ‘vnets’, ‘/’).

row_key

Specific row key (0 for table-level access).

row_display

Display name of the row (if row-specific).

is_table_level

Whether this is table-level (all rows) permission.

can_list

Whether list/see permission is granted.

can_read

Whether read permission is granted.

can_create

Whether create permission is granted.

can_modify

Whether modify permission is granted.

can_delete

Whether delete permission is granted.

property identity_key: int

Get the identity key.

property identity_name: str | None

Get the identity display name (user/group name).

property table: str

Get the resource table name.

property row_key: int

Get the row key (0 for table-level access).

property row_display: str | None

Get the row display name (if row-specific).

property is_table_level: bool

Check if this is a table-level permission (applies to all rows).

property can_list: bool

Check if list permission is granted.

property can_read: bool

Check if read permission is granted.

property can_create: bool

Check if create permission is granted.

property can_modify: bool

Check if modify permission is granted.

property can_delete: bool

Check if delete permission is granted.

property has_full_control: bool

Check if all permissions are granted (full control).

revoke()

Revoke this permission.

Raises:

ValueError – If permission key is not available.

Return type:

None

class pyvergeos.resources.permissions.PermissionManager

Bases: ResourceManager[Permission]

Manager for VergeOS permission operations.

Provides operations to list, grant, and revoke permissions for users and groups on resources.

Example

>>> # List all permissions for a user
>>> perms = client.permissions.list(user=user.key)

>>> # List permissions for a group on VMs
>>> perms = client.permissions.list(group=group.key, table="vms")

>>> # Grant read-only access to VMs
>>> client.permissions.grant(
...     user=user.key,
...     table="vms",
...     can_list=True,
...     can_read=True
... )

>>> # Grant full control to a group
>>> client.permissions.grant(
...     group=group.key,
...     table="vms",
...     full_control=True
... )

>>> # Revoke a permission
>>> client.permissions.revoke(permission.key)

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, user=None, group=None, identity_key=None, table=None, **filter_kwargs)

List permissions with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (builtins.list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• user (int | User | None) – User key or User object to filter by.

• group (int | Group | None) – Group key or Group object to filter by.

• identity_key (int | None) – Identity key to filter by directly.

• table (str | None) – Resource table name to filter by (e.g., ‘vms’, ‘vnets’).

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of Permission objects.

Return type:

builtins.list[Permission]

Example

>>> # List all permissions
>>> perms = client.permissions.list()

>>> # List permissions for a user
>>> perms = client.permissions.list(user=user.key)

>>> # List permissions for a group on VMs
>>> perms = client.permissions.list(group=group.key, table="vms")

>>> # List permissions by identity key directly
>>> perms = client.permissions.list(identity_key=123)

get(key, *, fields=None)

Get a single permission by key.

Parameters:

• key (int) – Permission $key (ID).

• fields (list[str] | None) – List of fields to return.

Returns:

Permission object.

Raises:

NotFoundError – If permission not found.

Return type:

Permission

Example

>>> perm = client.permissions.get(123)

grant(table, *, user=None, group=None, identity_key=None, row_key=0, can_list=True, can_read=False, can_create=False, can_modify=False, can_delete=False, full_control=False)

Grant permission to a user or group.

Parameters:

• table (str) – Resource table to grant access to (e.g., ‘vms’, ‘vnets’, ‘/’).

• user (int | User | None) – User key or User object to grant to.

• group (int | Group | None) – Group key or Group object to grant to.

• identity_key (int | None) – Identity key to grant to directly.

• row_key (int) – Specific row key (0 for table-level access to all rows).

• can_list (bool) – Grant permission to list/see items. Default True.

• can_read (bool) – Grant permission to read item details. Default False.

• can_create (bool) – Grant permission to create new items. Default False.

• can_modify (bool) – Grant permission to modify existing items. Default False.

• can_delete (bool) – Grant permission to delete items. Default False.

• full_control (bool) – Grant all permissions (overrides individual flags).

Returns:

Created Permission object.

Raises:

• ValueError – If no user, group, or identity_key provided.

• ConflictError – If permission already exists.

Return type:

Permission

Example

>>> # Grant read-only access to VMs for a user
>>> perm = client.permissions.grant(
...     table="vms",
...     user=user.key,
...     can_list=True,
...     can_read=True
... )

>>> # Grant full control to a group
>>> perm = client.permissions.grant(
...     table="vms",
...     group=group.key,
...     full_control=True
... )

>>> # Grant root access (all resources)
>>> perm = client.permissions.grant(
...     table="/",
...     user=user.key,
...     can_list=True,
...     can_read=True
... )

>>> # Grant access to a specific VM only
>>> perm = client.permissions.grant(
...     table="vms",
...     user=user.key,
...     row_key=vm.key,
...     full_control=True
... )

revoke(key)

Revoke (delete) a permission.

Parameters:

key (int) – Permission $key (ID) to revoke.

Return type:

None

Example

>>> client.permissions.revoke(perm.key)

revoke_for_user(user, table=None)

Revoke all permissions for a user, optionally filtered by table.

Parameters:

• user (int | User) – User key or User object.

• table (str | None) – Optional table name to filter by.

Returns:

Number of permissions revoked.

Return type:

int

Example

>>> # Revoke all permissions for user
>>> count = client.permissions.revoke_for_user(user.key)

>>> # Revoke only VM permissions for user
>>> count = client.permissions.revoke_for_user(user.key, table="vms")

revoke_for_group(group, table=None)

Revoke all permissions for a group, optionally filtered by table.

Parameters:

• group (int | Group) – Group key or Group object.

• table (str | None) – Optional table name to filter by.

Returns:

Number of permissions revoked.

Return type:

int

Example

>>> # Revoke all permissions for group
>>> count = client.permissions.revoke_for_group(group.key)

>>> # Revoke only network permissions for group
>>> count = client.permissions.revoke_for_group(group.key, table="vnets")

Authentication & Security

Authentication Sources

External identity providers (OAuth2, OIDC, Azure AD, Okta).

Authentication source management for external identity providers.

Authentication sources enable SSO and federated login via OAuth2/OIDC providers such as Azure AD, Google, GitLab, Okta, and generic OpenID Connect.

Key concepts:

• Auth Source: Configuration for an external identity provider

• Driver: The type of provider (azure, google, gitlab, okta, openid, etc.)

• Settings: Driver-specific configuration stored as JSON

• States: Ephemeral OAuth state tokens during authentication flow

Supported drivers:

• azure: Azure Active Directory

• google: Google OAuth

• gitlab: GitLab (OpenID)

• okta: Okta

• openid: Generic OpenID Connect

• openid-well-known: OpenID with well-known configuration discovery

• oauth2: Generic OAuth2

• verge.io: Verge.io parent system authentication

Example

>>> # List all authentication sources
>>> for source in client.auth_sources.list():
...     print(f"{source.name} ({source.driver})")

>>> # Get a specific auth source
>>> azure = client.auth_sources.get(name="Azure AD")

>>> # Create an Azure AD auth source
>>> source = client.auth_sources.create(
...     name="Corporate Azure",
...     driver="azure",
...     settings={
...         "tenant_id": "your-tenant-id",
...         "client_id": "your-client-id",
...         "client_secret": "your-client-secret",
...         "scope": "openid profile email",
...     }
... )

>>> # Enable debug mode for troubleshooting
>>> source.enable_debug()

>>> # List users using this auth source
>>> for user in client.users.list(auth_source=source.key):
...     print(f"  {user.name}")

class pyvergeos.resources.auth_sources.AuthSourceState

Bases: ResourceObject

OAuth state token for authentication flow.

Auth source states are ephemeral tokens created during the OAuth authentication flow. They expire after 15 minutes.

key

State key (40-character hex string).

auth_source

Parent auth source key.

meta

State metadata (JSON).

timestamp

Creation timestamp (microseconds).

property key: str

State key (40-character hex string).

Raises:

ValueError – If state has no key.

property auth_source_key: int | None

Get the parent auth source key.

property is_expired: bool

Check if state has expired (>15 minutes old).

States expire 15 minutes (900 seconds) after creation.

class pyvergeos.resources.auth_sources.AuthSourceStateManager

Bases: ResourceManager[AuthSourceState]

Manager for authentication source state operations.

States are read-only and automatically created/deleted during OAuth flow.

Example

>>> # List states for an auth source
>>> for state in client.auth_source_states.list(auth_source=1):
...     print(f"{state.key}: expired={state.is_expired}")

__init__(client, *, auth_source_key=None)

Parameters:

• client (VergeClient)

• auth_source_key (int | None)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, auth_source=None, **filter_kwargs)

List auth source states with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• auth_source (int | None) – Filter by auth source key. Ignored if manager is scoped.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of AuthSourceState objects.

Return type:

list[AuthSourceState]

get(key=None, *, fields=None)

Get a single state by key.

Parameters:

• key (str | None) – State key (40-character hex string).

• fields (list[str] | None) – List of fields to return.

Returns:

AuthSourceState object.

Raises:

• NotFoundError – If state not found.

• ValueError – If key not provided.

Return type:

AuthSourceState

class pyvergeos.resources.auth_sources.AuthSource

Bases: ResourceObject

Authentication source resource object.

Represents an external identity provider configuration.

key

Auth source $key (row ID).

name

Display name shown on login button.

driver

Provider type (azure, google, gitlab, okta, openid, etc.).

settings

Driver-specific configuration (JSON).

menu

Whether to show in dropdown menu.

debug

Debug logging enabled.

debug_ts

Debug mode timestamp.

button_background_color

Login button background color (CSS).

button_color

Login button text color (CSS).

button_fa_icon

Login button Font Awesome icon class.

icon_color

Login button icon color (CSS).

property driver: str

Get the auth provider driver type.

property is_azure: bool

Check if this is an Azure AD source.

property is_google: bool

Check if this is a Google source.

property is_gitlab: bool

Check if this is a GitLab source.

property is_okta: bool

Check if this is an Okta source.

property is_openid: bool

Check if this is an OpenID source (any variant).

property is_oauth2: bool

Check if this is a generic OAuth2 source.

property is_vergeos: bool

Check if this is a Verge.io parent source.

property settings: dict[str, Any]

Get driver-specific settings.

Settings vary by driver but commonly include: - client_id: OAuth client ID - client_secret: OAuth client secret - tenant_id: Azure tenant ID (Azure only) - scope: OAuth scopes to request - redirect_uri: OAuth redirect URI - remote_user_fields: Fields to match users

property is_debug_enabled: bool

Check if debug logging is enabled.

property is_menu: bool

Check if shown in dropdown menu.

property button_style: dict[str, str | None]

Get login button styling properties.

Returns:

Dict with background_color, text_color, icon, icon_color.

property states: AuthSourceStateManager

Get a state manager scoped to this auth source.

Returns:

AuthSourceStateManager for this auth source.

enable_debug()

Enable debug logging for this auth source.

Debug mode automatically disables after 1 hour.

Returns:

Updated AuthSource object.

Return type:

AuthSource

disable_debug()

Disable debug logging for this auth source.

Returns:

Updated AuthSource object.

Return type:

AuthSource

refresh()

Refresh resource data from API.

Returns:

Updated AuthSource object.

Return type:

AuthSource

save(**kwargs)

Save changes to resource.

Parameters:

**kwargs (Any) – Fields to update.

Returns:

Updated AuthSource object.

Return type:

AuthSource

delete()

Delete this auth source.

This will fail if users or OIDC applications are using this source.

Return type:

None

class pyvergeos.resources.auth_sources.AuthSourceManager

Bases: ResourceManager[AuthSource]

Manager for authentication source operations.

Authentication sources enable SSO via external identity providers.

Example

>>> # List all auth sources
>>> for source in client.auth_sources.list():
...     print(f"{source.name} ({source.driver})")

>>> # Get a specific source
>>> source = client.auth_sources.get(name="Azure AD")

>>> # Create an auth source
>>> source = client.auth_sources.create(
...     name="Google",
...     driver="google",
...     settings={
...         "client_id": "your-client-id",
...         "client_secret": "your-secret",
...     }
... )

>>> # Update settings
>>> source = client.auth_sources.update(
...     source.key,
...     settings={"scope": "openid profile email groups"}
... )

>>> # Delete an auth source
>>> client.auth_sources.delete(source.key)

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, driver=None, **filter_kwargs)

List auth sources with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• driver (str | None) – Filter by driver type (azure, google, gitlab, etc.).

• **filter_kwargs (Any) – Shorthand filter arguments (name, etc.).

Returns:

List of AuthSource objects.

Return type:

list[AuthSource]

Example

>>> # List all sources
>>> sources = client.auth_sources.list()

>>> # List Azure sources only
>>> sources = client.auth_sources.list(driver="azure")

>>> # Filter by name pattern
>>> sources = client.auth_sources.list(name="Corporate*")

get(key=None, *, name=None, fields=None, include_settings=False)

Get a single auth source by key or name.

Parameters:

• key (int | None) – Auth source $key (row ID).

• name (str | None) – Auth source name.

• fields (list[str] | None) – List of fields to return.

• include_settings (bool) – Include settings JSON in response.

Returns:

AuthSource object.

Raises:

• NotFoundError – If source not found.

• ValueError – If no identifier provided.

Return type:

AuthSource

Example

>>> # Get by key
>>> source = client.auth_sources.get(1)

>>> # Get by name
>>> source = client.auth_sources.get(name="Azure AD")

>>> # Include settings
>>> source = client.auth_sources.get(1, include_settings=True)
>>> print(source.settings)

create(name, *, driver, settings=None, menu=False, button_background_color=None, button_color=None, button_fa_icon=None, icon_color=None)

Create a new authentication source.

Parameters:

• name (str) – Display name for the auth source (appears on login button).

• driver (str) – Provider type. One of: - azure: Azure Active Directory - google: Google OAuth - gitlab: GitLab (OpenID) - okta: Okta - openid: Generic OpenID Connect - openid-well-known: OpenID with well-known discovery - oauth2: Generic OAuth2 - verge.io: Verge.io parent system

• settings (dict[str, Any] | None) – Driver-specific configuration. Common fields: - client_id: OAuth client ID - client_secret: OAuth client secret - tenant_id: Azure tenant ID (Azure only) - scope: OAuth scopes (default: “openid profile email”) - remote_user_fields: Fields to match users - auto_create_users: Pattern for auto-creating users - update_remote_user: Update remote user ID after login - update_user_email: Update user email from provider - update_user_display_name: Update display name from provider - update_group_membership: Sync group membership

• menu (bool) – Show in dropdown menu instead of buttons.

• button_background_color (str | None) – Button background color (CSS value).

• button_color (str | None) – Button text color (CSS value).

• button_fa_icon (str | None) – Button icon (Bootstrap Icon class, e.g. “bi-google”).

• icon_color (str | None) – Button icon color (CSS value).

Returns:

Created AuthSource object.

Return type:

AuthSource

Example

>>> # Create Azure AD source
>>> source = client.auth_sources.create(
...     name="Corporate Azure",
...     driver="azure",
...     settings={
...         "tenant_id": "your-tenant-id",
...         "client_id": "your-client-id",
...         "client_secret": "your-client-secret",
...         "scope": "openid profile email",
...         "update_remote_user": True,
...         "update_user_email": True,
...     }
... )

>>> # Create Google source with custom styling
>>> source = client.auth_sources.create(
...     name="Sign in with Google",
...     driver="google",
...     settings={
...         "client_id": "your-client-id",
...         "client_secret": "your-secret",
...     },
...     button_background_color="#4285F4",
...     button_color="#ffffff",
...     button_fa_icon="bi-google",
... )

update(key, *, name=None, settings=None, menu=None, debug=None, button_background_color=None, button_color=None, button_fa_icon=None, icon_color=None)

Update an authentication source.

Note: The driver cannot be changed after creation.

Parameters:

• key (int) – Auth source $key (row ID).

• name (str | None) – New display name.

• settings (dict[str, Any] | None) – Updated settings (merged with existing).

• menu (bool | None) – Show in dropdown menu.

• debug (bool | None) – Enable/disable debug logging.

• button_background_color (str | None) – Button background color.

• button_color (str | None) – Button text color.

• button_fa_icon (str | None) – Button icon class.

• icon_color (str | None) – Button icon color.

Returns:

Updated AuthSource object.

Return type:

AuthSource

Example

>>> # Update settings
>>> source = client.auth_sources.update(
...     source.key,
...     settings={"scope": "openid profile email groups"}
... )

>>> # Enable debug mode
>>> source = client.auth_sources.update(source.key, debug=True)

delete(key)

Delete an authentication source.

This operation will fail if: - Users are assigned to this auth source - OIDC applications reference this auth source

Parameters:

key (int) – Auth source $key (row ID).

Raises:

• NotFoundError – If source not found.

• ConflictError – If source is in use by users or OIDC apps.

Return type:

None

Example

>>> client.auth_sources.delete(source.key)

states(key)

Get a state manager scoped to a specific auth source.

Parameters:

key (int) – Auth source $key (row ID).

Returns:

AuthSourceStateManager for the auth source.

Return type:

AuthSourceStateManager

OIDC Applications

Use VergeOS as an identity provider.

OIDC application management for VergeOS as identity provider.

OIDC applications enable VergeOS to act as an OpenID Connect identity provider, allowing other systems and tenants to authenticate through VergeOS.

Key concepts:

• OIDC Application: Configuration for a client that authenticates via VergeOS

• Client Credentials: Auto-generated client_id and client_secret for OAuth2 flow

• Redirect URIs: Allowed callback URLs for the OAuth2 flow

• Access Control: User/group ACLs to restrict who can use the application

Benefits:

• Central identity management across VergeOS systems and tenants

• Single sign-on (SSO) capabilities

• Can chain to upstream providers (Azure, Google, etc.)

• Reduces administrative burden for multi-system environments

Example

>>> # List all OIDC applications
>>> for app in client.oidc_applications.list():
...     print(f"{app.name}: {app.client_id}")

>>> # Create an OIDC application
>>> app = client.oidc_applications.create(
...     name="Tenant Portal",
...     redirect_uri="https://tenant.example.com/callback",
...     description="OIDC for tenant authentication",
... )
>>> print(f"Client ID: {app.client_id}")
>>> print(f"Client Secret: {app.client_secret}")

>>> # Get well-known configuration URL
>>> print(f"Well-known: {app.well_known_configuration}")

>>> # Restrict access to specific users
>>> app = client.oidc_applications.update(app.key, restrict_access=True)
>>> app.allowed_users.add(user_key=123)

class pyvergeos.resources.oidc_applications.OidcApplicationUser

Bases: ResourceObject

OIDC application user ACL entry.

Represents a user that is allowed to use an OIDC application when restrict_access is enabled.

key

Entry $key (row ID).

oidc_application

Parent application key.

user

Allowed user key.

property application_key: int | None

Get the parent OIDC application key.

property user_key: int | None

Get the allowed user key.

property user_display: str | None

Get the user display name.

delete()

Remove this user from allowed users.

Return type:

None

class pyvergeos.resources.oidc_applications.OidcApplicationUserManager

Bases: ResourceManager[OidcApplicationUser]

Manager for OIDC application user ACL operations.

Example

>>> # List allowed users for an application
>>> for entry in app.allowed_users.list():
...     print(f"{entry.user_display}")

>>> # Add a user
>>> app.allowed_users.add(user_key=123)

>>> # Remove a user
>>> entry.delete()

__init__(client, *, application_key=None)

Parameters:

• client (VergeClient)

• application_key (int | None)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, oidc_application=None, **filter_kwargs)

List allowed users with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• oidc_application (int | None) – Filter by application key. Ignored if scoped.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of OidcApplicationUser objects.

Return type:

list[OidcApplicationUser]

get(key=None, *, fields=None)

Get a single user ACL entry by key.

Parameters:

• key (int | None) – Entry $key (row ID).

• fields (list[str] | None) – List of fields to return.

Returns:

OidcApplicationUser object.

Raises:

• NotFoundError – If entry not found.

• ValueError – If key not provided.

Return type:

OidcApplicationUser

add(*, user_key)

Add a user to allowed users.

Parameters:

user_key (int) – User $key to add.

Returns:

Created OidcApplicationUser object.

Raises:

ValueError – If manager is not scoped to an application.

Return type:

OidcApplicationUser

delete(key)

Remove a user ACL entry.

Parameters:

key (int) – Entry $key (row ID).

Return type:

None

class pyvergeos.resources.oidc_applications.OidcApplicationGroup

Bases: ResourceObject

OIDC application group ACL entry.

Represents a group whose members are allowed to use an OIDC application when restrict_access is enabled.

key

Entry $key (row ID).

oidc_application

Parent application key.

group

Allowed group key.

property application_key: int | None

Get the parent OIDC application key.

property group_key: int | None

Get the allowed group key.

property group_display: str | None

Get the group display name.

delete()

Remove this group from allowed groups.

Return type:

None

class pyvergeos.resources.oidc_applications.OidcApplicationGroupManager

Bases: ResourceManager[OidcApplicationGroup]

Manager for OIDC application group ACL operations.

Example

>>> # List allowed groups for an application
>>> for entry in app.allowed_groups.list():
...     print(f"{entry.group_display}")

>>> # Add a group
>>> app.allowed_groups.add(group_key=456)

>>> # Remove a group
>>> entry.delete()

__init__(client, *, application_key=None)

Parameters:

• client (VergeClient)

• application_key (int | None)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, oidc_application=None, **filter_kwargs)

List allowed groups with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• oidc_application (int | None) – Filter by application key. Ignored if scoped.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of OidcApplicationGroup objects.

Return type:

list[OidcApplicationGroup]

get(key=None, *, fields=None)

Get a single group ACL entry by key.

Parameters:

• key (int | None) – Entry $key (row ID).

• fields (list[str] | None) – List of fields to return.

Returns:

OidcApplicationGroup object.

Raises:

• NotFoundError – If entry not found.

• ValueError – If key not provided.

Return type:

OidcApplicationGroup

add(*, group_key)

Add a group to allowed groups.

Parameters:

group_key (int) – Group $key to add.

Returns:

Created OidcApplicationGroup object.

Raises:

ValueError – If manager is not scoped to an application.

Return type:

OidcApplicationGroup

delete(key)

Remove a group ACL entry.

Parameters:

key (int) – Entry $key (row ID).

Return type:

None

class pyvergeos.resources.oidc_applications.OidcApplicationLog

Bases: ResourceObject

OIDC application log entry.

Represents an audit log entry for OIDC application operations.

key

Log entry $key (row ID).

oidc_application

Parent application key.

level

Log level (audit, message, warning, error, critical).

text

Log message text.

timestamp

Log timestamp (microseconds).

user

User who triggered the log.

property application_key: int | None

Get the parent application key.

property is_error: bool

Check if this is an error log entry.

property is_warning: bool

Check if this is a warning log entry.

property is_audit: bool

Check if this is an audit log entry.

class pyvergeos.resources.oidc_applications.OidcApplicationLogManager

Bases: ResourceManager[OidcApplicationLog]

Manager for OIDC application log operations.

Example

>>> # List all logs for an application
>>> for log in app.logs.list():
...     print(f"{log.level}: {log.text}")

>>> # List errors only
>>> errors = app.logs.list_errors()

__init__(client, *, application_key=None)

Parameters:

• client (VergeClient)

• application_key (int | None)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, oidc_application=None, level=None, **filter_kwargs)

List logs with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• oidc_application (int | None) – Filter by application key. Ignored if scoped.

• level (str | None) – Filter by log level.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of OidcApplicationLog objects.

Return type:

list[OidcApplicationLog]

get(key=None, *, fields=None)

Get a single log entry by key.

Parameters:

• key (int | None) – Log entry $key (row ID).

• fields (list[str] | None) – List of fields to return.

Returns:

OidcApplicationLog object.

Raises:

• NotFoundError – If entry not found.

• ValueError – If key not provided.

Return type:

OidcApplicationLog

list_errors(limit=None)

List error and critical log entries.

Parameters:

limit (int | None) – Maximum number of results.

Returns:

List of error/critical log entries.

Return type:

list[OidcApplicationLog]

list_warnings(limit=None)

List warning log entries.

Parameters:

limit (int | None) – Maximum number of results.

Returns:

List of warning log entries.

Return type:

list[OidcApplicationLog]

list_audits(limit=None)

List audit log entries.

Parameters:

limit (int | None) – Maximum number of results.

Returns:

List of audit log entries.

Return type:

list[OidcApplicationLog]

class pyvergeos.resources.oidc_applications.OidcApplication

Bases: ResourceObject

OIDC application resource object.

Represents an OIDC client application configuration for VergeOS acting as an identity provider.

key

Application $key (row ID).

name

Application name.

enabled

Whether the application is enabled.

created

Creation timestamp.

description

Application description.

redirect_uri

Allowed redirect URIs (newline-separated).

client_id

OAuth2 client ID (auto-generated).

client_secret

OAuth2 client secret (auto-generated).

force_auth_source

Auth source for auto-redirect.

restrict_access

Whether access is restricted to specific users/groups.

map_user

User to map all logins to.

scope_profile

Grant profile scope.

scope_email

Grant email scope.

scope_groups

Grant groups scope.

well_known_configuration

Well-known configuration URL.

property client_id: str | None

Get the OAuth2 client ID.

property client_secret: str | None

Get the OAuth2 client secret.

Note: This is only available if fetched with include_secret=True.

property is_enabled: bool

Check if the application is enabled.

property is_access_restricted: bool

Check if access is restricted to specific users/groups.

property redirect_uris: list[str]

Get redirect URIs as a list.

Redirect URIs are stored as newline-separated values.

property well_known_configuration: str | None

Get the OIDC well-known configuration URL.

property scopes: list[str]

Get enabled scopes as a list.

property force_auth_source_key: int | None

Get the forced auth source key for auto-redirect.

property map_user_key: int | None

Get the mapped user key.

property allowed_users: OidcApplicationUserManager

Get a user ACL manager scoped to this application.

Returns:

OidcApplicationUserManager for this application.

property allowed_groups: OidcApplicationGroupManager

Get a group ACL manager scoped to this application.

Returns:

OidcApplicationGroupManager for this application.

property logs: OidcApplicationLogManager

Get a log manager scoped to this application.

Returns:

OidcApplicationLogManager for this application.

enable()

Enable this OIDC application.

Returns:

Updated OidcApplication object.

Return type:

OidcApplication

disable()

Disable this OIDC application.

Returns:

Updated OidcApplication object.

Return type:

OidcApplication

refresh()

Refresh resource data from API.

Returns:

Updated OidcApplication object.

Return type:

OidcApplication

save(**kwargs)

Save changes to resource.

Parameters:

**kwargs (Any) – Fields to update.

Returns:

Updated OidcApplication object.

Return type:

OidcApplication

delete()

Delete this OIDC application.

Return type:

None

class pyvergeos.resources.oidc_applications.OidcApplicationManager

Bases: ResourceManager[OidcApplication]

Manager for OIDC application operations.

OIDC applications enable VergeOS to act as an identity provider.

Example

>>> # List all OIDC applications
>>> for app in client.oidc_applications.list():
...     print(f"{app.name}: {app.client_id}")

>>> # Get a specific application
>>> app = client.oidc_applications.get(name="Tenant Portal")

>>> # Create an application
>>> app = client.oidc_applications.create(
...     name="Partner Portal",
...     redirect_uri="https://partner.example.com/callback",
...     description="OIDC for partner authentication",
... )
>>> print(f"Client ID: {app.client_id}")
>>> print(f"Client Secret: {app.client_secret}")

>>> # Restrict access to specific users
>>> app = client.oidc_applications.update(app.key, restrict_access=True)
>>> app.allowed_users.add(user_key=123)

>>> # Delete an application
>>> client.oidc_applications.delete(app.key)

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, enabled=None, **filter_kwargs)

List OIDC applications with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• enabled (bool | None) – Filter by enabled state.

• **filter_kwargs (Any) – Shorthand filter arguments (name, etc.).

Returns:

List of OidcApplication objects.

Return type:

list[OidcApplication]

Example

>>> # List all applications
>>> apps = client.oidc_applications.list()

>>> # List enabled applications only
>>> apps = client.oidc_applications.list(enabled=True)

>>> # Filter by name pattern
>>> apps = client.oidc_applications.list(name="Tenant*")

get(key=None, *, name=None, fields=None, include_secret=False, include_well_known=False)

Get a single OIDC application by key or name.

Parameters:

• key (int | None) – Application $key (row ID).

• name (str | None) – Application name.

• fields (list[str] | None) – List of fields to return.

• include_secret (bool) – Include client_secret in response.

• include_well_known (bool) – Include well_known_configuration in response.

Returns:

OidcApplication object.

Raises:

• NotFoundError – If application not found.

• ValueError – If no identifier provided.

Return type:

OidcApplication

Example

>>> # Get by key
>>> app = client.oidc_applications.get(1)

>>> # Get by name with secret
>>> app = client.oidc_applications.get(
...     name="Tenant Portal",
...     include_secret=True
... )
>>> print(app.client_secret)

create(name, *, redirect_uri=None, description=None, enabled=True, force_auth_source=None, restrict_access=False, map_user=None, scope_profile=True, scope_email=True, scope_groups=True)

Create a new OIDC application.

The client_id and client_secret are auto-generated and returned in the created object.

Parameters:

• name (str) – Application name.

• redirect_uri (str | list[str] | None) – Allowed redirect URIs (string or list of strings). Wildcards supported (e.g., https://*.example.com).

• description (str | None) – Application description.

• enabled (bool) – Whether the application is enabled.

• force_auth_source (int | None) – Auth source key for auto-redirect.

• restrict_access (bool) – Restrict access to specific users/groups.

• map_user (int | None) – User key to map all logins to.

• scope_profile (bool) – Grant profile scope (read user name).

• scope_email (bool) – Grant email scope (read user email).

• scope_groups (bool) – Grant groups scope (read group membership).

Returns:

Created OidcApplication object with client credentials.

Return type:

OidcApplication

Example

>>> app = client.oidc_applications.create(
...     name="Partner Portal",
...     redirect_uri=[
...         "https://portal.example.com/callback",
...         "https://staging.example.com/callback",
...     ],
...     description="OIDC for partner authentication",
... )
>>> print(f"Client ID: {app.client_id}")
>>> print(f"Client Secret: {app.client_secret}")

update(key, *, name=None, redirect_uri=None, description=None, enabled=None, force_auth_source=None, restrict_access=None, map_user=None, scope_profile=None, scope_email=None, scope_groups=None)

Update an OIDC application.

Note: client_id and client_secret cannot be changed.

Parameters:

• key (int) – Application $key (row ID).

• name (str | None) – New application name.

• redirect_uri (str | list[str] | None) – Updated redirect URIs.

• description (str | None) – New description.

• enabled (bool | None) – Enable or disable.

• force_auth_source (int | None) – Auth source for auto-redirect.

• restrict_access (bool | None) – Restrict to specific users/groups.

• map_user (int | None) – User to map all logins to.

• scope_profile (bool | None) – Grant profile scope.

• scope_email (bool | None) – Grant email scope.

• scope_groups (bool | None) – Grant groups scope.

Returns:

Updated OidcApplication object.

Return type:

OidcApplication

Example

>>> # Update redirect URIs
>>> app = client.oidc_applications.update(
...     app.key,
...     redirect_uri="https://new.example.com/callback"
... )

>>> # Enable access restriction
>>> app = client.oidc_applications.update(
...     app.key,
...     restrict_access=True
... )

delete(key)

Delete an OIDC application.

Parameters:

key (int) – Application $key (row ID).

Raises:

NotFoundError – If application not found.

Return type:

None

Example

>>> client.oidc_applications.delete(app.key)

allowed_users(key)

Get a user ACL manager scoped to a specific application.

Parameters:

key (int) – Application $key (row ID).

Returns:

OidcApplicationUserManager for the application.

Return type:

OidcApplicationUserManager

allowed_groups(key)

Get a group ACL manager scoped to a specific application.

Parameters:

key (int) – Application $key (row ID).

Returns:

OidcApplicationGroupManager for the application.

Return type:

OidcApplicationGroupManager

logs(key)

Get a log manager scoped to a specific application.

Parameters:

key (int) – Application $key (row ID).

Returns:

OidcApplicationLogManager for the application.

Return type:

OidcApplicationLogManager

Certificates

Certificate resource manager for VergeOS SSL/TLS certificate management.

class pyvergeos.resources.certificates.Certificate

Bases: ResourceObject

SSL/TLS certificate resource object.

Represents an SSL/TLS certificate in VergeOS. Certificates can be: - Manual: Uploaded certificate with public/private keys - Let’s Encrypt: Automatically managed via ACME protocol - Self-Signed: Self-signed certificate generated by VergeOS

Properties:

domain: Primary domain name for the certificate. domain_name: Alternative accessor for domain name. domain_list: List of Subject Alternative Names (SANs). description: Certificate description. cert_type: Certificate type (API value). cert_type_display: Friendly certificate type name. key_type: Key type (ecdsa or rsa). key_type_display: Friendly key type name. rsa_key_size: RSA key size (if RSA key type). acme_server: ACME server URL (for Let’s Encrypt). contact_user_key: Contact user key (for Let’s Encrypt). is_tos_agreed: Whether TOS is accepted (for Let’s Encrypt). is_valid: Whether certificate is valid (not expired). is_auto_created: Whether certificate was auto-created by system. expires_at: Expiration datetime. created_at: Creation datetime. modified_at: Last modified datetime. days_until_expiry: Days until certificate expires. public_key: Public certificate (PEM format, if loaded). private_key: Private key (PEM format, if loaded). chain: Certificate chain (PEM format, if loaded).

property domain: str

Get primary domain name.

property domain_name: str

Get domain name (alias for domain).

property domain_list: list[str]

Get list of Subject Alternative Names.

property description: str

Get certificate description.

property cert_type: str

Get certificate type (API value).

property cert_type_display: str

Get friendly certificate type name.

property key_type: str

Get key type (API value).

property key_type_display: str

Get friendly key type name.

property rsa_key_size: int | None

Get RSA key size (if RSA key type).

property acme_server: str

Get ACME server URL (for Let’s Encrypt).

property contact_user_key: int | None

Get contact user key (for Let’s Encrypt).

property is_tos_agreed: bool

Check if Terms of Service is accepted.

property is_valid: bool

Check if certificate is valid (not expired).

property is_auto_created: bool

Check if certificate was auto-created by system.

property expires_at: datetime | None

Get expiration datetime.

property created_at: datetime | None

Get creation datetime.

property modified_at: datetime | None

Get last modified datetime.

property days_until_expiry: int | None

Get days until certificate expires.

property public_key: str | None

Get public certificate (PEM format, if loaded).

property private_key: str | None

Get private key (PEM format, if loaded).

property chain: str | None

Get certificate chain (PEM format, if loaded).

refresh()

Refresh certificate data from API.

Returns:

Updated Certificate object.

Return type:

Certificate

save(**kwargs)

Update certificate with new values.

Parameters:

**kwargs (Any) – Fields to update.

Returns:

Updated Certificate object.

Return type:

Certificate

delete()

Delete this certificate.

Return type:

None

renew(*, force=False)

Renew or regenerate this certificate.

For Let’s Encrypt certificates, triggers ACME renewal. For self-signed certificates, regenerates with a new key pair.

Parameters:

force (bool) – Force renewal even if not near expiration.

Returns:

Updated Certificate object after renewal.

Return type:

Certificate

class pyvergeos.resources.certificates.CertificateManager

Bases: ResourceManager[Certificate]

Manager for SSL/TLS certificates.

Provides CRUD operations for SSL/TLS certificates including manual uploads, Let’s Encrypt (ACME) certificates, and self-signed certificates.

Example

>>> # List all certificates
>>> certs = client.certificates.list()
>>>
>>> # Get a specific certificate
>>> cert = client.certificates.get(domain="example.com")
>>>
>>> # Create a self-signed certificate
>>> cert = client.certificates.create(
...     domain="internal.local",
...     cert_type="SelfSigned",
...     description="Internal services"
... )
>>>
>>> # Create a Let's Encrypt certificate
>>> cert = client.certificates.create(
...     domain="public.example.com",
...     cert_type="LetsEncrypt",
...     agree_tos=True,
...     contact_user_key=1
... )
>>>
>>> # Renew a certificate
>>> cert = client.certificates.renew(cert.key, force=True)

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, cert_type=None, valid=None, include_keys=False, **filter_kwargs)

List certificates with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• cert_type (str | None) – Filter by certificate type (Manual, LetsEncrypt, SelfSigned).

• valid (bool | None) – Filter by valid status (True for valid only).

• include_keys (bool) – Include sensitive key material (public, private, chain).

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of Certificate objects.

Return type:

list[Certificate]

list_valid(**kwargs)

List only valid (unexpired) certificates.

Parameters:

**kwargs (Any) – Additional arguments passed to list().

Returns:

List of valid Certificate objects.

Return type:

list[Certificate]

list_by_type(cert_type, **kwargs)

List certificates by type.

Parameters:

• cert_type (str) – Certificate type (Manual, LetsEncrypt, SelfSigned).

• **kwargs (Any) – Additional arguments passed to list().

Returns:

List of Certificate objects.

Return type:

list[Certificate]

list_expiring(days=30, **kwargs)

List certificates expiring within specified days.

Parameters:

• days (int) – Number of days threshold.

• **kwargs (Any) – Additional arguments passed to list().

Returns:

List of Certificate objects expiring within the threshold.

Return type:

list[Certificate]

list_expired(**kwargs)

List expired certificates.

Parameters:

**kwargs (Any) – Additional arguments passed to list().

Returns:

List of expired Certificate objects.

Return type:

list[Certificate]

get(key=None, *, domain=None, fields=None, include_keys=False)

Get a certificate by key or domain.

Parameters:

• key (int | None) – Certificate $key (ID).

• domain (str | None) – Domain name (exact match).

• fields (list[str] | None) – List of fields to return.

• include_keys (bool) – Include sensitive key material.

Returns:

Certificate object.

Raises:

• NotFoundError – If certificate not found.

• ValueError – If neither key nor domain provided.

Return type:

Certificate

create(domain, *, cert_type='SelfSigned', domain_list=None, description=None, public_key=None, private_key=None, chain=None, acme_server=None, eab_key_id=None, eab_hmac_key=None, key_type=None, rsa_key_size=None, contact_user_key=None, agree_tos=False)

Create a new SSL/TLS certificate.

Parameters:

• domain (str) – Primary domain name for the certificate.

• cert_type (str) – Certificate type (Manual, LetsEncrypt, SelfSigned). Default is SelfSigned.

• domain_list (list[str] | str | None) – Additional domains (SANs) as list or comma-separated string.

• description (str | None) – Certificate description.

• public_key (str | None) – Public certificate in PEM format (required for Manual).

• private_key (str | None) – Private key in PEM format (required for Manual).

• chain (str | None) – Certificate chain in PEM format (optional for Manual).

• acme_server (str | None) – ACME server URL (for Let’s Encrypt).

• eab_key_id (str | None) – External Account Binding key ID (for some ACME providers).

• eab_hmac_key (str | None) – External Account Binding HMAC key.

• key_type (str | None) – Key type (ECDSA or RSA). Default is ECDSA.

• rsa_key_size (int | None) – RSA key size (2048, 3072, or 4096). Default is 2048.

• contact_user_key (int | None) – Contact user $key for Let’s Encrypt.

• agree_tos (bool) – Accept Let’s Encrypt Terms of Service (required for LE).

Returns:

Created Certificate object.

Raises:

• ValidationError – If parameters invalid.

• ConflictError – If certificate for domain already exists.

• ValueError – If required parameters missing for certificate type.

Return type:

Certificate

update(key, *, description=None, domain_list=None, public_key=None, private_key=None, chain=None, acme_server=None, eab_key_id=None, eab_hmac_key=None, key_type=None, rsa_key_size=None, contact_user_key=None, agree_tos=None)

Update a certificate.

Parameters:

• key (int) – Certificate $key (ID).

• description (str | None) – New certificate description.

• domain_list (list[str] | str | None) – New additional domains (SANs).

• public_key (str | None) – New public certificate (PEM format, manual certs only).

• private_key (str | None) – New private key (PEM format, manual certs only).

• chain (str | None) – New certificate chain (PEM format, manual certs only).

• acme_server (str | None) – New ACME server URL (Let’s Encrypt only).

• eab_key_id (str | None) – New External Account Binding key ID.

• eab_hmac_key (str | None) – New External Account Binding HMAC key.

• key_type (str | None) – New key type (ECDSA or RSA).

• rsa_key_size (int | None) – New RSA key size (2048, 3072, or 4096).

• contact_user_key (int | None) – New contact user $key.

• agree_tos (bool | None) – Accept Terms of Service.

Returns:

Updated Certificate object.

Raises:

• NotFoundError – If certificate not found.

• ValidationError – If parameters invalid.

Return type:

Certificate

delete(key)

Delete a certificate.

Parameters:

key (int) – Certificate $key (ID).

Raises:

NotFoundError – If certificate not found.

Return type:

None

renew(key, *, force=False)

Renew or regenerate a certificate.

For Let’s Encrypt certificates, triggers ACME renewal. For self-signed certificates, regenerates with a new key pair. Manual certificates cannot be renewed (upload new keys instead).

Parameters:

• key (int) – Certificate $key (ID).

• force (bool) – Force renewal even if not near expiration.

Returns:

Updated Certificate object after renewal.

Raises:

• NotFoundError – If certificate not found.

• ValueError – If certificate type doesn’t support renewal.

Return type:

Certificate

refresh(key)

Alias for renew() - refresh/renew a certificate.

Parameters:

key (int) – Certificate $key (ID).

Returns:

Updated Certificate object after renewal.

Return type:

Certificate

System

System Management

System management for VergeOS - settings, statistics, licenses, diagnostics, and inventory.

class pyvergeos.resources.system.SystemSetting

Bases: ResourceObject

Represents a system setting in VergeOS.

System settings are key-value pairs that control various aspects of VergeOS behavior.

property key: str

Setting key (unique identifier).

property value: str | None

Current setting value.

property default_value: str | None

Default setting value.

property description: str

Setting description.

property is_modified: bool

Whether the setting has been modified from default.

class pyvergeos.resources.system.SettingsManager

Bases: ResourceManager[SystemSetting]

Manages system settings in VergeOS.

Settings control various aspects of VergeOS behavior including connection limits, API rate limits, UI settings, and more.

Example

>>> # List all settings
>>> for setting in client.settings.list():
...     print(f"{setting.key}: {setting.value}")

>>> # Get a specific setting
>>> setting = client.settings.get("max_connections")
>>> print(f"Max connections: {setting.value}")

>>> # Find modified settings
>>> modified = [s for s in client.settings.list() if s.is_modified]

list(filter=None, fields=None, key_contains=None, **filter_kwargs)

List system settings.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• key_contains (str | None) – Filter settings where key contains this string.

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of SystemSetting objects.

Return type:

list[SystemSetting]

Example

>>> # List all settings
>>> settings = client.settings.list()

>>> # List UI-related settings
>>> ui_settings = client.settings.list(key_contains="ui_")

get(key=None, *, fields=None)

Get a system setting by key.

Parameters:

• key (str | None) – Setting key name (e.g., “max_connections”).

• fields (list[str] | None) – List of fields to return.

Returns:

SystemSetting object.

Raises:

• NotFoundError – If setting not found.

• ValueError – If key not provided.

Return type:

SystemSetting

Example

>>> setting = client.settings.get("max_connections")
>>> print(f"Value: {setting.value}, Default: {setting.default_value}")

update(key, value)

Update a system setting value.

Parameters:

• key (str) – Setting key name (e.g., “max_connections”).

• value (str) – New value for the setting.

Returns:

Updated SystemSetting object.

Raises:

• NotFoundError – If setting not found.

• ValueError – If key not provided.

Return type:

SystemSetting

Example

>>> setting = client.system.settings.update("max_connections", "1000")
>>> print(f"New value: {setting.value}")

reset(key)

Reset a system setting to its default value.

Parameters:

key (str) – Setting key name.

Returns:

Updated SystemSetting object with default value.

Raises:

NotFoundError – If setting not found.

Return type:

SystemSetting

Example

>>> setting = client.system.settings.reset("max_connections")
>>> print(f"Reset to: {setting.value}")

list_modified()

List only settings that have been modified from defaults.

Returns:

List of modified SystemSetting objects.

Return type:

list[SystemSetting]

Example

>>> for setting in client.system.settings.list_modified():
...     print(f"{setting.key}: {setting.value} (default: {setting.default_value})")

class pyvergeos.resources.system.License

Bases: ResourceObject

Represents a license in VergeOS.

Licenses control feature availability and system capabilities.

property name: str

License name.

property description: str

License description.

property features: dict[str, Any] | None

License features as a dictionary.

property is_valid: bool

Whether the license is currently valid.

property valid_from: datetime | None

License validity start date.

property valid_until: datetime | None

License validity end date.

property issued: datetime | None

When the license was issued.

property added: datetime | None

When the license was added to the system.

property added_by: str

User who added the license.

property allow_branding: bool

Whether branding is allowed.

property auto_renewal: bool

Whether auto-renewal is enabled.

property note: str

License note.

class pyvergeos.resources.system.LicenseManager

Bases: ResourceManager[License]

Manages licenses in VergeOS.

Licenses control which features are available and the capabilities of the VergeOS system.

Example

>>> # List all licenses
>>> for lic in client.licenses.list():
...     print(f"{lic.name}: {'valid' if lic.is_valid else 'invalid'}")

>>> # Get license details
>>> lic = client.licenses.get(name="Production")
>>> print(f"Valid until: {lic.valid_until}")

list(filter=None, fields=None, name=None, **filter_kwargs)

List licenses.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• name (str | None) – Filter by license name (supports wildcards).

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of License objects.

Return type:

list[License]

Example

>>> # List all licenses
>>> licenses = client.licenses.list()

>>> # Filter by name
>>> prod_licenses = client.licenses.list(name="Production")

get(key=None, *, name=None, fields=None)

Get a license by key or name.

Parameters:

• key (int | None) – License $key.

• name (str | None) – License name - alternative to key.

• fields (list[str] | None) – List of fields to return.

Returns:

License object.

Raises:

• NotFoundError – If license not found.

• ValueError – If neither key nor name provided.

Return type:

License

Example

>>> lic = client.licenses.get(name="Production")
>>> print(f"Features: {lic.features}")

generate_payload()

Generate a license request payload for air-gapped systems.

For systems without internet connectivity, this generates a payload that can be sent to Verge.io support to obtain a license file.

Returns:

License request payload as a string.

Raises:

APIError – If payload generation fails.

Return type:

str

Example

>>> payload = client.system.licenses.generate_payload()
>>> # Save payload to a file and send to support
>>> with open("license_request.txt", "w") as f:
...     f.write(payload)

add(license_text)

Add a new license to the system.

Parameters:

license_text (str) – The license text/key provided by Verge.io.

Returns:

The newly added License object.

Raises:

• ValidationError – If the license is invalid.

• ConflictError – If the license already exists.

Return type:

License

Example

>>> license_data = open("license.txt").read()
>>> lic = client.system.licenses.add(license_data)
>>> print(f"Added license: {lic.name}")

class pyvergeos.resources.system.SystemStatistics

Bases: object

System dashboard statistics.

Contains counts and status information for all major resource types.

__init__(data)

Parameters:

data (dict[str, Any])

Return type:

None

property vms_total: int

Total number of VMs.

property vms_online: int

Number of online VMs.

property vms_warning: int

Number of VMs with warnings.

property vms_error: int

Number of VMs with errors.

property tenants_total: int

Total number of tenants.

property tenants_online: int

Number of online tenants.

property tenants_warning: int

Number of tenants with warnings.

property tenants_error: int

Number of tenants with errors.

property networks_total: int

Total number of networks.

property networks_online: int

Number of online networks.

property networks_warning: int

Number of networks with warnings.

property networks_error: int

Number of networks with errors.

property nodes_total: int

Total number of nodes.

property nodes_online: int

Number of online nodes.

property nodes_warning: int

Number of nodes with warnings.

property nodes_error: int

Number of nodes with errors.

property clusters_total: int

Total number of clusters.

property clusters_online: int

Number of online clusters.

property clusters_warning: int

Number of clusters with warnings.

property clusters_error: int

Number of clusters with errors.

property storage_tiers_total: int

Total number of storage tiers.

property cluster_tiers_total: int

Total number of cluster tiers.

property cluster_tiers_online: int

Number of online cluster tiers.

property cluster_tiers_warning: int

Number of cluster tiers with warnings.

property cluster_tiers_error: int

Number of cluster tiers with errors.

property users_total: int

Total number of users.

property users_enabled: int

Number of enabled users.

property groups_total: int

Total number of groups.

property groups_enabled: int

Number of enabled groups.

property sites_total: int

Total number of sites.

property sites_online: int

Number of online sites.

property sites_warning: int

Number of sites with warnings.

property sites_error: int

Number of sites with errors.

property repositories_total: int

Total number of repositories.

property repositories_online: int

Number of online repositories.

property repositories_warning: int

Number of repositories with warnings.

property repositories_error: int

Number of repositories with errors.

property alarms_total: int

Total number of active alarms.

property alarms_warning: int

Number of warning alarms.

property alarms_error: int

Number of error/critical alarms.

property resource_instance_count: int

Current resource instance count.

property resource_instance_max: int

Maximum resource instances.

to_dict()

Return statistics as a dictionary.

Return type:

dict[str, Any]

class pyvergeos.resources.system.InventoryVM

Bases: object

VM inventory item.

__init__(data)

Parameters:

data (dict[str, Any])

Return type:

None

property key: int

Unique identifier for the VM.

property name: str

VM name.

property description: str

VM description.

property power_state: str

Current power state (e.g., ‘running’, ‘stopped’).

property cpu_cores: int

Number of CPU cores allocated to the VM.

property ram_mb: int

RAM allocated to the VM in megabytes.

property ram_gb: float

RAM allocated to the VM in gigabytes.

property os_family: str

Operating system family (e.g., ‘linux’, ‘windows’).

property cluster: str

Name of the cluster hosting this VM.

property node: str

Name of the node hosting this VM.

class pyvergeos.resources.system.InventoryNetwork

Bases: object

Network inventory item.

__init__(data)

Parameters:

data (dict[str, Any])

Return type:

None

property key: int

Unique identifier for the network.

property name: str

Network name.

property description: str

Network description.

property network_type: str

Type of network (e.g., ‘internal’, ‘external’).

property power_state: str

Current power state (e.g., ‘running’, ‘stopped’).

property network_address: str

Network address in CIDR notation.

property ip_address: str

IP address assigned to the network interface.

class pyvergeos.resources.system.InventoryStorageTier

Bases: object

Storage tier inventory item.

__init__(data)

Parameters:

data (dict[str, Any])

Return type:

None

property tier: int

Storage tier number.

property description: str

Storage tier description.

property capacity_bytes: int

Total capacity of the storage tier in bytes.

property capacity_gb: float

Total capacity of the storage tier in gigabytes.

property used_bytes: int

Used space in the storage tier in bytes.

property used_gb: float

Used space in the storage tier in gigabytes.

property used_percent: float

Percentage of storage tier capacity currently in use.

class pyvergeos.resources.system.InventoryNode

Bases: object

Node inventory item.

__init__(data)

Parameters:

data (dict[str, Any])

Return type:

None

property key: int

Unique identifier for the node.

property name: str

Node name.

property status: str

Current node status.

property cluster: str

Name of the cluster this node belongs to.

property cores: int

Number of CPU cores available on the node.

property ram_mb: int

Total RAM on the node in megabytes.

property ram_gb: float

Total RAM on the node in gigabytes.

class pyvergeos.resources.system.InventoryCluster

Bases: object

Cluster inventory item.

__init__(data)

Parameters:

data (dict[str, Any])

Return type:

None

property key: int

Unique identifier for the cluster.

property name: str

Cluster name.

property description: str

Cluster description.

property status: str

Current cluster status.

property total_nodes: int

Total number of nodes in the cluster.

property online_nodes: int

Number of nodes currently online in the cluster.

class pyvergeos.resources.system.InventoryTenant

Bases: object

Tenant inventory item.

__init__(data)

Parameters:

data (dict[str, Any])

Return type:

None

property key: int

Unique identifier for the tenant.

property name: str

Tenant name.

property description: str

Tenant description.

property status: str

Current tenant status.

property is_running: bool

Whether the tenant is currently running.

class pyvergeos.resources.system.SystemInventory

Bases: object

System inventory containing all resource types.

Similar to RVtools for VMware, this provides a comprehensive view of all VergeOS resources.

__init__(vms, networks, storage, nodes, clusters, tenants, generated_at)

Parameters:

• vms (list[InventoryVM])

• networks (list[InventoryNetwork])

• storage (list[InventoryStorageTier])

• nodes (list[InventoryNode])

• clusters (list[InventoryCluster])

• tenants (list[InventoryTenant])

• generated_at (datetime)

Return type:

None

property summary: dict[str, Any]

Get a summary of the inventory.

class pyvergeos.resources.system.SystemDiagnostic

Bases: ResourceObject

Represents a system diagnostic report in VergeOS.

System diagnostics capture comprehensive system information including logs, configuration, network state, and other metrics useful for troubleshooting.

Properties:

name: Diagnostic report name. description: Report description. status: Current status (initializing, building, uploading, complete, error). status_display: Human-readable status. status_info: Additional status information (e.g., current node being processed). file_key: Associated file $key for download. is_complete: Whether the diagnostic build is complete. is_building: Whether the diagnostic is currently building. has_error: Whether the diagnostic encountered an error. created_at: When the diagnostic was created.

property name: str

Diagnostic report name.

property description: str

Report description.

property status: str

Current status (API value).

property status_display: str

Human-readable status.

property status_info: str

Additional status information.

property file_key: int | None

Associated file $key for download.

property is_complete: bool

Whether the diagnostic build is complete.

property is_building: bool

Whether the diagnostic is currently building.

property has_error: bool

Whether the diagnostic encountered an error.

property created_at: datetime | None

When the diagnostic was created.

refresh()

Refresh diagnostic data from API.

Returns:

Updated SystemDiagnostic object.

Return type:

SystemDiagnostic

send_to_support()

Send this diagnostic report to Verge.io support.

Requires the diagnostic to be complete.

Raises:

ValueError – If diagnostic is not complete.

Return type:

None

wait_for_completion(timeout=300, poll_interval=2)

Wait for the diagnostic build to complete.

Parameters:

• timeout (float) – Maximum time to wait in seconds.

• poll_interval (float) – Time between status checks in seconds.

Returns:

The completed SystemDiagnostic object.

Raises:

TaskTimeoutError – If timeout is reached before completion.

Return type:

SystemDiagnostic

delete()

Delete this diagnostic report.

Return type:

None

class pyvergeos.resources.system.SystemDiagnosticManager

Bases: ResourceManager[SystemDiagnostic]

Manages system diagnostic reports in VergeOS.

System diagnostics capture comprehensive system information for troubleshooting and support purposes.

Example

>>> # Build a new diagnostic report
>>> diag = client.system.diagnostics.build(
...     name="Support Case #12345",
...     description="Network connectivity issue",
...     send_to_support=True
... )
>>>
>>> # Wait for completion
>>> diag = diag.wait_for_completion()
>>> print(f"Status: {diag.status_display}")
>>>
>>> # List all diagnostics
>>> for d in client.system.diagnostics.list():
...     print(f"{d.name}: {d.status_display}")

list(filter=None, fields=None, limit=None, offset=None, *, status=None, **filter_kwargs)

List system diagnostic reports.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• status (str | None) – Filter by status (initializing, building, complete, error).

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of SystemDiagnostic objects.

Return type:

list[SystemDiagnostic]

Example

>>> # List all diagnostics
>>> diagnostics = client.system.diagnostics.list()
>>>
>>> # List completed diagnostics only
>>> completed = client.system.diagnostics.list(status="complete")

get(key, *, fields=None)

Get a diagnostic report by key.

Parameters:

• key (int) – Diagnostic $key.

• fields (list[str] | None) – List of fields to return.

Returns:

SystemDiagnostic object.

Raises:

NotFoundError – If diagnostic not found.

Return type:

SystemDiagnostic

build(name=None, description=None, *, send_to_support=False)

Build a new system diagnostic report.

Triggers collection of comprehensive system information from all nodes. This operation may take several minutes depending on system size.

Parameters:

• name (str | None) – Report name. If not provided, auto-generated with timestamp.

• description (str | None) – Report description.

• send_to_support (bool) – If True, automatically send to Verge.io support when complete (requires internet connectivity).

Returns:

The new SystemDiagnostic object (initially in ‘initializing’ status).

Return type:

SystemDiagnostic

Example

>>> # Build diagnostic for support case
>>> diag = client.system.diagnostics.build(
...     name="Support-12345",
...     description="High CPU usage investigation",
...     send_to_support=True
... )
>>> diag = diag.wait_for_completion()

send_to_support(key)

Send a diagnostic report to Verge.io support.

The diagnostic must be complete before sending.

Parameters:

key (int) – Diagnostic $key.

Raises:

• NotFoundError – If diagnostic not found.

• ValueError – If diagnostic is not complete.

Return type:

None

delete(key)

Delete a diagnostic report.

Parameters:

key (int) – Diagnostic $key.

Raises:

NotFoundError – If diagnostic not found.

Return type:

None

update(key, *, name=None, description=None)

Update a diagnostic report’s name or description.

Parameters:

• key (int) – Diagnostic $key.

• name (str | None) – New name.

• description (str | None) – New description.

Returns:

Updated SystemDiagnostic object.

Raises:

NotFoundError – If diagnostic not found.

Return type:

SystemDiagnostic

get_download_url(key)

Get the download URL for a completed diagnostic file.

Parameters:

key (int) – Diagnostic $key.

Returns:

Download URL string, or None if file not available.

Raises:

• NotFoundError – If diagnostic not found.

• ValueError – If diagnostic is not complete.

Return type:

str | None

class pyvergeos.resources.system.RootCertificate

Bases: ResourceObject

Represents a trusted root certificate authority in VergeOS.

Root certificates are added to the system’s trust store to enable secure connections to systems using private/internal CA certificates.

Properties:

subject: Certificate subject (common name, organization, etc.). issuer: Certificate issuer. fingerprint: Certificate fingerprint (SHA-256). start_date: Certificate validity start date. end_date: Certificate validity end date. cert_pem: Certificate in PEM format. modified_at: When the certificate was last modified.

property subject: str

Certificate subject.

property issuer: str

Certificate issuer.

property fingerprint: str

Certificate fingerprint.

property start_date: str

Certificate validity start date.

property end_date: str

Certificate validity end date.

property cert_pem: str

Certificate in PEM format.

property modified_at: datetime | None

When the certificate was last modified.

delete()

Delete this root certificate.

Return type:

None

class pyvergeos.resources.system.RootCertificateManager

Bases: ResourceManager[RootCertificate]

Manages trusted root certificates in VergeOS.

Root certificates allow adding custom Certificate Authorities to the system’s trust store, enabling secure connections to systems using private/enterprise CA certificates.

Common use cases: - Enabling secure site syncs with internal CA certificates - Trusting enterprise PKI for LDAP/AD connections - Development environments with self-signed CAs

Example

>>> # Add a root CA
>>> ca_cert = open("enterprise-ca.pem").read()
>>> root_ca = client.system.root_certificates.create(cert=ca_cert)
>>> print(f"Added CA: {root_ca.subject}")
>>>
>>> # List trusted CAs
>>> for ca in client.system.root_certificates.list():
...     print(f"{ca.subject} (expires: {ca.end_date})")

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List trusted root certificates.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of RootCertificate objects.

Return type:

list[RootCertificate]

Example

>>> # List all trusted CAs
>>> for ca in client.system.root_certificates.list():
...     print(f"{ca.subject}")

get(key, *, fields=None)

Get a root certificate by key.

Parameters:

• key (int) – Certificate $key.

• fields (list[str] | None) – List of fields to return.

Returns:

RootCertificate object.

Raises:

NotFoundError – If certificate not found.

Return type:

RootCertificate

get_by_subject(subject)

Get a root certificate by subject.

Parameters:

subject (str) – Certificate subject (partial match supported).

Returns:

RootCertificate object.

Raises:

NotFoundError – If certificate not found.

Return type:

RootCertificate

get_by_fingerprint(fingerprint)

Get a root certificate by fingerprint.

Parameters:

fingerprint (str) – Certificate fingerprint.

Returns:

RootCertificate object.

Raises:

NotFoundError – If certificate not found.

Return type:

RootCertificate

create(cert)

Add a new trusted root certificate.

Parameters:

cert (str) – Certificate in PEM format.

Returns:

The new RootCertificate object.

Raises:

• ValidationError – If the certificate is invalid.

• ConflictError – If the certificate already exists.

Return type:

RootCertificate

Example

>>> ca_cert = '''-----BEGIN CERTIFICATE-----
... MIIDXTCCAkWgAwIBAgIJAJC1...
... -----END CERTIFICATE-----'''
>>> root_ca = client.system.root_certificates.create(cert=ca_cert)

delete(key)

Delete a root certificate.

Parameters:

key (int) – Certificate $key.

Raises:

NotFoundError – If certificate not found.

Return type:

None

class pyvergeos.resources.system.SystemManager

Bases: object

Provides system-level operations in VergeOS.

Includes access to settings, statistics, licenses, diagnostics, root certificates, and inventory.

Example

>>> # Get system statistics
>>> stats = client.system.statistics()
>>> print(f"VMs: {stats.vms_online}/{stats.vms_total}")

>>> # Get licenses
>>> for lic in client.system.licenses.list():
...     print(f"{lic.name}: {'valid' if lic.is_valid else 'invalid'}")

>>> # Get system settings
>>> setting = client.system.settings.get("max_connections")
>>> print(f"Max connections: {setting.value}")

>>> # Update a setting
>>> setting = client.system.settings.update("max_connections", "1000")

>>> # Build system diagnostics
>>> diag = client.system.diagnostics.build(
...     name="Support Case",
...     send_to_support=True
... )

>>> # Add a trusted root CA
>>> root_ca = client.system.root_certificates.create(cert=pem_text)

>>> # Get full inventory
>>> inventory = client.system.inventory()
>>> print(inventory.summary)

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

property settings: SettingsManager

Access system settings.

System settings control various aspects of VergeOS behavior including connection limits, API rate limits, and more.

Example

>>> # List all settings
>>> for s in client.system.settings.list():
...     print(f"{s.key}: {s.value}")

>>> # Update a setting
>>> client.system.settings.update("max_connections", "1000")

>>> # List modified settings
>>> for s in client.system.settings.list_modified():
...     print(f"{s.key}: {s.value} (default: {s.default_value})")

property licenses: LicenseManager

Access license management.

Licenses control which features are available and the capabilities of the VergeOS system.

Example

>>> # List licenses
>>> for lic in client.system.licenses.list():
...     print(f"{lic.name}: {'valid' if lic.is_valid else 'invalid'}")

>>> # Generate payload for air-gapped licensing
>>> payload = client.system.licenses.generate_payload()

property diagnostics: SystemDiagnosticManager

Access system diagnostics.

System diagnostics capture comprehensive system information for troubleshooting and support purposes.

Example

>>> # Build a diagnostic report
>>> diag = client.system.diagnostics.build(
...     name="Support-12345",
...     description="Network issue",
...     send_to_support=True
... )
>>> diag = diag.wait_for_completion()

>>> # List diagnostics
>>> for d in client.system.diagnostics.list():
...     print(f"{d.name}: {d.status_display}")

property root_certificates: RootCertificateManager

Access root certificate (trusted CA) management.

Root certificates allow adding custom Certificate Authorities to the system’s trust store for secure connections.

Example

>>> # Add a trusted CA
>>> ca_pem = open("enterprise-ca.pem").read()
>>> ca = client.system.root_certificates.create(cert=ca_pem)

>>> # List trusted CAs
>>> for ca in client.system.root_certificates.list():
...     print(f"{ca.subject}")

statistics()

Get system dashboard statistics.

Returns:

SystemStatistics object with counts for all resource types.

Return type:

SystemStatistics

Example

>>> stats = client.system.statistics()
>>> print(f"Total VMs: {stats.vms_total}")
>>> print(f"Online VMs: {stats.vms_online}")
>>> print(f"Active Alarms: {stats.alarms_total}")

inventory(include_vms=True, include_networks=True, include_storage=True, include_nodes=True, include_clusters=True, include_tenants=True)

Generate a comprehensive system inventory.

Similar to RVtools for VMware, this provides a complete view of all VergeOS resources.

Parameters:

• include_vms (bool) – Include VM inventory.

• include_networks (bool) – Include network inventory.

• include_storage (bool) – Include storage tier inventory.

• include_nodes (bool) – Include node inventory.

• include_clusters (bool) – Include cluster inventory.

• include_tenants (bool) – Include tenant inventory.

Returns:

SystemInventory object containing all requested resources.

Return type:

SystemInventory

Example

>>> inventory = client.system.inventory()
>>> print(f"Total VMs: {len(inventory.vms)}")
>>> print(f"Summary: {inventory.summary}")

Clusters

Cluster resource manager.

class pyvergeos.resources.clusters.Cluster

Bases: ResourceObject

Cluster resource object.

Represents a VergeOS cluster with compute and storage capabilities.

Example

>>> cluster = client.clusters.get(name="Production")
>>> print(f"{cluster.name}: {cluster.status}")
>>> print(f"  Nodes: {cluster.online_nodes}/{cluster.total_nodes}")
>>> print(f"  RAM: {cluster.used_ram_gb}/{cluster.online_ram_gb} GB")

property name: str

Cluster name.

property description: str

Cluster description.

property is_enabled: bool

Check if cluster is enabled.

property is_compute: bool

Check if cluster is a compute cluster.

property is_storage: bool

Check if cluster is a storage cluster.

property default_cpu: str

Default CPU type for VMs in this cluster.

property recommended_cpu_type: str

Recommended CPU type based on cluster hardware.

property nested_virtualization: bool

Check if nested virtualization is enabled.

property ram_per_unit: int

RAM per billing unit in MB.

property cores_per_unit: int

CPU cores per billing unit.

property max_ram_per_vm: int

Maximum RAM allowed per VM in MB.

property max_cores_per_vm: int

Maximum CPU cores allowed per VM.

property target_ram_percent: float

Target maximum RAM utilization percentage.

property ram_overcommit_percent: float

Percentage of reserve RAM to use for machines.

property created_at: datetime | None

Timestamp when cluster was created.

property status: str

Cluster status (Online, Offline, etc.).

property status_raw: str

Raw status value.

property total_nodes: int

Total number of nodes in cluster.

property online_nodes: int

Number of online nodes.

property total_ram_mb: int

Total RAM in MB.

property total_ram_gb: float

Total RAM in GB.

property online_ram_mb: int

Online RAM in MB.

property online_ram_gb: float

Online RAM in GB.

property used_ram_mb: int

Used RAM in MB.

property used_ram_gb: float

Used RAM in GB.

property ram_used_percent: float

RAM usage percentage.

property total_cores: int

Total CPU cores.

property online_cores: int

Online CPU cores.

property used_cores: int

Used CPU cores.

property cores_used_percent: float

CPU core usage percentage.

property running_machines: int

Number of running VMs.

property tiers: ClusterTierManager

Access tier management for this cluster.

Returns:

ClusterTierManager scoped to this cluster.

Example

>>> cluster = client.clusters.get(name="Production")
>>> for tier in cluster.tiers.list():
...     print(f"Tier {tier.tier}: {tier.used_percent}% used")

class pyvergeos.resources.clusters.VSANStatus

Bases: ResourceObject

Represents vSAN status for a cluster.

Provides health status, capacity information, and resource utilization metrics for a VergeOS cluster’s vSAN.

property cluster_name: str

Cluster name.

property description: str

Cluster description.

property is_enabled: bool

Whether cluster is enabled.

property is_storage: bool

Whether cluster provides storage.

property is_compute: bool

Whether cluster provides compute.

property status: str

Cluster status (Online, Offline, etc.).

property status_raw: str

Raw status value.

property state: str

Cluster state (Online, Warning, Error, Offline).

property state_raw: str

Raw state value.

property health_status: str

Health status (Healthy, Degraded, Critical, Offline).

property status_info: str

Status information message.

property total_nodes: int

Total number of nodes in cluster.

property online_nodes: int

Number of online nodes.

property running_machines: int

Number of running VMs.

property total_ram_mb: int

Total RAM in MB.

property total_ram_gb: float

Total RAM in GB.

property online_ram_mb: int

Online RAM in MB.

property online_ram_gb: float

Online RAM in GB.

property used_ram_mb: int

Used RAM in MB.

property used_ram_gb: float

Used RAM in GB.

property ram_used_percent: float

RAM usage percentage.

property total_cores: int

Total CPU cores.

property online_cores: int

Online CPU cores.

property used_cores: int

Used CPU cores.

property core_used_percent: float

CPU core usage percentage.

property last_update: datetime | None

Last status update timestamp.

property tiers: list[dict[str, Any]]

Tier status information (if include_tiers=True).

class pyvergeos.resources.clusters.ClusterManager

Bases: ResourceManager[Cluster]

Manager for Cluster operations.

Provides CRUD operations for VergeOS clusters including compute and storage configuration.

Example

>>> # List all clusters
>>> clusters = client.clusters.list()
>>> for cluster in clusters:
...     print(f"{cluster.name}: {cluster.status}")
...     print(f"  Nodes: {cluster.online_nodes}/{cluster.total_nodes}")

>>> # Get a specific cluster
>>> cluster = client.clusters.get(name="Production")

>>> # Create a new cluster
>>> new_cluster = client.clusters.create(
...     name="Development",
...     compute=True,
...     max_ram_per_vm=65536,
...     max_cores_per_vm=32,
... )

>>> # Update cluster settings
>>> client.clusters.update(cluster.key, max_ram_per_vm=131072)

>>> # Get vSAN status for all clusters
>>> status_list = client.clusters.vsan_status()
>>> for status in status_list:
...     print(f"{status.cluster_name}: {status.health_status}")

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, name=None, enabled=None, compute=None, storage=None, **filter_kwargs)

List clusters with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (defaults to comprehensive set).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• name (str | None) – Filter by cluster name (supports wildcards with ‘ct’).

• enabled (bool | None) – Filter by enabled status.

• compute (bool | None) – Filter by compute capability.

• storage (bool | None) – Filter by storage capability.

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of Cluster objects.

Return type:

list[Cluster]

Example

>>> # List all clusters
>>> clusters = client.clusters.list()

>>> # List only compute clusters
>>> compute_clusters = client.clusters.list(compute=True)

>>> # List enabled clusters
>>> enabled = client.clusters.list(enabled=True)

get(key=None, *, name=None, fields=None)

Get a single cluster by key or name.

Parameters:

• key (int | None) – Cluster $key (ID).

• name (str | None) – Cluster name.

• fields (list[str] | None) – List of fields to return.

Returns:

Cluster object.

Raises:

• NotFoundError – If cluster not found.

• ValueError – If neither key nor name provided.

Return type:

Cluster

Example

>>> cluster = client.clusters.get(key=1)
>>> cluster = client.clusters.get(name="Production")

create(name, *, description=None, enabled=True, compute=False, nested_virtualization=False, allow_nested_virt_migration=True, allow_vgpu_migration=False, default_cpu=None, disable_cpu_security_mitigations=False, disable_smt=False, enable_split_lock_detection=False, energy_perf_policy='performance', scaling_governor='performance', ram_per_unit=4096, cores_per_unit=1, cost_per_unit=0, price_per_unit=0, max_ram_per_vm=65536, max_cores_per_vm=16, target_ram_percent=80, ram_overcommit_percent=0, storage_cache_per_node=None, storage_buffer_per_node=None, storage_hugepages=True, enable_nvme_power_management=False, swap_tier=-1, swap_per_drive=None, max_core_temp=None, critical_core_temp=None, max_core_temp_warn_percent=10, disable_sleep=False, log_filter=None)

Create a new cluster.

Parameters:

• name (str) – Cluster name (1-128 characters, must be unique).

• description (str | None) – Optional description (max 2048 characters).

• enabled (bool) – Enable the cluster after creation.

• compute (bool) – Enable compute workloads on this cluster.

• nested_virtualization (bool) – Enable nested virtualization (VMs inside VMs).

• allow_nested_virt_migration (bool) – Allow live migration of VMs with nested virt.

• allow_vgpu_migration (bool) – Allow live migration of VMs with vGPU devices.

• default_cpu (str | None) – Default CPU type for VMs (e.g., ‘host’, ‘EPYC-Milan’).

• disable_cpu_security_mitigations (bool) – Disable CPU security mitigations.

• disable_smt (bool) – Disable Simultaneous Multi-Threading (hyper-threading).

• enable_split_lock_detection (bool) – Enable split lock detection.

• energy_perf_policy (Literal['performance', 'balance-performance', 'balance-power', 'normal', 'power']) – CPU energy-performance policy.

• scaling_governor (Literal['performance', 'ondemand', 'powersave']) – CPU scaling governor.

• ram_per_unit (int) – RAM per billing unit in MB.

• cores_per_unit (int) – CPU cores per billing unit.

• cost_per_unit (float) – Cost per billing unit.

• price_per_unit (float) – Price per billing unit.

• max_ram_per_vm (int) – Maximum RAM allowed per VM in MB.

• max_cores_per_vm (int) – Maximum CPU cores allowed per VM.

• target_ram_percent (float) – Target maximum RAM utilization percentage (0-100).

• ram_overcommit_percent (float) – Percentage of reserve RAM for machines (0-100).

• storage_cache_per_node (int | None) – Storage cache per node in MB.

• storage_buffer_per_node (int | None) – Storage buffer per node in MB.

• storage_hugepages (bool) – Allocate hugepages for storage.

• enable_nvme_power_management (bool) – Enable NVMe power management.

• swap_tier (int) – Storage tier for swap (-1 to disable, 0-5 for tier).

• swap_per_drive (int | None) – Swap space per drive in MB.

• max_core_temp (int | None) – Maximum core temperature in Celsius.

• critical_core_temp (int | None) – Critical core temperature in Celsius.

• max_core_temp_warn_percent (int) – Temperature warning threshold percentage.

• disable_sleep (bool) – Disable CPU sleep states.

• log_filter (str | None) – System log filter expression.

Returns:

Created Cluster object.

Raises:

• ValidationError – If parameters are invalid.

• ConflictError – If cluster name already exists.

Return type:

Cluster

Example

>>> cluster = client.clusters.create(
...     name="Development",
...     description="Development workloads",
...     compute=True,
...     max_ram_per_vm=65536,
...     max_cores_per_vm=32,
... )

update(key, *, name=None, description=None, enabled=None, compute=None, nested_virtualization=None, allow_nested_virt_migration=None, allow_vgpu_migration=None, default_cpu=None, disable_cpu_security_mitigations=None, disable_smt=None, enable_split_lock_detection=None, energy_perf_policy=None, scaling_governor=None, ram_per_unit=None, cores_per_unit=None, cost_per_unit=None, price_per_unit=None, max_ram_per_vm=None, max_cores_per_vm=None, target_ram_percent=None, ram_overcommit_percent=None, storage_cache_per_node=None, storage_buffer_per_node=None, storage_hugepages=None, enable_nvme_power_management=None, swap_tier=None, swap_per_drive=None, max_core_temp=None, critical_core_temp=None, max_core_temp_warn_percent=None, disable_sleep=None, log_filter=None)

Update an existing cluster.

Parameters:

• key (int) – Cluster $key (ID).

• name (str | None) – New cluster name.

• description (str | None) – New description.

• enabled (bool | None) – Enable or disable the cluster.

• compute (bool | None) – Enable or disable compute workloads.

• nested_virtualization (bool | None) – Enable or disable nested virtualization.

• allow_nested_virt_migration (bool | None) – Allow live migration with nested virt.

• allow_vgpu_migration (bool | None) – Allow live migration with vGPU.

• default_cpu (str | None) – Default CPU type for VMs.

• disable_cpu_security_mitigations (bool | None) – Disable CPU security mitigations.

• disable_smt (bool | None) – Disable Simultaneous Multi-Threading.

• enable_split_lock_detection (bool | None) – Enable split lock detection.

• energy_perf_policy (Literal['performance', 'balance-performance', 'balance-power', 'normal', 'power'] | None) – CPU energy-performance policy.

• scaling_governor (Literal['performance', 'ondemand', 'powersave'] | None) – CPU scaling governor.

• ram_per_unit (int | None) – RAM per billing unit in MB.

• cores_per_unit (int | None) – CPU cores per billing unit.

• cost_per_unit (float | None) – Cost per billing unit.

• price_per_unit (float | None) – Price per billing unit.

• max_ram_per_vm (int | None) – Maximum RAM allowed per VM in MB.

• max_cores_per_vm (int | None) – Maximum CPU cores allowed per VM.

• target_ram_percent (float | None) – Target maximum RAM utilization percentage.

• ram_overcommit_percent (float | None) – Percentage of reserve RAM for machines.

• storage_cache_per_node (int | None) – Storage cache per node in MB.

• storage_buffer_per_node (int | None) – Storage buffer per node in MB.

• storage_hugepages (bool | None) – Allocate hugepages for storage.

• enable_nvme_power_management (bool | None) – Enable NVMe power management.

• swap_tier (int | None) – Storage tier for swap.

• swap_per_drive (int | None) – Swap space per drive in MB.

• max_core_temp (int | None) – Maximum core temperature in Celsius.

• critical_core_temp (int | None) – Critical core temperature in Celsius.

• max_core_temp_warn_percent (int | None) – Temperature warning threshold percentage.

• disable_sleep (bool | None) – Disable CPU sleep states.

• log_filter (str | None) – System log filter expression.

Returns:

Updated Cluster object.

Return type:

Cluster

Example

>>> updated = client.clusters.update(
...     cluster.key,
...     max_ram_per_vm=131072,
...     max_cores_per_vm=64,
... )

delete(key)

Delete a cluster.

Clusters cannot be deleted if they have nodes or running machines assigned to them. Reassign resources before deletion.

Parameters:

key (int) – Cluster $key (ID).

Raises:

• ValidationError – If cluster has nodes or running machines.

• NotFoundError – If cluster not found.

Return type:

None

Example

>>> client.clusters.delete(cluster.key)

vsan_status(cluster_name=None, include_tiers=False)

Get vSAN health status for clusters.

Parameters:

• cluster_name (str | None) – Filter by specific cluster name.

• include_tiers (bool) – Include per-tier status information.

Returns:

List of VSANStatus objects with health and capacity info.

Return type:

list[VSANStatus]

Example

>>> status_list = client.clusters.vsan_status()
>>> for status in status_list:
...     print(f"{status.cluster_name}: {status.health_status}")
...     print(f"  RAM: {status.used_ram_gb}/{status.online_ram_gb} GB")
...     print(f"  Cores: {status.used_cores}/{status.online_cores}")

>>> # With tier information
>>> status_list = client.clusters.vsan_status(include_tiers=True)
>>> for status in status_list:
...     for tier in status.tiers:
...         print(f"  Tier {tier['tier']}: {tier['used_percent']}% used")

Cluster Tiers

Storage tier health and performance monitoring.

Cluster Tier Management for VergeOS vSAN.

This module provides access to cluster storage tiers, their status, performance stats, and historical metrics.

Example

>>> # Access tiers for a cluster
>>> cluster = client.clusters.get(name="Production")
>>> for tier in cluster.tiers.list():
...     print(f"Tier {tier.tier}: {tier.used_percent}% used")

>>> # Get tier status
>>> tier = cluster.tiers.get(tier=1)
>>> status = tier.get_status()
>>> print(f"Status: {status.status}, Redundant: {status.is_redundant}")

>>> # Get tier stats
>>> stats = tier.get_stats()
>>> print(f"IOPS: {stats.read_ops} read, {stats.write_ops} write")

>>> # Get stats history
>>> history = tier.stats_history_short(limit=100)
>>> for point in history:
...     print(f"{point.timestamp}: {point.read_ops} IOPS")

class pyvergeos.resources.cluster_tiers.ClusterTierStatsHistoryLong

Bases: ResourceObject

Long-term cluster tier stats history record.

Contains peak and average metrics with longer retention but lower resolution.

property tier_key: int

Parent tier key.

property timestamp: datetime | None

Timestamp for this history point.

property timestamp_epoch: int

Timestamp as Unix epoch.

property read_ops_peak: int

Peak read operations per second.

property write_ops_peak: int

Peak write operations per second.

property read_bps_peak: int

Peak read bytes per second.

property write_bps_peak: int

Peak write bytes per second.

property read_ops_avg: int

Average read operations per second.

property write_ops_avg: int

Average write operations per second.

property read_bps_avg: int

Average read bytes per second.

property write_bps_avg: int

Average write bytes per second.

property total_reads: int

Total read operations.

property total_writes: int

Total write operations.

property total_read_bytes: int

Total bytes read.

property total_write_bytes: int

Total bytes written.

property capacity_bytes: int

Capacity in bytes at this point.

property capacity_gb: float

Capacity in GB.

property used_bytes: int

Used space in bytes at this point.

property used_gb: float

Used space in GB.

property used_percent: float

Usage percentage at this point.

class pyvergeos.resources.cluster_tiers.ClusterTierStatsHistoryShort

Bases: ResourceObject

Short-term cluster tier stats history record.

Contains high-resolution metrics with shorter retention.

property tier_key: int

Parent tier key.

property timestamp: datetime | None

Timestamp for this history point.

property timestamp_epoch: int

Timestamp as Unix epoch.

property read_ops: int

Read operations per second.

property write_ops: int

Write operations per second.

property read_bps: int

Read bytes per second.

property write_bps: int

Write bytes per second.

property total_reads: int

Total read operations.

property total_writes: int

Total write operations.

property total_read_bytes: int

Total bytes read.

property total_write_bytes: int

Total bytes written.

property capacity_bytes: int

Capacity in bytes at this point.

property capacity_gb: float

Capacity in GB.

property used_bytes: int

Used space in bytes at this point.

property used_gb: float

Used space in GB.

property used_percent: float

Usage percentage at this point.

class pyvergeos.resources.cluster_tiers.ClusterTierStats

Bases: ResourceObject

Current cluster tier statistics.

Provides real-time I/O performance metrics for a tier.

property tier_key: int

Parent tier key.

property read_ops: int

Current read operations per second.

property write_ops: int

Current write operations per second.

property read_bps: int

Current read bytes per second.

property write_bps: int

Current write bytes per second.

property read_mbps: float

Current read MB per second.

property write_mbps: float

Current write MB per second.

property total_reads: int

Total read operations.

property total_writes: int

Total write operations.

property total_read_bytes: int

Total bytes read.

property total_write_bytes: int

Total bytes written.

property last_update: datetime | None

Timestamp of last update.

class pyvergeos.resources.cluster_tiers.ClusterTierStatus

Bases: ResourceObject

Cluster tier health and capacity status.

Provides operational status, capacity metrics, and health indicators.

property tier_key: int

Parent tier key.

property status: str

Status (Online, Offline, Repairing, etc.).

property status_raw: str

Raw status value.

property state: str

State (Online, Offline, Warning, Error).

property state_raw: str

Raw state value.

property is_online: bool

Check if tier is online.

property is_healthy: bool

Check if tier is healthy (online state).

property is_warning: bool

Check if tier is in warning state.

property is_error: bool

Check if tier is in error state.

property capacity_bytes: int

Total capacity in bytes.

property capacity_gb: float

Total capacity in GB.

property capacity_tb: float

Total capacity in TB.

property used_bytes: int

Used space in bytes.

property used_gb: float

Used space in GB.

property used_tb: float

Used space in TB.

property used_percent: float

Usage percentage.

property free_bytes: int

Free space in bytes.

property free_gb: float

Free space in GB.

property is_redundant: bool

Check if tier has redundancy.

property is_encrypted: bool

Check if tier is encrypted.

property is_working: bool

Check if tier is actively working.

property last_walk_time_ms: int

Last walk time in milliseconds.

property last_fullwalk_time_ms: int

Last full walk time in milliseconds.

property transaction: int

Current transaction ID.

property repairs: int

Number of repairs.

property bad_drives: int

Number of unavailable drives.

property is_fullwalk: bool

Check if full walk is in progress.

property walk_progress: float

Walk progress percentage (0-100).

property index_unique: int

Unique index count.

property throttle_ms: float

Current space throttle in milliseconds.

property is_throttled: bool

Check if tier is being throttled due to low space.

property transaction_start: datetime | None

Transaction start timestamp.

property state_timestamp: datetime | None

Timestamp when state last changed.

class pyvergeos.resources.cluster_tiers.ClusterTier

Bases: ResourceObject

Cluster storage tier resource object.

Represents a storage tier within a specific cluster.

Example

>>> tier = cluster.tiers.get(tier=1)
>>> print(f"Tier {tier.tier}: {tier.description}")
>>> print(f"  Status: {tier.status}, Capacity: {tier.capacity_gb} GB")

property tier: int

Tier number (0-5).

property cluster_key: int

Parent cluster key.

property description: str

Tier description.

property cost_per_gb: float

Cost per GB.

property price_per_gb: float

Price per GB.

property status: str

Status from embedded status field.

property status_raw: str

Raw status value.

property capacity_bytes: int

Total capacity in bytes.

property capacity_gb: float

Total capacity in GB.

property capacity_tb: float

Total capacity in TB.

property used_bytes: int

Used space in bytes.

property used_gb: float

Used space in GB.

property used_tb: float

Used space in TB.

property used_percent: float

Usage percentage.

property free_bytes: int

Free space in bytes.

property free_gb: float

Free space in GB.

property is_redundant: bool

Check if tier has redundancy.

property is_working: bool

Check if tier is actively working.

property is_encrypted: bool

Check if tier is encrypted.

property read_ops: int

Current read operations per second.

property write_ops: int

Current write operations per second.

property read_bps: int

Current read bytes per second.

property write_bps: int

Current write bytes per second.

get_status()

Get detailed tier status.

Returns:

ClusterTierStatus object with full status information.

Return type:

ClusterTierStatus

get_stats()

Get current tier statistics.

Returns:

ClusterTierStats object with current I/O metrics.

Return type:

ClusterTierStats

stats_history_short(limit=None, offset=None, since=None, until=None)

Get short-term stats history (high resolution).

Parameters:

• limit (int | None) – Maximum number of records.

• offset (int | None) – Skip this many records.

• since (datetime | int | None) – Return records after this time.

• until (datetime | int | None) – Return records before this time.

Returns:

List of ClusterTierStatsHistoryShort objects.

Return type:

list[ClusterTierStatsHistoryShort]

stats_history_long(limit=None, offset=None, since=None, until=None)

Get long-term stats history (lower resolution, longer retention).

Parameters:

• limit (int | None) – Maximum number of records.

• offset (int | None) – Skip this many records.

• since (datetime | int | None) – Return records after this time.

• until (datetime | int | None) – Return records before this time.

Returns:

List of ClusterTierStatsHistoryLong objects.

Return type:

list[ClusterTierStatsHistoryLong]

class pyvergeos.resources.cluster_tiers.ClusterTierManager

Bases: ResourceManager[ClusterTier]

Manager for cluster tier operations.

Provides access to storage tiers within a specific cluster, including status, statistics, and historical metrics.

Scoped to a specific cluster.

Example

>>> # Access via cluster object
>>> cluster = client.clusters.get(name="Production")
>>> for tier in cluster.tiers.list():
...     print(f"Tier {tier.tier}: {tier.used_percent}% used")

>>> # Get specific tier
>>> tier = cluster.tiers.get(tier=1)

>>> # Get tier status
>>> status = cluster.tiers.get_tier_status(tier.key)
>>> print(f"Status: {status.status}")

>>> # Get tier stats
>>> stats = cluster.tiers.get_tier_stats(tier.key)
>>> print(f"IOPS: {stats.read_ops} read, {stats.write_ops} write")

__init__(client, cluster_key)

Parameters:

• client (VergeClient)

• cluster_key (int)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, tier=None, **filter_kwargs)

List cluster tiers.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• tier (int | None) – Filter by tier number (0-5).

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of ClusterTier objects.

Return type:

list[ClusterTier]

Example

>>> # List all tiers for this cluster
>>> for tier in cluster.tiers.list():
...     print(f"Tier {tier.tier}: {tier.used_percent}% used")

get(key=None, *, tier=None, fields=None)

Get a cluster tier by key or tier number.

Parameters:

• key (int | None) – Tier $key.

• tier (int | None) – Tier number (0-5) - alternative to key.

• fields (list[str] | None) – List of fields to return.

Returns:

ClusterTier object.

Raises:

• NotFoundError – If tier not found.

• ValueError – If neither key nor tier provided.

Return type:

ClusterTier

Example

>>> tier1 = cluster.tiers.get(tier=1)
>>> print(f"Tier 1: {tier1.used_gb} GB used")

get_tier_status(tier_key)

Get detailed status for a tier.

Parameters:

tier_key (int) – Tier $key.

Returns:

ClusterTierStatus object.

Raises:

NotFoundError – If status not found.

Return type:

ClusterTierStatus

get_tier_stats(tier_key)

Get current statistics for a tier.

Parameters:

tier_key (int) – Tier $key.

Returns:

ClusterTierStats object.

Raises:

NotFoundError – If stats not found.

Return type:

ClusterTierStats

get_stats_history_short(tier_key, limit=None, offset=None, since=None, until=None)

Get short-term stats history for a tier.

Parameters:

• tier_key (int) – Tier $key.

• limit (int | None) – Maximum number of records.

• offset (int | None) – Skip this many records.

• since (datetime | int | None) – Return records after this time.

• until (datetime | int | None) – Return records before this time.

Returns:

List of ClusterTierStatsHistoryShort objects.

Return type:

list[ClusterTierStatsHistoryShort]

get_stats_history_long(tier_key, limit=None, offset=None, since=None, until=None)

Get long-term stats history for a tier.

Parameters:

• tier_key (int) – Tier $key.

• limit (int | None) – Maximum number of records.

• offset (int | None) – Skip this many records.

• since (datetime | int | None) – Return records after this time.

• until (datetime | int | None) – Return records before this time.

Returns:

List of ClusterTierStatsHistoryLong objects.

Return type:

list[ClusterTierStatsHistoryLong]

get_summary()

Get a summary of all tiers in this cluster.

Returns:

Dictionary with aggregate tier information.

Return type:

dict[str, Any]

Example

>>> summary = cluster.tiers.get_summary()
>>> print(f"Total: {summary['total_capacity_gb']} GB")
>>> print(f"Used: {summary['total_used_gb']} GB ({summary['used_percent']}%)")

Nodes

Node resource manager.

class pyvergeos.resources.nodes.Node

Bases: ResourceObject

Node resource object.

Represents a VergeOS node with compute and storage capabilities.

Example

>>> node = client.nodes.get(name="node1")
>>> print(f"{node.name}: {node.status}")
>>> print(f"  RAM: {node.ram_mb}MB, Cores: {node.cores}")
>>> if node.is_maintenance:
...     print("  In maintenance mode")

property name: str

Node hostname.

property description: str

Node description.

property model: str

Hardware model.

property cpu: str

CPU model.

property cpu_speed: str

CPU speed.

property is_online: bool

Check if node is online/running.

property is_maintenance: bool

Check if node is in maintenance mode.

property is_physical: bool

Check if this is a physical node.

property status: str

Node status (Running, Stopped, Online, Offline, etc.).

property status_raw: str

Raw status value.

property ram_mb: int

Total RAM in MB.

property ram_gb: float

Total RAM in GB.

property vm_ram_mb: int

RAM available for VMs in MB.

property overcommit_ram_mb: int

Overcommit RAM in MB.

property failover_ram_mb: int

Failover RAM in MB.

property cores: int

Number of CPU cores.

property ram_used_mb: int

Used physical RAM in MB.

property vram_used_mb: int

Used virtual RAM in MB.

property cpu_usage: float

CPU usage percentage.

property core_temp: float | None

Core temperature in Celsius.

property has_iommu: bool

Check if IOMMU (VT-d) is supported.

property needs_restart: bool

Check if node needs to be rebooted.

property restart_reason: str

Reason for needing reboot.

property vsan_node_id: int

vSAN node ID.

property vsan_connected: bool

Check if vSAN is connected.

property cluster_key: int | None

Parent cluster key.

property cluster_name: str

Parent cluster name.

property machine_key: int | None

Associated machine key.

property asset_tag: str

Asset tag.

property ipmi_address: str

IPMI address.

property ipmi_status: str

IPMI status.

property vergeos_version: str

VergeOS version (yb_version).

property os_version: str

OS version.

property kernel_version: str

Kernel version.

property appserver_version: str

Appserver version.

property vsan_version: str

vSAN version.

property qemu_version: str

QEMU version.

property started_at: datetime | None

Timestamp when node was started.

enable_maintenance()

Enable maintenance mode on this node.

Returns:

Updated Node object.

Return type:

Node

disable_maintenance()

Disable maintenance mode on this node.

Returns:

Updated Node object.

Return type:

Node

restart()

Perform a maintenance reboot on this node.

Returns:

Task information dict or None.

Return type:

dict[str, Any] | None

property drivers: NodeDriverManager

Access drivers for this node.

Returns:

NodeDriverManager scoped to this node.

property pci_devices: NodePCIDeviceManager

Access PCI devices for this node.

Returns:

NodePCIDeviceManager scoped to this node.

property usb_devices: NodeUSBDeviceManager

Access USB devices for this node.

Returns:

NodeUSBDeviceManager scoped to this node.

property stats: MachineStatsManager

Access performance stats for this node.

Returns:

MachineStatsManager scoped to this node.

Example

>>> stats = node.stats.get()
>>> print(f"CPU: {stats.total_cpu}%, RAM: {stats.ram_used_mb}MB")

>>> # Get stats history
>>> history = node.stats.history_short(limit=100)

Raises:

ValueError – If node has no associated machine.

property machine_status: MachineStatusManager

Access detailed operational status for this node.

Returns:

MachineStatusManager scoped to this node.

Example

>>> status = node.machine_status.get()
>>> print(f"Status: {status.status}")

Raises:

ValueError – If node has no associated machine.

property machine_logs: MachineLogManager

Access log entries for this node.

Returns:

MachineLogManager scoped to this node.

Example

>>> logs = node.machine_logs.list(limit=20)
>>> errors = node.machine_logs.list(errors_only=True)

Raises:

ValueError – If node has no associated machine.

property gpus: NodeGpuManager

Access GPU configurations for this node.

Returns:

NodeGpuManager scoped to this node.

Example

>>> for gpu in node.gpus.list():
...     print(f"{gpu.name}: {gpu.mode_display}")

property vgpu_devices: NodeVgpuDeviceManager

Access NVIDIA vGPU-capable devices on this node.

Returns:

NodeVgpuDeviceManager scoped to this node.

Example

>>> for device in node.vgpu_devices.list():
...     print(f"{device.name}: {device.vendor} {device.device}")

property host_gpu_devices: NodeHostGpuDeviceManager

Access host GPU devices available for passthrough on this node.

Returns:

NodeHostGpuDeviceManager scoped to this node.

Example

>>> for device in node.host_gpu_devices.list():
...     print(f"{device.name}: {device.vendor} {device.device}")

property sriov_nics: NodeSriovNicDeviceManager

Access SR-IOV NIC devices on this node.

Returns:

NodeSriovNicDeviceManager scoped to this node.

Example

>>> for device in node.sriov_nics.list():
...     print(f"{device.name}: PF {device.physical_function}")

class pyvergeos.resources.nodes.NodeDriver

Bases: ResourceObject

Node driver resource object.

Represents a driver installed on a VergeOS node.

property node_key: int | None

Parent node key.

property node_name: str

Parent node name.

property driver_name: str

Driver name.

property driver_key: str

Driver key identifier.

property driver_file_key: int | None

Driver file key.

property driver_file_name: str

Driver file name.

property description: str

Driver description.

property status: str

Driver status (Installed, Verifying, Error).

property status_raw: str

Raw status value.

property status_info: str

Status information message.

property class_filter: str

Device class filter.

property vendor_filter: str

Vendor filter.

property modified_at: datetime | None

Timestamp when driver was last modified.

class pyvergeos.resources.nodes.NodePCIDevice

Bases: ResourceObject

Node PCI device resource object.

Represents a PCI device attached to a VergeOS node.

property node_key: int | None

Parent node key.

property node_name: str

Parent node name.

property name: str

Device name.

property slot: str

PCI slot.

property device_class: str

Device class.

property class_hex: str

Device class in hexadecimal.

property device_type_code: str

Device type code.

property device_type: str

Device type description.

property vendor: str

Vendor name.

property device: str

Device name.

property vendor_device_hex: str

Vendor/device ID in hexadecimal.

property subsystem_vendor: str

Subsystem vendor.

property subsystem_device: str

Subsystem device.

property physical_slot: str

Physical slot.

property driver: str

Current driver.

property module: str

Kernel module.

property numa_node: str

NUMA node.

property iommu_group: str

IOMMU group.

property sriov_total_vfs: int

Maximum SR-IOV virtual functions.

property sriov_num_vfs: int

Current SR-IOV virtual functions.

property is_gpu: bool

Check if this is a GPU/display controller.

property is_network_controller: bool

Check if this is a network controller.

property is_storage_controller: bool

Check if this is a mass storage controller.

class pyvergeos.resources.nodes.NodeUSBDevice

Bases: ResourceObject

Node USB device resource object.

Represents a USB device attached to a VergeOS node.

property node_key: int | None

Parent node key.

property node_name: str

Parent node name.

property bus: str

USB bus number.

property device_num: str

USB device number.

property path: str

USB path.

property devpath: str

Device path.

property vendor: str

Vendor name.

property vendor_id: str

Vendor ID.

property model: str

Model name.

property model_id: str

Model ID.

property serial: str

Serial number.

property usb_version: str

USB version.

property speed: str

USB speed.

property interface_drivers: str

Interface drivers.

class pyvergeos.resources.nodes.NodeSriovNicDevice

Bases: ResourceObject

Node SR-IOV NIC device resource object.

Represents an SR-IOV capable NIC (Virtual Function) attached to a VergeOS node. These are virtual network interfaces created from a physical NIC that supports SR-IOV.

property node_key: int | None

Parent node key.

property node_name: str

Parent node name.

property pci_device_key: int | None

Parent PCI device key (physical function).

property name: str

Device name.

property slot: str

PCI slot.

property vendor: str

Vendor name.

property device: str

Device name.

property vendor_device_hex: str

Vendor/device ID in hexadecimal.

property subsystem_vendor: str

Subsystem vendor.

property subsystem_device: str

Subsystem device.

property physical_slot: str

Physical slot.

property physical_function: str

Physical function (PF) slot for this VF.

property revision_number: str

Revision number.

property driver: str

Current driver.

property module: str

Kernel module.

property numa_node: str

NUMA node.

property iommu_group: str

IOMMU group.

class pyvergeos.resources.nodes.NodeDriverManager

Bases: ResourceManager[NodeDriver]

Manager for node driver operations.

Provides access to drivers installed on VergeOS nodes. Can be used globally or scoped to a specific node.

Example

>>> # List all drivers across all nodes
>>> drivers = client.nodes.all_drivers.list()

>>> # List drivers for a specific node
>>> node_drivers = client.nodes.drivers(node_key).list()

>>> # Or via node object
>>> node = client.nodes.get(name="node1")
>>> for driver in node.drivers.list():
...     print(f"{driver.driver_name}: {driver.status}")

__init__(client, node_key=None)

Parameters:

• client (VergeClient)

• node_key (int | None)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, driver_name=None, status=None, **filter_kwargs)

List node drivers with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• driver_name (str | None) – Filter by driver name (contains).

• status (Literal['Installed', 'Verifying', 'Error'] | None) – Filter by status (Installed, Verifying, Error).

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of NodeDriver objects.

Return type:

list[NodeDriver]

Example

>>> # List all drivers
>>> drivers = client.nodes.all_drivers.list()

>>> # List installed drivers
>>> installed = client.nodes.all_drivers.list(status="Installed")

>>> # List NVIDIA drivers
>>> nvidia = client.nodes.all_drivers.list(driver_name="nvidia")

get(key=None, *, driver_name=None, fields=None)

Get a single driver by key or name.

Parameters:

• key (int | None) – Driver $key (ID).

• driver_name (str | None) – Driver name.

• fields (list[str] | None) – List of fields to return.

Returns:

NodeDriver object.

Raises:

• NotFoundError – If driver not found.

• ValueError – If neither key nor driver_name provided.

Return type:

NodeDriver

class pyvergeos.resources.nodes.NodePCIDeviceManager

Bases: ResourceManager[NodePCIDevice]

Manager for node PCI device operations.

Provides access to PCI devices attached to VergeOS nodes. Can be used globally or scoped to a specific node.

Example

>>> # List all PCI devices
>>> devices = client.nodes.all_pci_devices.list()

>>> # List GPUs only
>>> gpus = client.nodes.all_pci_devices.list(device_type="GPU")

>>> # List devices for a specific node
>>> node_devices = client.nodes.pci_devices(node_key).list()

__init__(client, node_key=None)

Parameters:

• client (VergeClient)

• node_key (int | None)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, device_type=None, device_class=None, vendor=None, **filter_kwargs)

List PCI devices with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• device_type (Literal['GPU', 'Network', 'Storage'] | None) – Filter by device type (GPU, Network, Storage).

• device_class (str | None) – Filter by device class (contains).

• vendor (str | None) – Filter by vendor name (contains).

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of NodePCIDevice objects.

Return type:

list[NodePCIDevice]

Example

>>> # List all PCI devices
>>> devices = client.nodes.all_pci_devices.list()

>>> # List GPUs only
>>> gpus = client.nodes.all_pci_devices.list(device_type="GPU")

>>> # List network controllers
>>> nics = client.nodes.all_pci_devices.list(device_type="Network")

get(key, *, fields=None)

Get a single PCI device by key.

Parameters:

• key (int) – Device $key (ID).

• fields (list[str] | None) – List of fields to return.

Returns:

NodePCIDevice object.

Raises:

NotFoundError – If device not found.

Return type:

NodePCIDevice

class pyvergeos.resources.nodes.NodeUSBDeviceManager

Bases: ResourceManager[NodeUSBDevice]

Manager for node USB device operations.

Provides access to USB devices attached to VergeOS nodes. Can be used globally or scoped to a specific node.

Example

>>> # List all USB devices
>>> devices = client.nodes.all_usb_devices.list()

>>> # List USB devices for a specific node
>>> node_devices = client.nodes.usb_devices(node_key).list()

__init__(client, node_key=None)

Parameters:

• client (VergeClient)

• node_key (int | None)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, vendor=None, model=None, **filter_kwargs)

List USB devices with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• vendor (str | None) – Filter by vendor name (contains).

• model (str | None) – Filter by model name (contains).

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of NodeUSBDevice objects.

Return type:

list[NodeUSBDevice]

Example

>>> # List all USB devices
>>> devices = client.nodes.all_usb_devices.list()

>>> # List USB devices by vendor
>>> devices = client.nodes.all_usb_devices.list(vendor="Logitech")

get(key, *, fields=None)

Get a single USB device by key.

Parameters:

• key (int) – Device $key (ID).

• fields (list[str] | None) – List of fields to return.

Returns:

NodeUSBDevice object.

Raises:

NotFoundError – If device not found.

Return type:

NodeUSBDevice

class pyvergeos.resources.nodes.NodeSriovNicDeviceManager

Bases: ResourceManager[NodeSriovNicDevice]

Manager for node SR-IOV NIC device operations.

Provides access to SR-IOV capable NIC virtual functions (VFs) attached to VergeOS nodes. Can be used globally or scoped to a specific node.

SR-IOV (Single Root I/O Virtualization) allows a single physical NIC to appear as multiple virtual network interfaces, each passable to a VM for near-native network performance.

Example

>>> # List all SR-IOV NIC devices
>>> devices = client.nodes.all_sriov_nics.list()

>>> # List SR-IOV NICs for a specific node
>>> node_devices = client.nodes.sriov_nics(node_key).list()

>>> # Or via node object
>>> for device in node.sriov_nics.list():
...     print(f"{device.name} on {device.slot} (PF: {device.physical_function})")

__init__(client, node_key=None)

Parameters:

• client (VergeClient)

• node_key (int | None)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, vendor=None, physical_function=None, **filter_kwargs)

List SR-IOV NIC devices with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• vendor (str | None) – Filter by vendor name (contains).

• physical_function (str | None) – Filter by physical function slot (exact match).

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of NodeSriovNicDevice objects.

Return type:

list[NodeSriovNicDevice]

Example

>>> # List all SR-IOV NIC devices
>>> devices = client.nodes.all_sriov_nics.list()

>>> # List Intel SR-IOV NICs
>>> intel = client.nodes.all_sriov_nics.list(vendor="Intel")

>>> # List VFs for a specific physical function
>>> vfs = client.nodes.all_sriov_nics.list(
...     physical_function="0000:3b:00.0"
... )

get(key, *, fields=None)

Get a single SR-IOV NIC device by key.

Parameters:

• key (int) – Device $key (ID).

• fields (list[str] | None) – List of fields to return.

Returns:

NodeSriovNicDevice object.

Raises:

NotFoundError – If device not found.

Return type:

NodeSriovNicDevice

class pyvergeos.resources.nodes.NodeManager

Bases: ResourceManager[Node]

Manager for Node operations.

Provides CRUD operations and actions for VergeOS nodes.

Example

>>> # List all nodes
>>> nodes = client.nodes.list()
>>> for node in nodes:
...     print(f"{node.name}: {node.status}")

>>> # Get a specific node
>>> node = client.nodes.get(name="node1")

>>> # Enable maintenance mode
>>> node = client.nodes.enable_maintenance(node.key)

>>> # Access node drivers
>>> for driver in node.drivers.list():
...     print(f"{driver.driver_name}: {driver.status}")

>>> # Access PCI devices (GPUs)
>>> gpus = client.nodes.all_pci_devices.list(device_type="GPU")

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, name=None, cluster=None, maintenance=None, **filter_kwargs)

List nodes with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (defaults to comprehensive set).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• name (str | None) – Filter by node name.

• cluster (str | None) – Filter by cluster name.

• maintenance (bool | None) – Filter by maintenance mode status.

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of Node objects.

Return type:

list[Node]

Example

>>> # List all nodes
>>> nodes = client.nodes.list()

>>> # List nodes in a specific cluster
>>> nodes = client.nodes.list(cluster="Cluster1")

>>> # List nodes in maintenance mode
>>> nodes = client.nodes.list(maintenance=True)

get(key=None, *, name=None, fields=None)

Get a single node by key or name.

Parameters:

• key (int | None) – Node $key (ID).

• name (str | None) – Node name (hostname).

• fields (list[str] | None) – List of fields to return.

Returns:

Node object.

Raises:

• NotFoundError – If node not found.

• ValueError – If neither key nor name provided.

Return type:

Node

Example

>>> node = client.nodes.get(key=1)
>>> node = client.nodes.get(name="node1")

enable_maintenance(key)

Enable maintenance mode on a node.

When in maintenance mode, VMs will be migrated off the node and no new workloads will be scheduled to it.

Parameters:

key (int) – Node $key (ID).

Returns:

Updated Node object.

Return type:

Node

Example

>>> node = client.nodes.enable_maintenance(node.key)
>>> print(f"Maintenance mode: {node.is_maintenance}")

disable_maintenance(key)

Disable maintenance mode on a node.

Once disabled, the node will be available to run VMs and receive new workloads.

Parameters:

key (int) – Node $key (ID).

Returns:

Updated Node object.

Return type:

Node

Example

>>> node = client.nodes.disable_maintenance(node.key)
>>> print(f"Maintenance mode: {node.is_maintenance}")

restart(key)

Perform a maintenance reboot on a node.

This safely reboots the node by first migrating workloads and then restarting the system.

Parameters:

key (int) – Node $key (ID).

Returns:

Task information dict or None.

Return type:

dict[str, Any] | None

Example

>>> result = client.nodes.restart(node.key)
>>> if result and "task" in result:
...     client.tasks.wait(result["task"])

drivers(node_key)

Get driver manager scoped to a specific node.

Parameters:

node_key (int) – Node $key (ID).

Returns:

NodeDriverManager for the specified node.

Return type:

NodeDriverManager

Example

>>> drivers = client.nodes.drivers(node.key).list()

pci_devices(node_key)

Get PCI device manager scoped to a specific node.

Parameters:

node_key (int) – Node $key (ID).

Returns:

NodePCIDeviceManager for the specified node.

Return type:

NodePCIDeviceManager

Example

>>> devices = client.nodes.pci_devices(node.key).list()

usb_devices(node_key)

Get USB device manager scoped to a specific node.

Parameters:

node_key (int) – Node $key (ID).

Returns:

NodeUSBDeviceManager for the specified node.

Return type:

NodeUSBDeviceManager

Example

>>> devices = client.nodes.usb_devices(node.key).list()

property all_drivers: NodeDriverManager

Access all drivers across all nodes.

Returns:

NodeDriverManager (global, not scoped to a node).

Example

>>> all_drivers = client.nodes.all_drivers.list()

property all_pci_devices: NodePCIDeviceManager

Access all PCI devices across all nodes.

Returns:

NodePCIDeviceManager (global, not scoped to a node).

Example

>>> all_gpus = client.nodes.all_pci_devices.list(device_type="GPU")

property all_usb_devices: NodeUSBDeviceManager

Access all USB devices across all nodes.

Returns:

NodeUSBDeviceManager (global, not scoped to a node).

Example

>>> all_usb = client.nodes.all_usb_devices.list()

sriov_nics(node_key)

Get SR-IOV NIC device manager scoped to a specific node.

Parameters:

node_key (int) – Node $key (ID).

Returns:

NodeSriovNicDeviceManager for the specified node.

Return type:

NodeSriovNicDeviceManager

Example

>>> devices = client.nodes.sriov_nics(node.key).list()

property all_sriov_nics: NodeSriovNicDeviceManager

Access all SR-IOV NIC devices across all nodes.

Returns:

NodeSriovNicDeviceManager (global, not scoped to a node).

Example

>>> all_sriov = client.nodes.all_sriov_nics.list()
>>> intel_vfs = client.nodes.all_sriov_nics.list(vendor="Intel")

gpus(node_key)

Get GPU manager scoped to a specific node.

Parameters:

node_key (int) – Node $key (ID).

Returns:

NodeGpuManager for the specified node.

Return type:

NodeGpuManager

Example

>>> gpus = client.nodes.gpus(node.key).list()

vgpu_devices(node_key)

Get vGPU device manager scoped to a specific node.

Parameters:

node_key (int) – Node $key (ID).

Returns:

NodeVgpuDeviceManager for the specified node.

Return type:

NodeVgpuDeviceManager

Example

>>> devices = client.nodes.vgpu_devices(node.key).list()

host_gpu_devices(node_key)

Get host GPU device manager scoped to a specific node.

Parameters:

node_key (int) – Node $key (ID).

Returns:

NodeHostGpuDeviceManager for the specified node.

Return type:

NodeHostGpuDeviceManager

Example

>>> devices = client.nodes.host_gpu_devices(node.key).list()

property all_gpus: NodeGpuManager

Access all GPU configurations across all nodes.

Returns:

NodeGpuManager (global, not scoped to a node).

Example

>>> all_gpus = client.nodes.all_gpus.list()
>>> passthrough = client.nodes.all_gpus.list(mode="gpu")

property all_vgpu_devices: NodeVgpuDeviceManager

Access all vGPU-capable devices across all nodes.

Returns:

NodeVgpuDeviceManager (global, not scoped to a node).

Example

>>> all_vgpu = client.nodes.all_vgpu_devices.list()

property all_host_gpu_devices: NodeHostGpuDeviceManager

Access all host GPU devices across all nodes.

Returns:

NodeHostGpuDeviceManager (global, not scoped to a node).

Example

>>> all_host_gpu = client.nodes.all_host_gpu_devices.list()

GPU/vGPU Management

GPU passthrough and vGPU configuration.

GPU and vGPU management for VergeOS.

This module provides access to GPU passthrough and NVIDIA vGPU functionality, enabling AI/ML workloads and graphics-intensive applications.

Example

>>> # List all vGPU profiles available in the system
>>> for profile in client.vgpu_profiles.list():
...     print(f"{profile.name}: {profile.framebuffer} RAM")

>>> # List GPUs configured on a node
>>> node = client.nodes.get(name="node2")
>>> for gpu in node.gpus.list():
...     print(f"{gpu.name}: {gpu.mode_display}")

>>> # Configure a GPU for passthrough
>>> gpu = node.gpus.get(name="GPU_1")
>>> gpu = node.gpus.update(gpu.key, mode="gpu")

>>> # Get GPU stats
>>> stats = gpu.stats.get()
>>> print(f"vGPUs in use: {stats.vgpus}/{stats.vgpus_total}")

class pyvergeos.resources.gpu.NvidiaVgpuProfile

Bases: ResourceObject

NVIDIA vGPU profile resource object.

Represents a vGPU profile available in the system. Profiles define the characteristics of virtual GPUs that can be created.

These are read-only and determined by NVIDIA drivers.

property name: str

Profile name (e.g., ‘nvidia-256’, ‘grid_p40-1q’).

property type_id: int

NVIDIA type ID for this profile.

property device_hex: str

device ID in hexadecimal (e.g., ‘10de:1eb8’).

Type:

Vendor

property num_heads: int

Number of display heads supported.

property frl_config: int

Frame rate limiter configuration.

property framebuffer: str

Framebuffer (VRAM) size (e.g., ‘256M’, ‘1G’).

property max_resolution: str

Maximum supported resolution (e.g., ‘4096x2160’).

property max_instance: int

Maximum instances per physical GPU.

property max_instances_per_vm: int

Maximum vGPU instances per VM.

property placement_ids: str

Placement IDs for this profile.

property location: str

Profile location/path.

property profile_type: str

Profile type code (A, B, C, Q).

property profile_type_display: str

Human-readable profile type.

property grid_license: str

Required GRID license type.

property is_virtual_function: bool

Whether this is a virtual function profile.

property profile_folder: str

Profile folder path.

class pyvergeos.resources.gpu.NvidiaVgpuProfileManager

Bases: ResourceManager[NvidiaVgpuProfile]

Manager for NVIDIA vGPU profiles.

Provides read-only access to vGPU profiles available in the system. These profiles are determined by the NVIDIA drivers and available hardware.

Example

>>> # List all profiles
>>> for profile in client.vgpu_profiles.list():
...     print(f"{profile.name}: {profile.framebuffer} ({profile.profile_type_display})")

>>> # Get profiles for AI/ML workloads
>>> ml_profiles = client.vgpu_profiles.list(profile_type="C")

list(filter=None, fields=None, limit=None, offset=None, *, profile_type=None, **filter_kwargs)

List NVIDIA vGPU profiles.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• profile_type (Literal['A', 'B', 'C', 'Q'] | None) – Filter by profile type: - A: Virtual Applications (vApps) - B: Virtual Desktops (vPC) - C: AI/ML/Training (vCS or vWS) - Q: Virtual Workstations (vWS)

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of NvidiaVgpuProfile objects.

Return type:

list[NvidiaVgpuProfile]

Example

>>> # List all profiles
>>> profiles = client.vgpu_profiles.list()

>>> # List AI/ML profiles only
>>> ml_profiles = client.vgpu_profiles.list(profile_type="C")

get(key=None, *, name=None, fields=None)

Get a vGPU profile by key or name.

Parameters:

• key (int | None) – Profile $key (ID).

• name (str | None) – Profile name.

• fields (list[str] | None) – List of fields to return.

Returns:

NvidiaVgpuProfile object.

Raises:

• NotFoundError – If profile not found.

• ValueError – If neither key nor name provided.

Return type:

NvidiaVgpuProfile

class pyvergeos.resources.gpu.NodeGpu

Bases: ResourceObject

Node GPU resource object.

Represents a physical GPU configured on a VergeOS node. A GPU can be configured for PCI passthrough or NVIDIA vGPU mode.

Example

>>> gpu = node.gpus.get(name="GPU_1")
>>> print(f"Mode: {gpu.mode_display}")
>>> print(f"Instances: {gpu.instances_count}/{gpu.max_instances}")

property name: str

GPU name (e.g., ‘GPU_1’).

property description: str

GPU description.

property pci_device_key: int | None

Associated PCI device key.

property pci_device_name: str

PCI device name/description.

property node_key: int | None

Parent node key.

property node_name: str

Parent node name.

property mode: str

GPU operating mode (none, gpu, nvidia_vgpu).

property mode_display: str

Human-readable GPU mode.

property nvidia_vgpu_profile_key: int | None

Assigned vGPU profile key (for nvidia_vgpu mode).

property nvidia_vgpu_profile_display: str

Display name of assigned vGPU profile.

property max_instances: int

Maximum GPU/vGPU instances this GPU can provide.

property instances_count: int

Current number of assigned instances.

property modified_at: datetime | None

Timestamp when GPU was last modified.

property is_passthrough: bool

Check if GPU is configured for PCI passthrough.

property is_vgpu: bool

Check if GPU is configured for NVIDIA vGPU.

property is_disabled: bool

Check if GPU is disabled (no mode set).

property stats: NodeGpuStatsManager

Access GPU utilization stats.

Returns:

NodeGpuStatsManager scoped to this GPU.

Example

>>> stats = gpu.stats.get()
>>> print(f"vGPUs: {stats.vgpus}/{stats.vgpus_total}")

property instances: NodeGpuInstanceManager

Access GPU instances assigned to VMs.

Returns:

NodeGpuInstanceManager scoped to this GPU.

Example

>>> for inst in gpu.instances.list():
...     print(f"VM: {inst.machine_name}")

refresh()

Refresh this GPU’s data from the server.

Returns:

Updated NodeGpu object.

Return type:

NodeGpu

save(**kwargs)

Update this GPU with the given values.

Parameters:

**kwargs (Any) – Fields to update.

Returns:

Updated NodeGpu object.

Return type:

NodeGpu

class pyvergeos.resources.gpu.NodeGpuManager

Bases: ResourceManager[NodeGpu]

Manager for node GPU operations.

Provides CRUD operations for GPU configurations on nodes. Can be used globally or scoped to a specific node.

Example

>>> # List all GPUs on a node
>>> for gpu in node.gpus.list():
...     print(f"{gpu.name}: {gpu.mode_display}")

>>> # Configure a GPU for passthrough
>>> gpu = node.gpus.update(gpu.key, mode="gpu")

>>> # Configure for vGPU with a specific profile
>>> gpu = node.gpus.update(
...     gpu.key,
...     mode="nvidia_vgpu",
...     nvidia_vgpu_profile=profile.key
... )

__init__(client, node_key=None)

Parameters:

• client (VergeClient)

• node_key (int | None)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, mode=None, enabled_only=False, **filter_kwargs)

List node GPUs.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• mode (Literal['none', 'gpu', 'nvidia_vgpu'] | None) – Filter by GPU mode.

• enabled_only (bool) – Only return GPUs with a mode set (not ‘none’).

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of NodeGpu objects.

Return type:

list[NodeGpu]

Example

>>> # List all GPUs on a node
>>> gpus = node.gpus.list()

>>> # List only passthrough GPUs
>>> passthrough_gpus = node.gpus.list(mode="gpu")

>>> # List enabled GPUs
>>> enabled = node.gpus.list(enabled_only=True)

get(key=None, *, name=None, fields=None)

Get a GPU by key or name.

Parameters:

• key (int | None) – GPU $key (ID).

• name (str | None) – GPU name.

• fields (list[str] | None) – List of fields to return.

Returns:

NodeGpu object.

Raises:

• NotFoundError – If GPU not found.

• ValueError – If neither key nor name provided.

Return type:

NodeGpu

update(key, **kwargs)

Update a GPU configuration.

Parameters:

• key (int) – GPU $key (ID).

• **kwargs (Any) – Fields to update. Common fields: - name: GPU name - description: Description - mode: Operating mode (‘none’, ‘gpu’, ‘nvidia_vgpu’) - nvidia_vgpu_profile: vGPU profile key (for nvidia_vgpu mode)

Returns:

Updated NodeGpu object.

Return type:

NodeGpu

Example

>>> # Enable PCI passthrough
>>> gpu = client.nodes.gpus(node_key).update(gpu.key, mode="gpu")

>>> # Enable vGPU mode with a profile
>>> gpu = client.nodes.gpus(node_key).update(
...     gpu.key,
...     mode="nvidia_vgpu",
...     nvidia_vgpu_profile=profile.key
... )

>>> # Disable GPU
>>> gpu = client.nodes.gpus(node_key).update(gpu.key, mode="none")

class pyvergeos.resources.gpu.NodeGpuStats

Bases: ResourceObject

Node GPU stats resource object.

Provides current GPU utilization metrics.

property gpu_key: int

Parent GPU key.

property gpus_total: int

Total GPU slots available.

property gpus: int

GPUs in use.

property gpus_idle: int

Idle GPU slots.

property vgpus_total: int

Total vGPU slots available.

property vgpus: int

vGPUs in use.

property vgpus_idle: int

Idle vGPU slots.

property timestamp: datetime | None

Stats timestamp.

class pyvergeos.resources.gpu.NodeGpuStatsHistory

Bases: ResourceObject

Node GPU stats history record.

Represents a single time point in the GPU stats history.

property gpu_key: int

Parent GPU key.

property timestamp: datetime | None

Timestamp for this history point.

property timestamp_epoch: int

Timestamp as Unix epoch.

property gpus_total: int

Total GPU slots available.

property gpus: int

GPUs in use.

property gpus_idle: int

Idle GPU slots.

property vgpus_total: int

Total vGPU slots available.

property vgpus: int

vGPUs in use.

property vgpus_idle: int

Idle vGPU slots.

class pyvergeos.resources.gpu.NodeGpuStatsManager

Bases: ResourceManager[NodeGpuStats]

Manager for node GPU stats.

Provides access to current and historical GPU utilization metrics. Scoped to a specific GPU.

Example

>>> # Get current stats
>>> stats = gpu.stats.get()
>>> print(f"vGPUs: {stats.vgpus}/{stats.vgpus_total}")

>>> # Get stats history
>>> history = gpu.stats.history_short(limit=100)

__init__(client, gpu_key)

Parameters:

• client (VergeClient)

• gpu_key (int)

Return type:

None

get(fields=None)

Get current GPU stats.

Parameters:

fields (list[str] | None) – List of fields to return.

Returns:

NodeGpuStats object.

Raises:

NotFoundError – If stats not found for this GPU.

Return type:

NodeGpuStats

history_short(limit=None, offset=None, since=None, until=None, fields=None)

Get short-term GPU stats history (high resolution).

Parameters:

• limit (int | None) – Maximum number of records to return.

• offset (int | None) – Skip this many records.

• since (datetime | int | None) – Return records after this time (datetime or epoch).

• until (datetime | int | None) – Return records before this time (datetime or epoch).

• fields (list[str] | None) – List of fields to return.

Returns:

List of NodeGpuStatsHistory objects, sorted by timestamp descending.

Return type:

list[NodeGpuStatsHistory]

history_long(limit=None, offset=None, since=None, until=None, fields=None)

Get long-term GPU stats history (lower resolution, longer retention).

Parameters:

• limit (int | None) – Maximum number of records to return.

• offset (int | None) – Skip this many records.

• since (datetime | int | None) – Return records after this time (datetime or epoch).

• until (datetime | int | None) – Return records before this time (datetime or epoch).

• fields (list[str] | None) – List of fields to return.

Returns:

List of NodeGpuStatsHistory objects, sorted by timestamp descending.

Return type:

list[NodeGpuStatsHistory]

class pyvergeos.resources.gpu.NodeGpuInstance

Bases: ResourceObject

Node GPU instance resource object.

Represents a GPU or vGPU instance assigned to a VM.

property gpu_key: int

Parent GPU key.

property gpu_name: str

Parent GPU name.

property node_key: int | None

Node key.

property node_name: str

Node name.

property machine_key: int | None

Machine (VM) key.

property machine_name: str

Machine (VM) name.

property machine_type: str

Machine type (e.g., ‘vm’).

property machine_type_display: str

Machine type display name.

property machine_device_key: int | None

Machine device key.

property machine_device_name: str

Machine device name.

property machine_device_status: str

Machine device status.

property pci_device_key: int | None

PCI device key.

property pci_device_name: str

PCI device name.

property mode: str

GPU mode (gpu, nvidia_vgpu).

property mode_display: str

GPU mode display name.

property description: str

Instance description.

property modified_at: datetime | None

Timestamp when instance was last modified.

class pyvergeos.resources.gpu.NodeGpuInstanceManager

Bases: ResourceManager[NodeGpuInstance]

Manager for node GPU instances.

Provides read-only access to GPU instances assigned to VMs. Scoped to a specific GPU.

Example

>>> # List instances for a GPU
>>> for inst in gpu.instances.list():
...     print(f"VM: {inst.machine_name} ({inst.machine_device_status})")

__init__(client, gpu_key)

Parameters:

• client (VergeClient)

• gpu_key (int)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List GPU instances.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of NodeGpuInstance objects.

Return type:

list[NodeGpuInstance]

class pyvergeos.resources.gpu.NodeVgpuDevice

Bases: ResourceObject

Node vGPU device resource object.

Represents a physical NVIDIA vGPU-capable device on a node. These are detected automatically by the system.

property node_key: int | None

Parent node key.

property node_name: str

Parent node name.

property pci_device_key: int | None

Associated PCI device key.

property name: str

Device name.

property slot: str

PCI slot.

property vendor: str

Vendor name.

property device: str

Device description.

property vendor_device_hex: str

device ID in hexadecimal.

Type:

Vendor

property driver: str

Current driver.

property module: str

Kernel module.

property numa_node: str

NUMA node.

property iommu_group: str

IOMMU group.

property type_id: int

Device type ID.

property max_instances: int

Maximum vGPU instances.

property physical_function: str

Physical function (for SR-IOV).

property virtual_function: str

Virtual function identifier.

property fingerprint: str

Device fingerprint for live migration.

property created_at: datetime | None

Timestamp when device was detected.

property modified_at: datetime | None

Timestamp when device was last updated.

class pyvergeos.resources.gpu.NodeVgpuDeviceManager

Bases: ResourceManager[NodeVgpuDevice]

Manager for node vGPU device operations.

Provides read-only access to NVIDIA vGPU-capable devices on nodes. Can be used globally or scoped to a specific node.

Example

>>> # List all vGPU devices on a node
>>> for device in node.vgpu_devices.list():
...     print(f"{device.name}: {device.vendor} {device.device}")

>>> # List all vGPU devices across all nodes
>>> for device in client.nodes.all_vgpu_devices.list():
...     print(f"{device.node_name}: {device.name}")

__init__(client, node_key=None)

Parameters:

• client (VergeClient)

• node_key (int | None)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, vendor=None, **filter_kwargs)

List vGPU-capable devices.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• vendor (str | None) – Filter by vendor name (contains).

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of NodeVgpuDevice objects.

Return type:

list[NodeVgpuDevice]

get(key, *, fields=None)

Get a vGPU device by key.

Parameters:

• key (int) – Device $key (ID).

• fields (list[str] | None) – List of fields to return.

Returns:

NodeVgpuDevice object.

Raises:

NotFoundError – If device not found.

Return type:

NodeVgpuDevice

class pyvergeos.resources.gpu.NodeHostGpuDevice

Bases: ResourceObject

Node host GPU device resource object.

Represents a physical GPU device available for host GPU passthrough. These are detected automatically by the system.

property node_key: int | None

Parent node key.

property node_name: str

Parent node name.

property pci_device_key: int | None

Associated PCI device key.

property name: str

Device name.

property slot: str

PCI slot.

property vendor: str

Vendor name.

property device: str

Device description.

property vendor_device_hex: str

device ID in hexadecimal.

Type:

Vendor

property driver: str

Current driver.

property module: str

Kernel module.

property numa_node: str

NUMA node.

property iommu_group: str

IOMMU group.

property type_id: int

Device type ID.

property device_index: int

Device index.

property max_instances: int

Maximum instances (typically 1 for passthrough).

property fingerprint: str

Device fingerprint for live migration.

property created_at: datetime | None

Timestamp when device was detected.

property modified_at: datetime | None

Timestamp when device was last updated.

class pyvergeos.resources.gpu.NodeHostGpuDeviceManager

Bases: ResourceManager[NodeHostGpuDevice]

Manager for node host GPU device operations.

Provides read-only access to GPUs available for host passthrough on nodes. Can be used globally or scoped to a specific node.

Example

>>> # List all host GPUs on a node
>>> for device in node.host_gpu_devices.list():
...     print(f"{device.name}: {device.vendor} {device.device}")

>>> # List all host GPUs across all nodes
>>> for device in client.nodes.all_host_gpu_devices.list():
...     print(f"{device.node_name}: {device.name}")

__init__(client, node_key=None)

Parameters:

• client (VergeClient)

• node_key (int | None)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, vendor=None, **filter_kwargs)

List host GPU devices.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• vendor (str | None) – Filter by vendor name (contains).

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of NodeHostGpuDevice objects.

Return type:

list[NodeHostGpuDevice]

get(key, *, fields=None)

Get a host GPU device by key.

Parameters:

• key (int) – Device $key (ID).

• fields (list[str] | None) – List of fields to return.

Returns:

NodeHostGpuDevice object.

Raises:

NotFoundError – If device not found.

Return type:

NodeHostGpuDevice

class pyvergeos.resources.gpu.NodeVgpuProfile

Bases: ResourceObject

Node vGPU profile resource object.

Represents a vGPU profile available on a specific node’s physical GPU. These are determined by the physical hardware and NVIDIA drivers.

property physical_gpu_key: int | None

Associated physical GPU (PCI device) key.

property name: str

Profile name (e.g., ‘nvidia-256’).

property num_heads: int

Number of display heads.

property frl_config: int

Frame rate limiter configuration.

property framebuffer: str

Framebuffer (VRAM) size.

property max_resolution: str

Maximum resolution.

property max_instance: int

Maximum instances per GPU.

property available_instances: int

Currently available instances.

property device_api: str

Device API version.

property profile_type: str

Profile type code (A, B, C, Q).

property profile_type_display: str

Human-readable profile type.

property is_virtual_function: bool

Whether this is a virtual function profile.

property profile_folder: str

Profile folder path.

class pyvergeos.resources.gpu.NodeVgpuProfileManager

Bases: ResourceManager[NodeVgpuProfile]

Manager for node vGPU profile operations.

Provides read-only access to vGPU profiles available on a specific node. These are determined by the physical hardware.

Example

>>> # List profiles available on a node's GPU
>>> for profile in node.vgpu_profiles.list():
...     print(f"{profile.name}: {profile.available_instances} available")

__init__(client, physical_gpu_key=None)

Parameters:

• client (VergeClient)

• physical_gpu_key (int | None)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, profile_type=None, **filter_kwargs)

List vGPU profiles.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• profile_type (Literal['A', 'B', 'C', 'Q'] | None) – Filter by profile type.

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of NodeVgpuProfile objects.

Return type:

list[NodeVgpuProfile]

get(key=None, *, name=None, fields=None)

Get a vGPU profile by key or name.

Parameters:

• key (int | None) – Profile $key (ID).

• name (str | None) – Profile name.

• fields (list[str] | None) – List of fields to return.

Returns:

NodeVgpuProfile object.

Raises:

• NotFoundError – If profile not found.

• ValueError – If neither key nor name provided.

Return type:

NodeVgpuProfile

Devices

VM Device resource manager for device passthrough.

This module provides management of hardware devices attached to VMs, including GPU passthrough, NVIDIA vGPU, USB, PCI, SR-IOV NICs, and TPM.

Example

>>> # List devices attached to a VM
>>> devices = vm.devices.list()
>>> for device in devices:
...     print(f"{device.name}: {device.device_type}")

>>> # Attach a vGPU to a VM
>>> device = vm.devices.create_vgpu(
...     resource_group=vgpu_pool.key,
...     frame_rate_limit=60,
...     attach_guest_drivers=True,
... )

>>> # Attach a USB device
>>> device = vm.devices.create_usb(
...     resource_group=usb_pool.key,
...     allow_guest_reset=True,
... )

class pyvergeos.resources.devices.Device

Bases: ResourceObject

VM device resource object.

Represents a hardware device attached to a VM (GPU, TPM, USB, PCI, SR-IOV, etc.).

Example

>>> device = vm.devices.get(name="vGPU-1")
>>> print(f"Type: {device.device_type}, Status: {device.status}")

property machine_key: int

Parent machine (VM) key.

property machine_name: str

Parent machine (VM) name.

property machine_type: str

Machine type (vm, node, etc.).

property name: str

Device name.

property description: str

Device description.

property device_type: str

Device type (human-readable).

property device_type_raw: str

Raw device type value.

property orderid: int

Device order ID.

property uuid: str

Device UUID.

property is_enabled: bool

Check if device is enabled.

property is_optional: bool

Check if device is optional (machine can start without it).

property resource_group_key: int | None

Associated resource group key.

property resource_group_name: str

Associated resource group name.

property status: str

Device status (human-readable).

property status_raw: str

Raw device status value.

property status_info: str

Additional status information.

property created_at: datetime | None

Timestamp when device was created.

property modified_at: datetime | None

Timestamp when device was last modified.

property is_gpu: bool

Check if this is a GPU device (passthrough or vGPU).

property is_vgpu: bool

Check if this is an NVIDIA vGPU device.

property is_host_gpu: bool

Check if this is a host GPU passthrough device.

property is_tpm: bool

Check if this is a TPM device.

property is_usb: bool

Check if this is a USB device.

property is_pci: bool

Check if this is a PCI device.

property is_sriov: bool

Check if this is an SR-IOV NIC device.

refresh()

Refresh this device’s data from the server.

Returns:

Updated Device object.

Return type:

Device

save(**kwargs)

Update this device with the given values.

Parameters:

**kwargs (Any) – Fields to update.

Returns:

Updated Device object.

Return type:

Device

delete()

Delete this device.

Note

Machine should typically be powered off before removing devices.

Return type:

None

class pyvergeos.resources.devices.DeviceManager

Bases: ResourceManager[Device]

Manager for VM device operations.

Provides CRUD operations for hardware devices attached to VMs, including GPU passthrough, NVIDIA vGPU, USB, PCI, and SR-IOV NICs.

Example

>>> # List all devices on a VM
>>> for device in vm.devices.list():
...     print(f"{device.name}: {device.device_type}")

>>> # Attach a vGPU
>>> device = vm.devices.create_vgpu(
...     resource_group=vgpu_pool.key,
...     frame_rate_limit=60,
... )

>>> # Attach a USB device
>>> device = vm.devices.create_usb(
...     resource_group=usb_pool.key,
... )

__init__(client, machine_key)

Parameters:

• client (VergeClient)

• machine_key (int)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, device_type=None, enabled_only=False, **filter_kwargs)

List devices attached to this machine.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• device_type (Literal['gpu', 'nvidia_vgpu', 'tpm', 'node_usb_devices', 'node_sriov_nic_devices', 'node_pci_devices', 'node_host_gpu_devices', 'node_nvidia_vgpu_devices'] | None) – Filter by device type.

• enabled_only (bool) – Only return enabled devices.

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of Device objects.

Return type:

list[Device]

Example

>>> # List all devices
>>> devices = vm.devices.list()

>>> # List vGPUs only
>>> vgpus = vm.devices.list(device_type="node_nvidia_vgpu_devices")

>>> # List enabled devices
>>> enabled = vm.devices.list(enabled_only=True)

get(key=None, *, name=None, fields=None)

Get a specific device by key or name.

Parameters:

• key (int | None) – Device $key (ID).

• name (str | None) – Device name.

• fields (list[str] | None) – List of fields to return.

Returns:

Device object.

Raises:

• NotFoundError – If device not found.

• ValueError – If neither key nor name provided.

Return type:

Device

create(device_type, name=None, description='', enabled=True, optional=False, resource_group=None, count=1, settings=None, **kwargs)

Create a new device for this machine.

Parameters:

• device_type (Literal['gpu', 'nvidia_vgpu', 'tpm', 'node_usb_devices', 'node_sriov_nic_devices', 'node_pci_devices', 'node_host_gpu_devices', 'node_nvidia_vgpu_devices']) – Type of device to create.

• name (str | None) – Device name (auto-generated if not provided).

• description (str) – Device description.

• enabled (bool) – Whether device is enabled.

• optional (bool) – Allow machine to start without this device.

• resource_group (int | None) – Resource group key for the device.

• count (int) – Number of devices to create from the resource group.

• settings (dict[str, Any] | None) – Device-specific settings (passed as settings_args).

• **kwargs (Any) – Additional device fields.

Returns:

Created Device object.

Return type:

Device

Example

>>> device = vm.devices.create(
...     device_type="node_nvidia_vgpu_devices",
...     resource_group=vgpu_pool.key,
...     settings={"frame_rate_limiter": 60}
... )

create_vgpu(resource_group, name=None, *, frame_rate_limit=60, attach_guest_drivers=False, disable_console_vnc=False, enable_unified_memory=False, enable_cuda_debuggers=False, enable_cuda_profilers=False, profile_type='any', enabled=True, optional=False, count=1)

Create an NVIDIA vGPU device.

Parameters:

• resource_group (int) – Resource group key for the vGPU pool.

• name (str | None) – Device name (auto-generated if not provided).

• frame_rate_limit (int) – Frame rate limiter (0 to disable, default 60).

• attach_guest_drivers (bool) – Attach guest drivers ISO to this machine.

• disable_console_vnc (bool) – Disable VNC console (use RDP instead).

• enable_unified_memory (bool) – Enable NVIDIA unified memory.

• enable_cuda_debuggers (bool) – Enable NVIDIA CUDA Toolkit debuggers.

• enable_cuda_profilers (bool) – Enable NVIDIA CUDA Toolkit profilers.

• profile_type (str) – vGPU profile type filter (default “any”).

• enabled (bool) – Whether device is enabled.

• optional (bool) – Allow machine to start without this device.

• count (int) – Number of vGPU devices to attach.

Returns:

Created Device object.

Return type:

Device

Example

>>> device = vm.devices.create_vgpu(
...     resource_group=vgpu_pool.key,
...     frame_rate_limit=0,  # Compute only, no graphics
...     attach_guest_drivers=True,
... )

create_host_gpu(resource_group, name=None, *, enabled=True, optional=False, count=1)

Create a host GPU passthrough device.

This provides full GPU passthrough to a single VM (1:1 mapping).

Parameters:

• resource_group (int) – Resource group key for the host GPU pool.

• name (str | None) – Device name (auto-generated if not provided).

• enabled (bool) – Whether device is enabled.

• optional (bool) – Allow machine to start without this device.

• count (int) – Number of GPUs to attach from the pool.

Returns:

Created Device object.

Return type:

Device

Example

>>> device = vm.devices.create_host_gpu(
...     resource_group=gpu_pool.key,
... )

create_usb(resource_group, name=None, *, allow_guest_reset=True, allow_guest_reset_all=False, enabled=True, optional=False)

Create a USB passthrough device.

Parameters:

• resource_group (int) – Resource group key for the USB device pool.

• name (str | None) – Device name (auto-generated if not provided).

• allow_guest_reset (bool) – Allow VM to reset the USB device.

• allow_guest_reset_all (bool) – Allow VM to reset the USB hub.

• enabled (bool) – Whether device is enabled.

• optional (bool) – Allow machine to start without this device.

Returns:

Created Device object.

Return type:

Device

Example

>>> device = vm.devices.create_usb(
...     resource_group=usb_pool.key,
...     allow_guest_reset=True,
... )

create_pci(resource_group, name=None, *, enabled=True, optional=False, count=1)

Create a PCI passthrough device.

Parameters:

• resource_group (int) – Resource group key for the PCI device pool.

• name (str | None) – Device name (auto-generated if not provided).

• enabled (bool) – Whether device is enabled.

• optional (bool) – Allow machine to start without this device.

• count (int) – Number of PCI devices to attach from the pool.

Returns:

Created Device object.

Return type:

Device

Example

>>> device = vm.devices.create_pci(
...     resource_group=pci_pool.key,
...     count=2,
... )

create_sriov_nic(resource_group, name=None, *, mac_address=None, native_vlan=0, vlan_qos=0, vlan_protocol='802.1Q', max_tx_rate=0, min_tx_rate=0, trust='off', spoof_checking='on', query_rss='default', virtual_link_state='default', enabled=True, optional=False, count=1)

Create an SR-IOV NIC device.

Parameters:

• resource_group (int) – Resource group key for the SR-IOV NIC pool.

• name (str | None) – Device name (auto-generated if not provided).

• mac_address (str | None) – MAC address (auto-generated if not provided).

• native_vlan (int) – VLAN tag (0 disables VLAN tagging).

• vlan_qos (int) – VLAN QOS priority (0-7).

• vlan_protocol (Literal['802.1Q', '802.1ad']) – VLAN protocol (802.1Q or 802.1ad for QinQ).

• max_tx_rate (int) – Maximum transmit bandwidth in Mbps (0 disables).

• min_tx_rate (int) – Minimum transmit bandwidth in Mbps (0 disables).

• trust (Literal['default', 'on', 'off']) – Enable VF trust mode for special features.

• spoof_checking (Literal['default', 'on', 'off']) – Enable MAC spoof checking.

• query_rss (Literal['default', 'on', 'off']) – Allow querying RSS configuration.

• virtual_link_state (Literal['default', 'auto', 'enable', 'disable']) – Virtual link state (auto mirrors PF state).

• enabled (bool) – Whether device is enabled.

• optional (bool) – Allow machine to start without this device.

• count (int) – Number of SR-IOV VFs to attach.

Returns:

Created Device object.

Return type:

Device

Example

>>> device = vm.devices.create_sriov_nic(
...     resource_group=sriov_pool.key,
...     native_vlan=100,
...     max_tx_rate=1000,  # 1 Gbps cap
... )

create_tpm(name=None, *, enabled=True, optional=False)

Create a virtual TPM (Trusted Platform Module) device.

TPM provides hardware-based security features for the VM.

Parameters:

• name (str | None) – Device name (auto-generated if not provided).

• enabled (bool) – Whether device is enabled.

• optional (bool) – Allow machine to start without this device.

Returns:

Created Device object.

Return type:

Device

Example

>>> device = vm.devices.create_tpm()

update(key, **kwargs)

Update a device.

Parameters:

• key (int) – Device $key (ID).

• **kwargs (Any) – Fields to update. Common fields: - name: Device name - description: Description - enabled: Whether enabled - optional: Whether optional - settings_args: Device-specific settings

Returns:

Updated Device object.

Return type:

Device

Example

>>> device = vm.devices.update(
...     device.key,
...     enabled=False,
... )

delete(key)

Delete a device.

Parameters:

key (int) – Device $key (ID).

Return type:

None

Note

Machine should typically be powered off before removing devices.

Logs

Log resource manager for VergeOS system logs.

class pyvergeos.resources.logs.Log

Bases: ResourceObject

Log resource object.

Represents a log entry in VergeOS system logs including audit events, messages, warnings, errors, and critical events.

Properties:

level: Log severity (critical, error, warning, message, audit, summary, debug). level_display: Capitalized display name for level. text: Log message text. user: User who performed the action. object_type: API object type value (vm, vnet, etc.). object_type_display: Friendly object type name (VM, Network, etc.). object_name: Name of the related object. created_at: Datetime when log was created (from microsecond timestamp). timestamp_us: Raw timestamp in microseconds.

property level: str

Get log severity level.

property level_display: str

Get capitalized level display name.

property text: str

Get log message text.

property user: str

Get user who performed the action.

property object_type: str

Get API object type value.

property object_type_display: str

Get friendly object type name.

property object_name: str

Get name of the related object.

property timestamp_us: int

Get raw timestamp in microseconds.

property created_at: datetime | None

Get datetime when log was created.

Converts the microsecond timestamp to a datetime object.

class pyvergeos.resources.logs.LogManager

Bases: ResourceManager[Log]

Manager for Log operations.

Logs provide an audit trail and history of events in the VergeOS system, including user actions, system events, errors, and warnings.

Example

>>> # List recent logs
>>> logs = client.logs.list(limit=100)
>>> for log in logs:
...     print(f"{log.level_display}: {log.text}")

>>> # List errors and critical logs
>>> errors = client.logs.list(level=["error", "critical"])

>>> # Filter by object type
>>> vm_logs = client.logs.list(object_type="VM")

>>> # Filter by user
>>> admin_logs = client.logs.list(user="admin")

>>> # Filter by time range (last hour)
>>> from datetime import datetime, timedelta, timezone
>>> since = datetime.now(timezone.utc) - timedelta(hours=1)
>>> recent = client.logs.list(since=since)

>>> # Search log text
>>> power_logs = client.logs.list(text="power")

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=100, offset=None, *, level=None, object_type=None, user=None, text=None, since=None, before=None, errors_only=False, **filter_kwargs)

List logs with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results (default: 100, max: 10000).

• offset (int | None) – Skip this many results.

• level (str | list[str] | None) – Filter by severity level (or list of levels). Values: critical, error, warning, message, audit, summary, debug.

• object_type (str | None) – Filter by object type. Values: VM, Network, Tenant, User, System, Node, Cluster, File, Group, Permission, SMTP, Task, Site, etc.

• user (str | None) – Filter logs by user (contains search).

• text (str | None) – Filter logs containing this text (contains search).

• since (datetime | None) – Return logs since this datetime.

• before (datetime | None) – Return logs before this datetime.

• errors_only (bool) – Shortcut to filter for error and critical logs only.

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of Log objects sorted by timestamp (newest first).

Return type:

list[Log]

Example

>>> # Recent logs
>>> logs = client.logs.list()

>>> # Error and critical logs only
>>> errors = client.logs.list(errors_only=True)

>>> # VM logs from the last hour
>>> from datetime import datetime, timedelta, timezone
>>> since = datetime.now(timezone.utc) - timedelta(hours=1)
>>> vm_logs = client.logs.list(object_type="VM", since=since)

>>> # Search for specific text
>>> logs = client.logs.list(text="snapshot")

list_errors(limit=100, since=None)

List error and critical logs.

Parameters:

• limit (int | None) – Maximum number of results.

• since (datetime | None) – Return logs since this datetime.

Returns:

List of error and critical Log objects.

Return type:

list[Log]

Example

>>> errors = client.logs.list_errors()
>>> for log in errors:
...     print(f"[{log.level_display}] {log.text}")

list_by_level(level, limit=100, since=None)

List logs by severity level.

Parameters:

• level (str) – Log level (critical, error, warning, message, audit, summary, debug).

• limit (int | None) – Maximum number of results.

• since (datetime | None) – Return logs since this datetime.

Returns:

List of Log objects at the specified level.

Return type:

list[Log]

Example

>>> warnings = client.logs.list_by_level("warning")

list_by_object_type(object_type, limit=100, since=None)

List logs by object type.

Parameters:

• object_type (str) – Object type (VM, Network, Tenant, User, System, Node, etc.).

• limit (int | None) – Maximum number of results.

• since (datetime | None) – Return logs since this datetime.

Returns:

List of Log objects for the specified object type.

Return type:

list[Log]

Example

>>> vm_logs = client.logs.list_by_object_type("VM")
>>> network_logs = client.logs.list_by_object_type("Network")

list_by_user(user, limit=100, since=None)

List logs by user.

Parameters:

• user (str) – Username to filter by (contains search).

• limit (int | None) – Maximum number of results.

• since (datetime | None) – Return logs since this datetime.

Returns:

List of Log objects for the specified user.

Return type:

list[Log]

Example

>>> admin_logs = client.logs.list_by_user("admin")

search(text, limit=100, since=None, level=None, object_type=None)

Search logs by text content.

Parameters:

• text (str) – Text to search for (case-insensitive contains search).

• limit (int | None) – Maximum number of results.

• since (datetime | None) – Return logs since this datetime.

• level (str | list[str] | None) – Filter by severity level(s).

• object_type (str | None) – Filter by object type.

Returns:

List of Log objects containing the search text.

Return type:

list[Log]

Example

>>> power_logs = client.logs.search("power")
>>> snapshot_errors = client.logs.search(
...     "snapshot", level=["error", "critical"]
... )

get(key=None, *, name=None, fields=None)

Get a log entry by key.

Note: Logs do not have a name field, so name parameter is not supported.

Parameters:

• key (int | None) – Log $key (ID).

• name (str | None) – Not supported for logs (will raise ValueError).

• fields (list[str] | None) – List of fields to return.

Returns:

Log object.

Raises:

• NotFoundError – If log not found.

• ValueError – If key not provided or if name is used.

Return type:

Log

Example

>>> log = client.logs.get(12345)
>>> print(f"{log.level_display}: {log.text}")

Alarms

Alarm resource manager for VergeOS system monitoring.

class pyvergeos.resources.alarms.Alarm

Bases: ResourceObject

Alarm resource object.

Represents an active alarm in VergeOS indicating a condition requiring attention such as errors, warnings, or critical issues.

Properties:

level: Alarm severity (critical, error, warning, message, audit). level_display: Capitalized display name for level. status: Alarm status message. alarm_type: Alarm type name. alarm_type_key: Alarm type $key. description: Alarm type description. alarm_id: Unique alarm identifier (8-char string). owner_name: Name of the owner object. owner_key: Key of the owner object. owner_type: API owner type value (vms, vnets, etc.). owner_type_display: Friendly owner type name (VM, Network, etc.). sub_owner: Sub-owner key if applicable. is_resolvable: True if alarm can be resolved. resolve_text: Text describing how to resolve. is_snoozed: True if alarm is currently snoozed. snoozed_by: User who snoozed the alarm. snooze_until: Datetime when snooze expires. created_at: Datetime when alarm was raised. modified_at: Datetime when alarm was last modified.

property level: str

Get alarm severity level.

property level_display: str

Get capitalized level display name.

property status: str

Get alarm status message.

property alarm_type: str

Get alarm type name.

property alarm_type_key: int | None

Get alarm type $key.

property description: str

Get alarm type description.

property alarm_id: str

Get unique alarm identifier (8-char string).

property owner_name: str

Get owner object name.

property owner_key: int | None

Get owner object key.

property owner_type: str

Get API owner type value.

property owner_type_display: str

Get friendly owner type name.

property sub_owner: int | None

Get sub-owner key if applicable.

property is_resolvable: bool

Check if alarm can be resolved.

property resolve_text: str

Get text describing how to resolve.

property is_snoozed: bool

Check if alarm is currently snoozed.

property snoozed_by: str

Get user who snoozed the alarm.

property snooze_until: datetime | None

Get datetime when snooze expires.

property created_at: datetime | None

Get datetime when alarm was raised.

property modified_at: datetime | None

Get datetime when alarm was last modified.

snooze(hours=24)

Snooze this alarm for a specified duration.

Parameters:

hours (int) – Number of hours to snooze (default: 24, max: 8760).

Returns:

Updated Alarm object.

Return type:

Alarm

snooze_to(until)

Snooze this alarm until a specific time.

Parameters:

until (datetime) – Datetime when snooze should expire.

Returns:

Updated Alarm object.

Return type:

Alarm

unsnooze()

Remove snooze from this alarm, making it active again.

Returns:

Updated Alarm object.

Return type:

Alarm

resolve()

Resolve this alarm.

Raises:

• ValueError – If alarm is not resolvable.

• APIError – If resolve action fails.

Return type:

None

class pyvergeos.resources.alarms.AlarmHistory

Bases: ResourceObject

Alarm history resource object.

Represents a resolved/lowered alarm in the history.

Properties:

level: Alarm severity when raised. level_display: Capitalized display name for level. status: Alarm status message. alarm_type: Alarm type name. alarm_id: Unique alarm identifier. owner: Owner object description (string in history). archived_by: How the alarm was archived (auto, user, etc.). raised_at: Datetime when alarm was raised. lowered_at: Datetime when alarm was lowered/resolved.

property level: str

Get alarm severity level.

property level_display: str

Get capitalized level display name.

property status: str

Get alarm status message.

property alarm_type: str

Get alarm type name.

property alarm_id: str

Get unique alarm identifier.

property owner: str

Get owner description.

property archived_by: str

Get how alarm was archived.

property raised_at: datetime | None

Get datetime when alarm was raised.

property lowered_at: datetime | None

Get datetime when alarm was lowered/resolved.

class pyvergeos.resources.alarms.AlarmManager

Bases: ResourceManager[Alarm]

Manager for Alarm operations.

Alarms indicate conditions requiring attention such as errors, warnings, or critical issues with VMs, networks, nodes, or the system.

Example

>>> # List all active alarms
>>> alarms = client.alarms.list()
>>> for alarm in alarms:
...     print(f"{alarm.level_display}: {alarm.status}")

>>> # List critical and error alarms
>>> critical = client.alarms.list(level=["critical", "error"])

>>> # List alarms by owner type
>>> vm_alarms = client.alarms.list(owner_type="VM")

>>> # Snooze an alarm
>>> client.alarms.snooze(alarm_key, hours=24)

>>> # Resolve a resolvable alarm
>>> client.alarms.resolve(alarm_key)

>>> # Get alarm history
>>> history = client.alarms.list_history()

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, level=None, owner_type=None, include_snoozed=False, **filter_kwargs)

List alarms with optional filtering.

By default, only returns active (non-snoozed) alarms.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• level (str | list[str] | None) – Filter by severity level (or list of levels). Values: critical, error, warning, message, audit, summary, debug.

• owner_type (str | None) – Filter by owner type. Values: VM, Network, Node, Tenant, User, System, CloudSnapshot.

• include_snoozed (bool) – If True, include snoozed alarms (default: False).

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of Alarm objects sorted by created date (newest first).

Return type:

list[Alarm]

Example

>>> # All active alarms
>>> alarms = client.alarms.list()

>>> # Critical alarms only
>>> critical = client.alarms.list(level="critical")

>>> # Critical and error alarms
>>> severe = client.alarms.list(level=["critical", "error"])

>>> # VM alarms
>>> vm_alarms = client.alarms.list(owner_type="VM")

>>> # Include snoozed alarms
>>> all_alarms = client.alarms.list(include_snoozed=True)

list_critical(include_snoozed=False, limit=None)

List critical alarms.

Parameters:

• include_snoozed (bool) – If True, include snoozed alarms.

• limit (int | None) – Maximum number of results.

Returns:

List of critical Alarm objects.

Return type:

list[Alarm]

list_errors(include_snoozed=False, limit=None)

List error alarms.

Parameters:

• include_snoozed (bool) – If True, include snoozed alarms.

• limit (int | None) – Maximum number of results.

Returns:

List of error Alarm objects.

Return type:

list[Alarm]

list_warnings(include_snoozed=False, limit=None)

List warning alarms.

Parameters:

• include_snoozed (bool) – If True, include snoozed alarms.

• limit (int | None) – Maximum number of results.

Returns:

List of warning Alarm objects.

Return type:

list[Alarm]

list_by_owner_type(owner_type, include_snoozed=False, limit=None)

List alarms by owner type.

Parameters:

• owner_type (str) – Owner type (VM, Network, Node, Tenant, User, System, CloudSnapshot).

• include_snoozed (bool) – If True, include snoozed alarms.

• limit (int | None) – Maximum number of results.

Returns:

List of Alarm objects for the specified owner type.

Return type:

list[Alarm]

get(key=None, *, name=None, fields=None)

Get an alarm by key.

Note: Alarms do not have a name field, so name parameter is not supported.

Parameters:

• key (int | None) – Alarm $key (ID).

• name (str | None) – Not supported for alarms (will raise ValueError).

• fields (list[str] | None) – List of fields to return.

Returns:

Alarm object.

Raises:

• NotFoundError – If alarm not found.

• ValueError – If key not provided or if name is used.

Return type:

Alarm

snooze(key, hours=24)

Snooze an alarm for a specified duration.

Snoozing temporarily hides the alarm from the active alarm list.

Parameters:

• key (int) – Alarm $key.

• hours (int) – Number of hours to snooze (default: 24, max: 8760 / 1 year).

Returns:

Updated Alarm object.

Return type:

Alarm

Example

>>> # Snooze for 24 hours (default)
>>> alarm = client.alarms.snooze(alarm_key)

>>> # Snooze for 48 hours
>>> alarm = client.alarms.snooze(alarm_key, hours=48)

snooze_to(key, until)

Snooze an alarm until a specific time.

Parameters:

• key (int) – Alarm $key.

• until (datetime) – Datetime when snooze should expire.

Returns:

Updated Alarm object.

Return type:

Alarm

Example

>>> from datetime import datetime, timedelta
>>> next_week = datetime.now() + timedelta(days=7)
>>> alarm = client.alarms.snooze_to(alarm_key, until=next_week)

unsnooze(key)

Remove snooze from an alarm, making it active again.

Parameters:

key (int) – Alarm $key.

Returns:

Updated Alarm object.

Return type:

Alarm

Example

>>> alarm = client.alarms.unsnooze(alarm_key)
>>> print(alarm.is_snoozed)  # False

resolve(key)

Resolve a resolvable alarm.

Only alarms with resolvable=True can be resolved. After resolution, the alarm may be removed or moved to history.

Parameters:

key (int) – Alarm $key.

Raises:

• ValueError – If alarm is not resolvable.

• NotFoundError – If alarm not found.

• APIError – If resolve action fails.

Return type:

None

Example

>>> alarm = client.alarms.get(alarm_key)
>>> if alarm.is_resolvable:
...     client.alarms.resolve(alarm_key)

list_history(filter=None, fields=None, limit=None, offset=None, *, level=None, **filter_kwargs)

List alarm history (resolved/lowered alarms).

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• level (str | list[str] | None) – Filter by severity level (or list of levels).

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of AlarmHistory objects sorted by lowered date (newest first).

Return type:

list[AlarmHistory]

Example

>>> # Recent alarm history
>>> history = client.alarms.list_history(limit=50)

>>> # Critical alarm history
>>> critical_history = client.alarms.list_history(level="critical")

get_history(key, *, fields=None)

Get an alarm history entry by key.

Parameters:

• key (int) – Alarm history $key (ID).

• fields (list[str] | None) – List of fields to return.

Returns:

AlarmHistory object.

Raises:

NotFoundError – If alarm history not found.

Return type:

AlarmHistory

get_summary()

Get a summary of current alarm status.

Returns:

Dictionary with alarm counts by level and status.

Return type:

dict[str, Any]

Example

>>> summary = client.alarms.get_summary()
>>> print(f"Critical: {summary['critical']}")
>>> print(f"Error: {summary['error']}")
>>> print(f"Warning: {summary['warning']}")
>>> print(f"Total: {summary['total']}")
>>> print(f"Snoozed: {summary['snoozed']}")

Update Management

System update configuration and application.

Update management resources for VergeOS system updates.

This module provides programmatic access to VergeOS system updates, including checking for updates, downloading, installing, and monitoring update progress.

Key concepts:

• Update Settings: Main singleton configuration for update behavior

• Update Source: Update server (Verge.io Updates, Trial/NFR, etc.)

• Update Branch: Version branch (stable-4.13, etc.)

• Update Package: Available/installed update packages

• Update Source Package: Packages available from a specific source/branch

• Update Source Status: Current operational status of update source

• Update Log: History of update operations

• Update Dashboard: Aggregated view of update status

Update workflow:

1. Check for updates (refresh from update source)

2. Download available packages

3. Install downloaded packages

4. Reboot nodes (done automatically per-node with workload migration)

Example

>>> # Get update settings
>>> settings = client.update_settings.get()
>>> print(f"Branch: {settings.branch_name}, Source: {settings.source_name}")

>>> # Check for updates
>>> client.update_settings.check()

>>> # Download and install updates
>>> client.update_settings.download()
>>> client.update_settings.install()

>>> # Or do everything at once
>>> client.update_settings.update_all()

>>> # View update logs
>>> for log in client.update_logs.list(limit=10):
...     print(f"{log.level}: {log.text}")

class pyvergeos.resources.updates.UpdateLog

Bases: ResourceObject

Update log entry resource object.

Represents a log entry from update operations.

key

Log entry $key (row ID).

level

Log level (audit, message, warning, error, critical).

text

Log message text.

timestamp

Log timestamp (microseconds since epoch).

user

User who triggered the operation.

object_name

Name of the object related to the log entry.

property is_error: bool

Check if this is an error log entry.

property is_warning: bool

Check if this is a warning log entry.

property is_audit: bool

Check if this is an audit log entry.

class pyvergeos.resources.updates.UpdateLogManager

Bases: ResourceManager[UpdateLog]

Manager for update log operations.

Update logs provide history of update operations including downloads, installs, and errors.

Example

>>> # List recent update logs
>>> for log in client.update_logs.list(limit=20):
...     print(f"{log.level}: {log.text}")

>>> # List errors only
>>> errors = client.update_logs.list_errors()

>>> # List warnings only
>>> warnings = client.update_logs.list_warnings()

list(filter=None, fields=None, limit=None, offset=None, level=None, **filter_kwargs)

List update logs with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• level (str | None) – Filter by log level (audit, message, warning, error, critical).

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of UpdateLog objects, sorted by timestamp descending.

Return type:

list[UpdateLog]

get(key=None, *, fields=None)

Get a single log entry by key.

Parameters:

• key (int | None) – Log entry $key (row ID).

• fields (list[str] | None) – List of fields to return.

Returns:

UpdateLog object.

Raises:

• NotFoundError – If log entry not found.

• ValueError – If key not provided.

Return type:

UpdateLog

list_errors(limit=None)

List error and critical log entries.

Parameters:

limit (int | None) – Maximum number of results.

Returns:

List of error/critical log entries.

Return type:

list[UpdateLog]

list_warnings(limit=None)

List warning log entries.

Parameters:

limit (int | None) – Maximum number of results.

Returns:

List of warning log entries.

Return type:

list[UpdateLog]

class pyvergeos.resources.updates.UpdateBranch

Bases: ResourceObject

Update branch resource object.

Represents an update branch (version stream) like stable-4.13.

key

Branch $key (row ID).

name

Branch name (e.g., ‘stable-4.13’).

description

Human-readable description.

created

Creation timestamp.

class pyvergeos.resources.updates.UpdateBranchManager

Bases: ResourceManager[UpdateBranch]

Manager for update branch operations.

Update branches define version streams available for updates. Branches are typically read-only and managed by the update source.

Example

>>> # List available branches
>>> for branch in client.update_branches.list():
...     print(f"{branch.name}: {branch.description}")

>>> # Get current branch from settings
>>> settings = client.update_settings.get()
>>> current_branch = client.update_branches.get(settings.branch)

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List update branches with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of UpdateBranch objects.

Return type:

list[UpdateBranch]

get(key=None, *, name=None, fields=None)

Get a single branch by key or name.

Parameters:

• key (int | None) – Branch $key (row ID).

• name (str | None) – Branch name.

• fields (list[str] | None) – List of fields to return.

Returns:

UpdateBranch object.

Raises:

• NotFoundError – If branch not found.

• ValueError – If no identifier provided.

Return type:

UpdateBranch

class pyvergeos.resources.updates.UpdateSourceStatus

Bases: ResourceObject

Update source status resource object.

Represents the current operational status of an update source.

key

Status $key (row ID).

source

Parent source key.

status

Current status (idle, refreshing, downloading, installing, applying, error).

info

Additional status information text.

nodes_updated

Count of nodes that have been updated.

last_update

Timestamp of last status change.

property source_key: int | None

Get the parent source key.

property is_idle: bool

Check if source is idle (not performing any operation).

property is_busy: bool

Check if source is currently busy with an operation.

property is_error: bool

Check if source is in error state.

property is_refreshing: bool

Check if source is currently checking for updates.

property is_downloading: bool

Check if source is currently downloading updates.

property is_installing: bool

Check if source is currently installing updates.

property is_applying: bool

Check if source is currently applying updates (rebooting nodes).

class pyvergeos.resources.updates.UpdateSourceStatusManager

Bases: ResourceManager[UpdateSourceStatus]

Manager for update source status operations.

Status objects are read-only and automatically created/updated for each update source.

Example

>>> # Get status for the active update source
>>> settings = client.update_settings.get()
>>> status = client.update_source_status.get_for_source(settings.source)
>>> print(f"Status: {status.status}, Nodes updated: {status.nodes_updated}")

>>> # Check if update is in progress
>>> if status.is_busy:
...     print("Update in progress...")

__init__(client, *, source_key=None)

Parameters:

• client (VergeClient)

• source_key (int | None)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, source=None, **filter_kwargs)

List source status records with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• source (int | None) – Filter by source key. Ignored if manager is scoped.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of UpdateSourceStatus objects.

Return type:

list[UpdateSourceStatus]

get(key=None, *, fields=None)

Get a single status record by key.

Parameters:

• key (int | None) – Status $key (row ID).

• fields (list[str] | None) – List of fields to return.

Returns:

UpdateSourceStatus object.

Raises:

• NotFoundError – If status not found.

• ValueError – If key not provided.

Return type:

UpdateSourceStatus

get_for_source(source_key)

Get status for a specific update source.

Parameters:

source_key (int) – Update source $key.

Returns:

UpdateSourceStatus object.

Raises:

NotFoundError – If status not found.

Return type:

UpdateSourceStatus

class pyvergeos.resources.updates.UpdateSourcePackage

Bases: ResourceObject

Update source package resource object.

Represents a package available from an update source for a specific branch.

key

Package $key (row ID).

name

Package name.

description

Package description.

version

Package version.

branch

Branch key.

source

Source key.

downloaded

Whether the package has been downloaded.

optional

Whether the package is optional.

require_license_feature

License feature required for this package.

created

Creation timestamp.

property branch_key: int | None

Get the branch key.

property source_key: int | None

Get the source key.

property is_downloaded: bool

Check if the package has been downloaded.

property is_optional: bool

Check if the package is optional.

class pyvergeos.resources.updates.UpdateSourcePackageManager

Bases: ResourceManager[UpdateSourcePackage]

Manager for update source package operations.

Source packages represent what’s available from an update source for a specific branch.

Example

>>> # List all available packages
>>> for pkg in client.update_source_packages.list():
...     status = "Downloaded" if pkg.is_downloaded else "Available"
...     print(f"{pkg.name} ({pkg.version}): {status}")

>>> # List packages for a specific source
>>> packages = client.update_source_packages.list(source=1)

>>> # List packages not yet downloaded
>>> pending = client.update_source_packages.list(downloaded=False)

__init__(client, *, source_key=None, branch_key=None)

Parameters:

• client (VergeClient)

• source_key (int | None)

• branch_key (int | None)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, source=None, branch=None, downloaded=None, **filter_kwargs)

List source packages with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• source (int | None) – Filter by source key. Ignored if manager is scoped.

• branch (int | None) – Filter by branch key. Ignored if manager is scoped.

• downloaded (bool | None) – Filter by download status.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of UpdateSourcePackage objects.

Return type:

list[UpdateSourcePackage]

get(key=None, *, name=None, fields=None)

Get a single source package by key or name.

Parameters:

• key (int | None) – Package $key (row ID).

• name (str | None) – Package name (may return multiple, takes first).

• fields (list[str] | None) – List of fields to return.

Returns:

UpdateSourcePackage object.

Raises:

• NotFoundError – If package not found.

• ValueError – If no identifier provided.

Return type:

UpdateSourcePackage

list_pending()

List packages that are available but not yet downloaded.

Returns:

List of packages pending download.

Return type:

list[UpdateSourcePackage]

list_downloaded()

List packages that have been downloaded.

Returns:

List of downloaded packages.

Return type:

list[UpdateSourcePackage]

class pyvergeos.resources.updates.UpdateSource

Bases: ResourceObject

Update source resource object.

Represents an update server (e.g., Verge.io Updates, Trial/NFR).

key

Source $key (row ID).

name

Source name.

description

Source description.

url

Update server URL.

user

Authentication username.

last_updated

Timestamp of last successful update.

last_refreshed

Timestamp of last refresh check.

enabled

Whether the source is enabled.

property is_enabled: bool

Check if the source is enabled.

property status: UpdateSourceStatusManager

Get a status manager scoped to this source.

Returns:

UpdateSourceStatusManager for this source.

property packages: UpdateSourcePackageManager

Get a package manager scoped to this source.

Returns:

UpdateSourcePackageManager for this source.

get_status()

Get the current status for this source.

Returns:

UpdateSourceStatus object.

Return type:

UpdateSourceStatus

refresh()

Trigger a refresh to check for updates.

Returns:

Task information dict or None.

Return type:

dict[str, Any] | None

class pyvergeos.resources.updates.UpdateSourceManager

Bases: ResourceManager[UpdateSource]

Manager for update source operations.

Update sources define where updates come from (Verge.io update servers).

Example

>>> # List available sources
>>> for source in client.update_sources.list():
...     print(f"{source.name}: {source.url}")

>>> # Get the active source
>>> settings = client.update_settings.get()
>>> source = client.update_sources.get(settings.source)

>>> # Check source status
>>> status = source.get_status()
>>> print(f"Status: {status.status}")

list(filter=None, fields=None, limit=None, offset=None, enabled=None, **filter_kwargs)

List update sources with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• enabled (bool | None) – Filter by enabled state.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of UpdateSource objects.

Return type:

list[UpdateSource]

get(key=None, *, name=None, fields=None)

Get a single source by key or name.

Parameters:

• key (int | None) – Source $key (row ID).

• name (str | None) – Source name.

• fields (list[str] | None) – List of fields to return.

Returns:

UpdateSource object.

Raises:

• NotFoundError – If source not found.

• ValueError – If no identifier provided.

Return type:

UpdateSource

create(name, *, url, description=None, user=None, password=None, enabled=True)

Create a new update source.

Parameters:

• name (str) – Source name.

• url (str) – Update server URL.

• description (str | None) – Source description.

• user (str | None) – Authentication username.

• password (str | None) – Authentication password.

• enabled (bool) – Whether the source is enabled.

Returns:

Created UpdateSource object.

Return type:

UpdateSource

update(key, *, name=None, description=None, url=None, user=None, password=None, enabled=None)

Update an update source.

Parameters:

• key (int) – Source $key (row ID).

• name (str | None) – New name.

• description (str | None) – New description.

• url (str | None) – New URL.

• user (str | None) – New username.

• password (str | None) – New password.

• enabled (bool | None) – Enable or disable.

Returns:

Updated UpdateSource object.

Return type:

UpdateSource

delete(key)

Delete an update source.

Parameters:

key (int) – Source $key (row ID).

Raises:

NotFoundError – If source not found.

Return type:

None

action(key, action_name, **kwargs)

Perform an action on an update source.

Parameters:

• key (int) – Source $key (row ID).

• action_name (str) – Action name (refresh, download, install, apply, all).

• **kwargs (Any) – Additional action parameters.

Returns:

Task information dict or None.

Return type:

dict[str, Any] | None

get_status(key)

Get the current status for an update source.

Parameters:

key (int) – Source $key (row ID).

Returns:

UpdateSourceStatus object.

Return type:

UpdateSourceStatus

packages(key)

Get a package manager scoped to a specific source.

Parameters:

key (int) – Source $key (row ID).

Returns:

UpdateSourcePackageManager for the source.

Return type:

UpdateSourcePackageManager

class pyvergeos.resources.updates.UpdatePackage

Bases: ResourceObject

Update package resource object.

Represents an installed or available update package.

key

Package key (name string, not integer).

name

Package name.

description

Package description.

version

Package version.

branch

Branch key.

type

Package type (ybpkg).

optional

Whether the package is optional.

created

Creation timestamp.

modified

Last modified timestamp.

property key: str

Resource primary key ($key) - package name string.

Unlike most resources, update packages use the name as the key.

Raises:

ValueError – If resource has no $key.

property branch_key: int | None

Get the branch key.

property is_optional: bool

Check if the package is optional.

class pyvergeos.resources.updates.UpdatePackageManager

Bases: ResourceManager[UpdatePackage]

Manager for update package operations.

Update packages represent the actual software packages that make up a VergeOS system.

Example

>>> # List all packages
>>> for pkg in client.update_packages.list():
...     print(f"{pkg.name}: {pkg.version}")

>>> # Get a specific package
>>> pkg = client.update_packages.get("yb-system")

list(filter=None, fields=None, limit=None, offset=None, branch=None, **filter_kwargs)

List update packages with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• branch (int | None) – Filter by branch key.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of UpdatePackage objects.

Return type:

list[UpdatePackage]

get(key=None, *, name=None, fields=None)

Get a single package by key (name).

Parameters:

• key (str | None) – Package key (name string).

• name (str | None) – Package name (alias for key).

• fields (list[str] | None) – List of fields to return.

Returns:

UpdatePackage object.

Raises:

• NotFoundError – If package not found.

• ValueError – If no identifier provided.

Return type:

UpdatePackage

class pyvergeos.resources.updates.UpdateSettings

Bases: ResourceObject

Update settings resource object.

Singleton configuration for system update behavior. There is only one update settings record (key=1).

key

Settings $key (always 1).

name

Settings name.

source

Active update source key.

branch

Selected update branch key.

auto_refresh

Automatically check for updates.

auto_update

Automatically install updates.

auto_reboot

Automatically reboot after updates.

update_time

Scheduled update time (HH:MM format).

max_vsan_usage

Maximum vSAN usage percentage for automatic updates.

warm_reboot

Use kexec for faster reboots.

multi_cluster_update

Allow multiple clusters to update simultaneously.

snapshot_cloud_on_update

Take system snapshot before updates.

snapshot_cloud_expire_seconds

Snapshot expiration period.

installed

Whether updates are installed and pending reboot.

reboot_required

Whether a reboot is required.

applying_updates

Whether updates are currently being applied.

release_notes_url

URL to release notes.

anonymize_statistics

Anonymize statistics sent to update server.

property source_key: int | None

Get the active source key.

property source_name: str | None

Get the active source name if available.

property branch_key: int | None

Get the selected branch key.

property branch_name: str | None

Get the selected branch name if available.

property is_auto_refresh: bool

Check if auto-refresh is enabled.

property is_auto_update: bool

Check if auto-update is enabled.

property is_installed: bool

Check if updates are installed and pending reboot.

property is_reboot_required: bool

Check if a reboot is required.

property is_applying_updates: bool

Check if updates are currently being applied.

check()

Check for available updates.

Returns:

Task information dict or None.

Return type:

dict[str, Any] | None

download()

Download available updates.

Returns:

Task information dict or None.

Return type:

dict[str, Any] | None

install()

Install downloaded updates.

Returns:

Task information dict or None.

Return type:

dict[str, Any] | None

update_all(force=False)

Download, install, and reboot in one operation.

Parameters:

force (bool) – Allow unmigratable workloads to be temporarily rebooted.

Returns:

Task information dict or None.

Return type:

dict[str, Any] | None

class pyvergeos.resources.updates.UpdateSettingsManager

Bases: ResourceManager[UpdateSettings]

Manager for update settings operations.

Update settings is a singleton - there is only one record with key=1.

Example

>>> # Get current settings
>>> settings = client.update_settings.get()
>>> print(f"Branch: {settings.branch_name}")
>>> print(f"Auto-refresh: {settings.is_auto_refresh}")

>>> # Check for updates
>>> client.update_settings.check()

>>> # Download available updates
>>> client.update_settings.download()

>>> # Install updates
>>> client.update_settings.install()

>>> # Or do everything at once
>>> client.update_settings.update_all()

>>> # Update settings
>>> client.update_settings.update(
...     auto_refresh=True,
...     update_time="02:00",
...     snapshot_cloud_on_update=True,
... )

get(key=None, *, fields=None)

Get update settings.

Update settings is a singleton (key=1), so the key parameter is optional and ignored.

Parameters:

• key (int | None) – Ignored (settings is always key=1).

• fields (list[str] | None) – List of fields to return.

Returns:

UpdateSettings object.

Return type:

UpdateSettings

update(key=None, *, source=None, branch=None, user=None, password=None, auto_refresh=None, auto_update=None, auto_reboot=None, update_time=None, max_vsan_usage=None, warm_reboot=None, multi_cluster_update=None, snapshot_cloud_on_update=None, snapshot_cloud_expire_seconds=None, anonymize_statistics=None)

Update the update settings.

Parameters:

• key (int | None) – Ignored (settings is always key=1).

• source (int | None) – Update source key.

• branch (int | None) – Update branch key.

• user (str | None) – Update server username.

• password (str | None) – Update server password.

• auto_refresh (bool | None) – Automatically check for updates.

• auto_update (bool | None) – Automatically install updates.

• auto_reboot (bool | None) – Automatically reboot after updates.

• update_time (str | None) – Scheduled update time (HH:MM format).

• max_vsan_usage (int | None) – Maximum vSAN usage percentage (10-100).

• warm_reboot (bool | None) – Use kexec for faster reboots.

• multi_cluster_update (bool | None) – Allow multiple clusters to update simultaneously.

• snapshot_cloud_on_update (bool | None) – Take system snapshot before updates.

• snapshot_cloud_expire_seconds (int | None) – Snapshot expiration period in seconds.

• anonymize_statistics (bool | None) – Anonymize statistics sent to update server.

Returns:

Updated UpdateSettings object.

Return type:

UpdateSettings

check()

Check for available updates.

Triggers a refresh to check the update source for new packages.

Returns:

Task information dict or None.

Return type:

dict[str, Any] | None

Example

>>> result = client.update_settings.check()
>>> if result:
...     task = client.tasks.wait(result.get("task"))

download()

Download available updates.

Downloads packages that are available from the update source.

Returns:

Task information dict or None.

Return type:

dict[str, Any] | None

Example

>>> result = client.update_settings.download()
>>> if result:
...     task = client.tasks.wait(result.get("task"))

install()

Install downloaded updates.

Installs packages that have been downloaded. This prepares them for application during node reboots.

Returns:

Task information dict or None.

Return type:

dict[str, Any] | None

Example

>>> result = client.update_settings.install()
>>> if result:
...     task = client.tasks.wait(result.get("task"))

update_all(force=False)

Download, install, and reboot in one operation.

This is the recommended way to apply updates. It will: 1. Download available packages 2. Install packages 3. Reboot nodes one at a time with workload migration

Parameters:

force (bool) – Allow unmigratable workloads to be temporarily rebooted. Use this if there are VMs that cannot be migrated (e.g., VMs with GPU passthrough).

Returns:

Task information dict or None.

Return type:

dict[str, Any] | None

Example

>>> # Normal update
>>> result = client.update_settings.update_all()

>>> # Force update (allows non-migratable workloads to reboot)
>>> result = client.update_settings.update_all(force=True)

class pyvergeos.resources.updates.UpdateDashboard

Bases: ResourceObject

Update dashboard resource object.

Provides an aggregated view of update status including packages, branches, settings, and logs.

logs

Recent update logs.

packages

Available packages with status.

branches

Available branches.

settings

Current update settings.

node_count

Number of physical nodes.

counts

Event and task counts.

property node_count: int

Get the number of physical nodes.

property event_count: int

Get the number of update-related events.

property task_count: int

Get the number of active update tasks.

get_settings()

Get the settings portion of the dashboard.

Returns:

Settings dict with source, branch, and status info.

Return type:

dict[str, Any]

get_packages()

Get the packages list from the dashboard.

Returns:

List of package dicts with version and status info.

Return type:

list[dict[str, Any]]

get_branches()

Get the available branches from the dashboard.

Returns:

List of branch dicts.

Return type:

list[dict[str, Any]]

get_logs()

Get recent logs from the dashboard.

Returns:

List of log entry dicts.

Return type:

list[dict[str, Any]]

class pyvergeos.resources.updates.UpdateDashboardManager

Bases: ResourceManager[UpdateDashboard]

Manager for update dashboard operations.

The update dashboard provides an aggregated view of the update system including packages, branches, settings, and logs.

Example

>>> # Get the dashboard
>>> dashboard = client.update_dashboard.get()

>>> # Check node count
>>> print(f"Nodes: {dashboard.node_count}")

>>> # Get settings summary
>>> settings = dashboard.get_settings()
>>> print(f"Branch: {settings.get('branch#name')}")

>>> # List packages
>>> for pkg in dashboard.get_packages():
...     print(f"{pkg.get('name')}: {pkg.get('version')}")

get(*, fields=None)

Get the update dashboard.

Parameters:

fields (list[str] | None) – List of fields to return (optional).

Returns:

UpdateDashboard object with aggregated update information.

Return type:

UpdateDashboard

Billing

Resource usage tracking and billing reports.

Billing resource managers for tracking resource usage and chargeback.

This module provides access to system-wide billing records and report generation for tracking resource utilization across the VergeOS system.

Example

>>> # List billing records
>>> records = client.billing.list(limit=100)
>>> for record in records:
...     print(f"{record.created}: {record.used_cores} cores, {record.used_ram_gb}GB RAM")

>>> # Get total storage usage across tiers
>>> record = client.billing.get_latest()
>>> print(f"Tier 0: {record.tier0_used_gb}GB / {record.tier0_total_gb}GB")

>>> # Generate a new billing report
>>> result = client.billing.generate()
>>> print(f"Generated billing report: {result}")

>>> # Get billing data for a time range
>>> from datetime import datetime, timedelta
>>> since = datetime.now() - timedelta(days=30)
>>> records = client.billing.list(since=since)

class pyvergeos.resources.billing.BillingRecord

Bases: ResourceObject

Billing record representing resource usage at a point in time.

Billing records capture system-wide resource utilization metrics for billing and chargeback purposes.

property created: datetime | None

When this billing record was created.

property created_epoch: int

Created timestamp as Unix epoch.

property from_time: datetime | None

Start of the billing period.

property from_epoch: int

From timestamp as Unix epoch.

property to_time: datetime | None

End of the billing period.

property to_epoch: int

To timestamp as Unix epoch.

property sent: datetime | None

When this billing record was sent/reported.

property sent_epoch: int

Sent timestamp as Unix epoch.

property description: str

Description of the billing record.

property used_cores: int

Number of CPU cores used.

property total_cores: int

Total CPU cores available.

property online_cores: int

Number of CPU cores currently online.

property phys_total_cpu: int

Total physical CPU percentage.

property total_nodes: int

Total number of nodes.

property online_nodes: int

Number of nodes currently online.

property running_machines: int

Number of VMs currently running.

property used_ram: int

RAM used in MB.

property used_ram_gb: float

RAM used in GB.

property total_ram: int

Total RAM available in MB.

property total_ram_gb: float

Total RAM available in GB.

property online_ram: int

RAM currently online in MB.

property online_ram_gb: float

RAM currently online in GB.

property phys_ram_used: int

Physical RAM used in bytes.

property phys_ram_used_gb: float

Physical RAM used in GB.

property phys_vram_used: int

Physical VRAM used in bytes.

property phys_vram_used_gb: float

Physical VRAM used in GB.

property tier0_used: int

Tier 0 storage used in bytes.

property tier0_used_gb: float

Tier 0 storage used in GB.

property tier0_total: int

Tier 0 storage total in bytes.

property tier0_total_gb: float

Tier 0 storage total in GB.

property tier1_used: int

Tier 1 storage used in bytes.

property tier1_used_gb: float

Tier 1 storage used in GB.

property tier1_total: int

Tier 1 storage total in bytes.

property tier1_total_gb: float

Tier 1 storage total in GB.

property tier2_used: int

Tier 2 storage used in bytes.

property tier2_used_gb: float

Tier 2 storage used in GB.

property tier2_total: int

Tier 2 storage total in bytes.

property tier2_total_gb: float

Tier 2 storage total in GB.

property tier3_used: int

Tier 3 storage used in bytes.

property tier3_used_gb: float

Tier 3 storage used in GB.

property tier3_total: int

Tier 3 storage total in bytes.

property tier3_total_gb: float

Tier 3 storage total in GB.

property tier4_used: int

Tier 4 storage used in bytes.

property tier4_used_gb: float

Tier 4 storage used in GB.

property tier4_total: int

Tier 4 storage total in bytes.

property tier4_total_gb: float

Tier 4 storage total in GB.

property tier5_used: int

Tier 5 storage used in bytes.

property tier5_used_gb: float

Tier 5 storage used in GB.

property tier5_total: int

Tier 5 storage total in bytes.

property tier5_total_gb: float

Tier 5 storage total in GB.

property gpus_total: int

Total number of physical GPUs.

property gpus_used: int

Number of physical GPUs in use.

property gpus_idle: int

Number of idle physical GPUs.

property vgpus_total: int

Total number of vGPUs.

property vgpus_used: int

Number of vGPUs in use.

property vgpus_idle: int

Number of idle vGPUs.

property workload_datapoints: int

Number of workload data points collected.

property storage_datapoints: int

Number of storage data points collected.

get_tier_stats(tier)

Get stats for a specific storage tier.

Parameters:

tier (int) – Tier number (0-5).

Returns:

Dict with used and total values in bytes and GB.

Raises:

ValueError – If tier is not 0-5.

Return type:

dict[str, Any]

property total_storage_used: int

Total storage used across all tiers in bytes.

property total_storage_used_gb: float

Total storage used across all tiers in GB.

property total_storage_total: int

Total storage capacity across all tiers in bytes.

property total_storage_total_gb: float

Total storage capacity across all tiers in GB.

property cpu_utilization_pct: float

CPU utilization percentage (used_cores / total_cores).

property ram_utilization_pct: float

RAM utilization percentage (used_ram / total_ram).

property gpu_utilization_pct: float

GPU utilization percentage (gpus_used / gpus_total).

property vgpu_utilization_pct: float

vGPU utilization percentage (vgpus_used / vgpus_total).

class pyvergeos.resources.billing.BillingManager

Bases: ResourceManager[BillingRecord]

Manager for billing records.

Provides access to system-wide resource usage records for billing and chargeback purposes. Records are automatically generated and stored by VergeOS.

Example

>>> # List billing records
>>> records = client.billing.list(limit=100)

>>> # Get the latest billing record
>>> latest = client.billing.get_latest()
>>> print(f"CPU: {latest.cpu_utilization_pct:.1f}%")

>>> # Get records for a specific time range
>>> from datetime import datetime, timedelta
>>> since = datetime.now() - timedelta(days=7)
>>> records = client.billing.list(since=since)

>>> # Generate a new billing report
>>> result = client.billing.generate()

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, since=None, until=None, **filter_kwargs)

List billing records.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• since (datetime | int | None) – Return records created after this time (datetime or epoch).

• until (datetime | int | None) – Return records created before this time (datetime or epoch).

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of BillingRecord objects, sorted by created descending.

Return type:

list[BillingRecord]

get(key=None, *, fields=None)

Get a specific billing record by key.

Parameters:

• key (int | None) – Billing record $key (ID).

• fields (list[str] | None) – List of fields to return.

Returns:

BillingRecord object.

Raises:

• NotFoundError – If record not found.

• ValueError – If key not provided.

Return type:

BillingRecord

get_latest(fields=None)

Get the most recent billing record.

Parameters:

fields (list[str] | None) – List of fields to return.

Returns:

Most recent BillingRecord object.

Raises:

NotFoundError – If no billing records exist.

Return type:

BillingRecord

generate()

Generate a new billing report.

Triggers the generation of a new billing record with current resource usage data.

Returns:

Action response from the billing_actions endpoint.

Return type:

dict[str, Any] | None

Example

>>> result = client.billing.generate()
>>> print(f"Generated billing report")

get_summary(since=None, until=None)

Get a summary of billing data over a time period.

Calculates average and peak usage across all billing records in the specified time range.

Parameters:

• since (datetime | int | None) – Start of time range (datetime or epoch).

• until (datetime | int | None) – End of time range (datetime or epoch).

Returns:

• record_count: Number of billing records

• avg_cpu_utilization: Average CPU utilization percentage

• peak_cpu_cores: Peak CPU cores used

• avg_ram_utilization: Average RAM utilization percentage

• peak_ram_gb: Peak RAM usage in GB

• avg_storage_used_gb: Average storage used in GB

• peak_storage_used_gb: Peak storage used in GB

• total_gpus: Total GPUs available

• avg_gpus_used: Average GPUs in use

• total_vgpus: Total vGPUs available

• avg_vgpus_used: Average vGPUs in use

Return type:

Dict with summary statistics including

Backup & DR

Cloud Snapshots

Cloud (system) snapshot resource manager for VergeOS backup/DR.

class pyvergeos.resources.cloud_snapshots.CloudSnapshotVM

Bases: ResourceObject

VM within a cloud snapshot.

Represents a VM captured in a cloud (system) snapshot. Can be used to restore the VM to its state at snapshot time.

Properties:

name: VM name at snapshot time. description: VM description. uuid: VM UUID. machine_uuid: VM machine UUID. cpu_cores: Number of CPU cores. ram_mb: RAM in megabytes. os_family: Operating system family. is_snapshot: Whether this is a snapshot VM. status: Recovery status (idle, importing, complete, error). status_info: Additional status information. original_key: Original VM key at snapshot time. cloud_snapshot_key: Key of the parent cloud snapshot.

property name: str

Get VM name.

property description: str

Get VM description.

property uuid: str | None

Get VM UUID.

property machine_uuid: str | None

Get VM machine UUID.

property cpu_cores: int

Get number of CPU cores.

property ram_mb: int

Get RAM in megabytes.

property os_family: str

Get OS family.

property is_snapshot: bool

Check if this is a snapshot VM.

property status: str

Get recovery status.

property status_info: str

Get status info.

property original_key: int | None

Get original VM key at snapshot time.

property cloud_snapshot_key: int | None

Get parent cloud snapshot key.

class pyvergeos.resources.cloud_snapshots.CloudSnapshotTenant

Bases: ResourceObject

Tenant within a cloud snapshot.

Represents a tenant captured in a cloud (system) snapshot. Can be used to restore the tenant to its state at snapshot time.

Properties:

name: Tenant name at snapshot time. description: Tenant description. uuid: Tenant UUID. nodes: Number of nodes. cpu_cores: Total CPU cores. ram_mb: Total RAM in megabytes. is_snapshot: Whether this is a snapshot tenant. status: Recovery status (idle, importing, complete, error). status_info: Additional status information. original_key: Original tenant key at snapshot time. cloud_snapshot_key: Key of the parent cloud snapshot.

property name: str

Get tenant name.

property description: str

Get tenant description.

property uuid: str | None

Get tenant UUID.

property nodes: int

Get number of nodes.

property cpu_cores: int

Get total CPU cores.

property ram_mb: int

Get total RAM in megabytes.

property is_snapshot: bool

Check if this is a snapshot tenant.

property status: str

Get recovery status.

property status_info: str

Get status info.

property original_key: int | None

Get original tenant key at snapshot time.

property cloud_snapshot_key: int | None

Get parent cloud snapshot key.

class pyvergeos.resources.cloud_snapshots.CloudSnapshotVMManager

Bases: ResourceManager[CloudSnapshotVM]

Manager for VMs within a cloud snapshot.

Provides access to VMs captured in a specific cloud snapshot.

Example

>>> # Get VMs in a snapshot
>>> snapshot = client.cloud_snapshots.get(name="Daily_20260123")
>>> vms = client.cloud_snapshots.vms(snapshot.key).list()
>>> for vm in vms:
...     print(f"{vm.name}: {vm.cpu_cores} cores, {vm.ram_mb} MB RAM")

__init__(client, snapshot_key)

Parameters:

• client (VergeClient)

• snapshot_key (int)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List VMs in this cloud snapshot.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of CloudSnapshotVM objects.

Return type:

list[CloudSnapshotVM]

get(key=None, *, name=None, fields=None)

Get a VM from this snapshot by key or name.

Parameters:

• key (int | None) – VM snapshot $key (ID).

• name (str | None) – VM name within this snapshot.

• fields (list[str] | None) – List of fields to return.

Returns:

CloudSnapshotVM object.

Raises:

• NotFoundError – If VM not found.

• ValueError – If neither key nor name provided.

Return type:

CloudSnapshotVM

class pyvergeos.resources.cloud_snapshots.CloudSnapshotTenantManager

Bases: ResourceManager[CloudSnapshotTenant]

Manager for tenants within a cloud snapshot.

Provides access to tenants captured in a specific cloud snapshot.

Example

>>> # Get tenants in a snapshot
>>> snapshot = client.cloud_snapshots.get(name="Daily_20260123")
>>> tenants = client.cloud_snapshots.tenants(snapshot.key).list()
>>> for tenant in tenants:
...     print(f"{tenant.name}: {tenant.nodes} nodes")

__init__(client, snapshot_key)

Parameters:

• client (VergeClient)

• snapshot_key (int)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List tenants in this cloud snapshot.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of CloudSnapshotTenant objects.

Return type:

list[CloudSnapshotTenant]

get(key=None, *, name=None, fields=None)

Get a tenant from this snapshot by key or name.

Parameters:

• key (int | None) – Tenant snapshot $key (ID).

• name (str | None) – Tenant name within this snapshot.

• fields (list[str] | None) – List of fields to return.

Returns:

CloudSnapshotTenant object.

Raises:

• NotFoundError – If tenant not found.

• ValueError – If neither key nor name provided.

Return type:

CloudSnapshotTenant

class pyvergeos.resources.cloud_snapshots.CloudSnapshot

Bases: ResourceObject

Cloud (system) snapshot resource object.

Represents a cloud snapshot that captures the entire system state including all VMs and tenants at a point in time.

Properties:

name: Snapshot name. description: Snapshot description. created_at: When the snapshot was created. expires_at: When the snapshot expires (None if never). never_expires: Whether the snapshot never expires. snapshot_profile_key: Key of associated snapshot profile. is_private: Whether the snapshot is hidden from tenants. is_remote_sync: Whether this was synced from a remote system. is_immutable: Whether the snapshot is immutable. immutable_status: Immutable status (unlocked, unlocking, locked). immutable_lock_expires_at: When the immutable lock expires. status: Snapshot status (normal, held). status_info: Additional status information.

__init__(data, manager, vms=None, tenants=None)

Parameters:

• data (dict[str, Any])

• manager (ResourceManager[Any])

• vms (list[CloudSnapshotVM] | None)

• tenants (list[CloudSnapshotTenant] | None)

Return type:

None

property name: str

Get snapshot name.

property description: str

Get snapshot description.

property created_at: datetime | None

Get creation timestamp.

property expires_at: datetime | None

Get expiration timestamp (None if never expires).

property never_expires: bool

Check if snapshot never expires.

property snapshot_profile_key: int | None

Get associated snapshot profile key.

property is_private: bool

Check if snapshot is hidden from tenants.

property is_remote_sync: bool

Check if this was synced from a remote system.

property is_immutable: bool

Check if snapshot is immutable.

property immutable_status: str

Get immutable status (unlocked, unlocking, locked).

property is_locked: bool

Check if snapshot is currently locked.

property immutable_lock_expires_at: datetime | None

Get when the immutable lock expires.

property status: str

Get snapshot status (normal, held).

property status_info: str

Get additional status information.

property vms: list[CloudSnapshotVM] | None

Get VMs in this snapshot (if loaded with include_vms=True).

property tenants: list[CloudSnapshotTenant] | None

Get tenants in this snapshot (if loaded with include_tenants=True).

get_vms()

Get all VMs in this snapshot.

Returns:

List of CloudSnapshotVM objects.

Return type:

list[CloudSnapshotVM]

get_tenants()

Get all tenants in this snapshot.

Returns:

List of CloudSnapshotTenant objects.

Return type:

list[CloudSnapshotTenant]

delete()

Delete this snapshot.

Raises:

ValidationError – If snapshot is immutable and locked.

Return type:

None

class pyvergeos.resources.cloud_snapshots.CloudSnapshotManager

Bases: ResourceManager[CloudSnapshot]

Manager for cloud (system) snapshot operations.

Cloud snapshots capture the entire system state including all VMs and tenants at a point in time. They are used for disaster recovery and point-in-time restoration.

Example

>>> # List all snapshots
>>> snapshots = client.cloud_snapshots.list()

>>> # Create a new snapshot
>>> snapshot = client.cloud_snapshots.create(
...     name="Pre-Upgrade",
...     retention_seconds=604800,  # 7 days
... )

>>> # Get a snapshot by name with VMs
>>> snapshot = client.cloud_snapshots.get(
...     name="Daily_20260123",
...     include_vms=True,
... )
>>> for vm in snapshot.vms:
...     print(vm.name)

>>> # Restore a VM from snapshot
>>> client.cloud_snapshots.restore_vm(
...     snapshot_key=snapshot.key,
...     vm_name="WebServer01",
...     new_name="WebServer01-Restored",
... )

>>> # Delete a snapshot
>>> client.cloud_snapshots.delete(snapshot.key)

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

vms(snapshot_key)

Get the VM manager for a snapshot.

Parameters:

snapshot_key (int) – Snapshot $key (ID).

Returns:

CloudSnapshotVMManager for the snapshot.

Return type:

CloudSnapshotVMManager

tenants(snapshot_key)

Get the tenant manager for a snapshot.

Parameters:

snapshot_key (int) – Snapshot $key (ID).

Returns:

CloudSnapshotTenantManager for the snapshot.

Return type:

CloudSnapshotTenantManager

list(filter=None, fields=None, limit=None, offset=None, *, include_expired=False, include_vms=False, include_tenants=False, **filter_kwargs)

List cloud snapshots.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• include_expired (bool) – Include expired snapshots.

• include_vms (bool) – Include VMs for each snapshot.

• include_tenants (bool) – Include tenants for each snapshot.

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of CloudSnapshot objects sorted by creation time (newest first).

Return type:

list[CloudSnapshot]

Example

>>> # All active snapshots
>>> snapshots = client.cloud_snapshots.list()

>>> # All snapshots including expired
>>> snapshots = client.cloud_snapshots.list(include_expired=True)

>>> # Snapshots with VMs and tenants
>>> snapshots = client.cloud_snapshots.list(
...     include_vms=True,
...     include_tenants=True,
... )

get(key=None, *, name=None, fields=None, include_vms=False, include_tenants=False, include_expired=True)

Get a cloud snapshot by key or name.

Parameters:

• key (int | None) – Snapshot $key (ID).

• name (str | None) – Snapshot name.

• fields (list[str] | None) – List of fields to return.

• include_vms (bool) – Include VMs in the snapshot.

• include_tenants (bool) – Include tenants in the snapshot.

• include_expired (bool) – Include expired snapshots when searching by name.

Returns:

CloudSnapshot object.

Raises:

• NotFoundError – If snapshot not found.

• ValueError – If neither key nor name provided.

Return type:

CloudSnapshot

create(name=None, *, retention_seconds=None, retention=None, never_expire=False, min_snapshots=1, immutable=False, private=False, wait=False, wait_timeout=300)

Create a new cloud snapshot.

Parameters:

• name (str | None) – Snapshot name. If not provided, a timestamped name is generated.

• retention_seconds (int | None) – Retention period in seconds (default: 259200 = 3 days).

• retention (timedelta | None) – Retention period as timedelta (alternative to retention_seconds).

• never_expire (bool) – If True, snapshot never expires.

• min_snapshots (int) – Minimum snapshots to retain (default: 1).

• immutable (bool) – Make snapshot immutable (locked, read-only).

• private (bool) – Hide snapshot from tenants.

• wait (bool) – Wait for snapshot creation to complete.

• wait_timeout (int) – Maximum seconds to wait (default: 300).

Returns:

Created CloudSnapshot object.

Raises:

• ValueError – If invalid parameters.

• APIError – If creation fails.

Return type:

CloudSnapshot

Example

>>> # Create with default settings (3-day retention)
>>> snapshot = client.cloud_snapshots.create()

>>> # Create with custom name and retention
>>> snapshot = client.cloud_snapshots.create(
...     name="Pre-Upgrade",
...     retention=timedelta(days=7),
... )

>>> # Create immutable snapshot that never expires
>>> snapshot = client.cloud_snapshots.create(
...     name="Permanent-Backup",
...     never_expire=True,
...     immutable=True,
... )

delete(key)

Delete a cloud snapshot.

Parameters:

key (int) – Snapshot $key (ID).

Raises:

• ValidationError – If snapshot is immutable and locked.

• NotFoundError – If snapshot not found.

Return type:

None

restore_vm(snapshot_key=None, snapshot_name=None, *, vm_key=None, vm_name=None, new_name=None)

Restore a VM from a cloud snapshot.

Creates a new VM from the snapshot data. Does not overwrite any existing VM.

Parameters:

• snapshot_key (int | None) – Cloud snapshot $key (ID).

• snapshot_name (str | None) – Cloud snapshot name (alternative to snapshot_key).

• vm_key (int | None) – VM snapshot key within the cloud snapshot.

• vm_name (str | None) – VM name within the cloud snapshot (alternative to vm_key).

• new_name (str | None) – Optional new name for the restored VM.

Returns:

Dict with restore operation details (task key if available).

Raises:

• ValueError – If required parameters not provided.

• NotFoundError – If snapshot or VM not found.

Return type:

dict[str, Any]

Example

>>> # Restore VM by name
>>> result = client.cloud_snapshots.restore_vm(
...     snapshot_name="Daily_20260123",
...     vm_name="WebServer01",
...     new_name="WebServer01-Restored",
... )

>>> # Restore by keys
>>> result = client.cloud_snapshots.restore_vm(
...     snapshot_key=5,
...     vm_key=123,
... )

restore_tenant(snapshot_key=None, snapshot_name=None, *, tenant_key=None, tenant_name=None, new_name=None)

Restore a tenant from a cloud snapshot.

Creates a new tenant from the snapshot data. Does not overwrite any existing tenant.

Parameters:

• snapshot_key (int | None) – Cloud snapshot $key (ID).

• snapshot_name (str | None) – Cloud snapshot name (alternative to snapshot_key).

• tenant_key (int | None) – Tenant snapshot key within the cloud snapshot.

• tenant_name (str | None) – Tenant name within the cloud snapshot (alternative to tenant_key).

• new_name (str | None) – Optional new name for the restored tenant.

Returns:

Dict with restore operation details (task key if available).

Raises:

• ValueError – If required parameters not provided.

• NotFoundError – If snapshot or tenant not found.

Return type:

dict[str, Any]

Example

>>> # Restore tenant by name
>>> result = client.cloud_snapshots.restore_tenant(
...     snapshot_name="Daily_20260123",
...     tenant_name="CustomerA",
...     new_name="CustomerA-DR",
... )

Snapshot Profiles

Snapshot profile resource manager for VergeOS backup/DR.

class pyvergeos.resources.snapshot_profiles.SnapshotProfilePeriod

Bases: ResourceObject

Snapshot profile period (schedule) resource object.

Represents a snapshot schedule period within a profile. Defines when snapshots are taken and how long they are retained.

Properties:

profile_key: Key of the parent snapshot profile. name: Period name (e.g., “Hourly”, “Daily”). frequency: Schedule frequency (custom, hourly, daily, weekly, monthly, yearly). frequency_display: Capitalized frequency display name. minute: Minute of the hour (0-59). hour: Hour of the day (0-23). day_of_week: Day of week (sun, mon, tue, wed, thu, fri, sat, any). day_of_week_display: Full day name. day_of_month: Day of month (0-31, 0 = any). month: Month (0-12, 0 = any). retention_seconds: Retention period in seconds. retention: Retention as timedelta. retention_display: Human-readable retention string. skip_missed: Skip if snapshot time was missed. max_tier: Maximum storage tier for snapshots (1-5). quiesce: Whether to quiesce disks during snapshot. min_snapshots: Minimum snapshots to retain. is_immutable: Whether snapshots are immutable (system snapshots only). estimated_snapshot_count: Estimated number of snapshots.

property profile_key: int | None

Get parent profile key.

property name: str

Get period name.

property frequency: str

Get schedule frequency.

property frequency_display: str

Get capitalized frequency display name.

property minute: int

Get minute of the hour (0-59).

property hour: int

Get hour of the day (0-23).

property day_of_week: str

Get day of week.

property day_of_week_display: str

Get full day name.

property day_of_month: int

Get day of month (0 = any).

property month: int

Get month (0 = any).

property retention_seconds: int

Get retention in seconds.

property retention: timedelta

Get retention as timedelta.

property retention_display: str

Get human-readable retention string.

property skip_missed: bool

Check if missed snapshots should be skipped.

property max_tier: int

Get maximum storage tier (1-5).

property quiesce: bool

Check if disk quiescing is enabled.

property min_snapshots: int

Get minimum snapshots to retain.

property is_immutable: bool

Check if snapshots are immutable.

property estimated_snapshot_count: int | None

Get estimated snapshot count.

save(**kwargs)

Save changes to period.

Parameters:

**kwargs (Any) – Fields to update.

Returns:

Updated period object.

Return type:

SnapshotProfilePeriod

delete()

Delete this period.

Return type:

None

class pyvergeos.resources.snapshot_profiles.SnapshotProfile

Bases: ResourceObject

Snapshot profile resource object.

Represents a snapshot profile that defines automated snapshot schedules for VMs, NAS volumes, and cloud/system snapshots.

Properties:

name: Profile name. description: Profile description. ignore_warnings: Whether to ignore snapshot count warnings. periods: List of schedule periods (if loaded with include_periods=True).

__init__(data, manager, periods=None)

Parameters:

• data (dict[str, Any])

• manager (ResourceManager[Any])

• periods (list[SnapshotProfilePeriod] | None)

Return type:

None

property name: str

Get profile name.

property description: str

Get profile description.

property ignore_warnings: bool

Check if snapshot count warnings are ignored.

property periods: list[SnapshotProfilePeriod] | None

Get schedule periods (if loaded).

save(**kwargs)

Save changes to profile.

Parameters:

**kwargs (Any) – Fields to update.

Returns:

Updated profile object.

Return type:

SnapshotProfile

delete()

Delete this profile.

Return type:

None

get_periods()

Get all schedule periods for this profile.

Returns:

List of SnapshotProfilePeriod objects.

Return type:

list[SnapshotProfilePeriod]

add_period(name, frequency, retention_seconds, *, minute=0, hour=0, day_of_week='any', day_of_month=0, month=0, skip_missed=False, max_tier=1, quiesce=False, min_snapshots=1, immutable=False)

Add a schedule period to this profile.

Parameters:

• name (str) – Period name.

• frequency (str) – Schedule frequency (hourly, daily, weekly, monthly, yearly, custom).

• retention_seconds (int) – Retention period in seconds.

• minute (int) – Minute of the hour (0-59).

• hour (int) – Hour of the day (0-23).

• day_of_week (str) – Day of week (sun, mon, tue, wed, thu, fri, sat, any).

• day_of_month (int) – Day of month (0-31, 0 = any).

• month (int) – Month (0-12, 0 = any).

• skip_missed (bool) – Skip if snapshot time was missed.

• max_tier (int) – Maximum storage tier (1-5).

• quiesce (bool) – Enable disk quiescing.

• min_snapshots (int) – Minimum snapshots to retain.

• immutable (bool) – Make snapshots immutable (system snapshots only).

Returns:

Created SnapshotProfilePeriod object.

Return type:

SnapshotProfilePeriod

class pyvergeos.resources.snapshot_profiles.SnapshotProfilePeriodManager

Bases: ResourceManager[SnapshotProfilePeriod]

Manager for snapshot profile period operations.

Manages schedule periods within a snapshot profile.

Example

>>> # Get periods for a profile
>>> profile = client.snapshot_profiles.get(name="Daily Backups")
>>> periods = client.snapshot_profiles.periods(profile.key).list()

>>> # Create a period
>>> period = client.snapshot_profiles.periods(profile.key).create(
...     name="Daily",
...     frequency="daily",
...     retention=86400 * 7,  # 7 days
...     hour=2,  # 2 AM
...     minute=0,
... )

>>> # Or use the profile object directly
>>> period = profile.add_period(
...     name="Hourly",
...     frequency="hourly",
...     retention_seconds=86400,  # 1 day
... )

__init__(client, profile_key)

Parameters:

• client (VergeClient)

• profile_key (int)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List periods for this profile.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of SnapshotProfilePeriod objects.

Return type:

list[SnapshotProfilePeriod]

get(key=None, *, name=None, fields=None)

Get a period by key or name.

Parameters:

• key (int | None) – Period $key (ID).

• name (str | None) – Period name within this profile.

• fields (list[str] | None) – List of fields to return.

Returns:

SnapshotProfilePeriod object.

Raises:

• NotFoundError – If period not found.

• ValueError – If neither key nor name provided.

Return type:

SnapshotProfilePeriod

create(name, frequency, retention, *, minute=0, hour=0, day_of_week='any', day_of_month=0, month=0, skip_missed=False, max_tier=1, quiesce=False, min_snapshots=1, immutable=False)

Create a new period in this profile.

Parameters:

• name (str) – Period name (e.g., “Daily”, “Hourly”).

• frequency (str) – Schedule frequency (hourly, daily, weekly, monthly, yearly, custom).

• retention (int) – Retention period in seconds.

• minute (int) – Minute of the hour (0-59).

• hour (int) – Hour of the day (0-23).

• day_of_week (str) – Day of week (sun, mon, tue, wed, thu, fri, sat, any).

• day_of_month (int) – Day of month (0-31, 0 = any).

• month (int) – Month (0-12, 0 = any).

• skip_missed (bool) – Skip if snapshot time was missed.

• max_tier (int) – Maximum storage tier (1-5).

• quiesce (bool) – Enable disk quiescing.

• min_snapshots (int) – Minimum snapshots to retain.

• immutable (bool) – Make snapshots immutable (system snapshots only).

Returns:

Created SnapshotProfilePeriod object.

Raises:

• ValueError – If invalid parameters provided.

• APIError – If creation fails.

Return type:

SnapshotProfilePeriod

update(key, **kwargs)

Update a period.

Parameters:

• key (int) – Period $key (ID).

• **kwargs (Any) – Fields to update (name, frequency, retention, minute, hour, day_of_week, day_of_month, month, skip_missed, max_tier, quiesce, min_snapshots, immutable).

Returns:

Updated SnapshotProfilePeriod object.

Return type:

SnapshotProfilePeriod

delete(key)

Delete a period.

Parameters:

key (int) – Period $key (ID).

Return type:

None

class pyvergeos.resources.snapshot_profiles.SnapshotProfileManager

Bases: ResourceManager[SnapshotProfile]

Manager for snapshot profile operations.

Snapshot profiles define automated snapshot schedules for VMs, NAS volumes, and cloud/system snapshots.

Example

>>> # List all profiles
>>> profiles = client.snapshot_profiles.list()

>>> # Get a profile by name
>>> profile = client.snapshot_profiles.get(name="Daily Backups")

>>> # Create a new profile
>>> profile = client.snapshot_profiles.create(
...     name="Production VMs",
...     description="Snapshot profile for production workloads",
... )

>>> # Add schedule periods
>>> profile.add_period(
...     name="Hourly",
...     frequency="hourly",
...     retention_seconds=86400,  # 1 day
... )
>>> profile.add_period(
...     name="Daily",
...     frequency="daily",
...     retention_seconds=604800,  # 7 days
...     hour=2,
...     minute=0,
... )

>>> # Delete a profile
>>> client.snapshot_profiles.delete(profile.key)

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

periods(profile_key)

Get the period manager for a profile.

Parameters:

profile_key (int) – Profile $key (ID).

Returns:

SnapshotProfilePeriodManager for the profile.

Return type:

SnapshotProfilePeriodManager

list(filter=None, fields=None, limit=None, offset=None, *, include_periods=False, **filter_kwargs)

List snapshot profiles.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• include_periods (bool) – If True, include schedule periods for each profile.

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of SnapshotProfile objects sorted by name.

Return type:

list[SnapshotProfile]

Example

>>> # All profiles
>>> profiles = client.snapshot_profiles.list()

>>> # Profiles with periods
>>> profiles = client.snapshot_profiles.list(include_periods=True)
>>> for profile in profiles:
...     print(f"{profile.name}: {len(profile.periods or [])} periods")

get(key=None, *, name=None, fields=None, include_periods=False)

Get a snapshot profile by key or name.

Parameters:

• key (int | None) – Profile $key (ID).

• name (str | None) – Profile name.

• fields (list[str] | None) – List of fields to return.

• include_periods (bool) – If True, include schedule periods.

Returns:

SnapshotProfile object.

Raises:

• NotFoundError – If profile not found.

• ValueError – If neither key nor name provided.

Return type:

SnapshotProfile

create(name, *, description=None, ignore_warnings=False)

Create a new snapshot profile.

Parameters:

• name (str) – Profile name (must be unique).

• description (str | None) – Optional profile description.

• ignore_warnings (bool) – Ignore snapshot count estimate warnings.

Returns:

Created SnapshotProfile object.

Raises:

• ValueError – If name is empty.

• APIError – If creation fails (e.g., duplicate name).

Return type:

SnapshotProfile

Example

>>> profile = client.snapshot_profiles.create(
...     name="Production VMs",
...     description="Snapshot profile for production workloads",
... )

update(key, **kwargs)

Update a snapshot profile.

Parameters:

• key (int) – Profile $key (ID).

• **kwargs (Any) – Fields to update (name, description, ignore_warnings).

Returns:

Updated SnapshotProfile object.

Return type:

SnapshotProfile

Example

>>> profile = client.snapshot_profiles.update(
...     profile.key,
...     description="Updated description",
... )

delete(key)

Delete a snapshot profile.

Uses the snapshot_profile_actions endpoint with delete action. The profile must not be in use by any VMs, volumes, or cloud snapshots.

Parameters:

key (int) – Profile $key (ID).

Raises:

APIError – If deletion fails (e.g., profile in use).

Return type:

None

Example

>>> client.snapshot_profiles.delete(profile.key)

Sites

Site resource manager for VergeOS backup/DR operations.

class pyvergeos.resources.sites.Site

Bases: ResourceObject

Site resource object representing a connection to a remote VergeOS system.

Sites are used for disaster recovery, replication, and remote management between VergeOS systems.

Properties:

name: Site name. description: Site description. is_enabled: Whether the site is enabled. url: URL of the remote VergeOS system. domain: Domain name for the site. city: City where the site is located. country: Country code where the site is located. timezone: Timezone for the site. latitude: Geographic latitude. longitude: Geographic longitude. status: Site status (idle, authenticating, syncing, error, warning). status_info: Additional status information. authentication_status: Authentication status (unauthenticated, authenticated, legacy). config_cloud_snapshots: Cloud snapshot sync config (disabled, send, receive, both). config_statistics: Statistics sync config (disabled, send, receive, both). config_management: Machine management config (disabled, manage, managed, both). config_repair_server: Repair server config (disabled, send, receive, both). vsan_host: vSAN connection host. vsan_port: vSAN connection port. is_tenant: Whether site is a tenant. has_incoming_syncs: Whether incoming syncs are enabled. has_outgoing_syncs: Whether outgoing syncs are enabled. statistics_interval: Statistics sync interval in seconds. statistics_retention: Statistics retention period in seconds. created_at: When the site was created. modified_at: When the site was last modified. creator: Username who created the site.

property name: str

Get site name.

property description: str

Get site description.

property is_enabled: bool

Check if site is enabled.

property url: str

Get site URL.

property domain: str

Get site domain.

property city: str

Get site city.

property country: str

Get site country code.

property timezone: str

Get site timezone.

property latitude: float | None

Get site latitude.

property longitude: float | None

Get site longitude.

property status: str

Get site status (idle, authenticating, syncing, error, warning).

property status_info: str

Get additional status information.

property authentication_status: str

Get authentication status (unauthenticated, authenticated, legacy).

property is_authenticated: bool

Check if site is authenticated.

property config_cloud_snapshots: str

Get cloud snapshot sync config (disabled, send, receive, both).

property config_statistics: str

Get statistics sync config (disabled, send, receive, both).

property config_management: str

Get machine management config (disabled, manage, managed, both).

property config_repair_server: str

Get repair server config (disabled, send, receive, both).

property vsan_host: str

Get vSAN connection host.

property vsan_port: int

Get vSAN connection port.

property is_tenant: bool

Check if site is a tenant.

property has_incoming_syncs: bool

Check if incoming syncs are enabled.

property has_outgoing_syncs: bool

Check if outgoing syncs are enabled.

property statistics_interval: int

Get statistics sync interval in seconds.

property statistics_retention: int

Get statistics retention period in seconds.

property created_at: datetime | None

Get creation timestamp.

property modified_at: datetime | None

Get last modified timestamp.

property creator: str

Get username who created the site.

enable()

Enable this site.

Returns:

Updated Site object.

Return type:

Site

disable()

Disable this site.

Returns:

Updated Site object.

Return type:

Site

refresh()

Refresh site data from server.

Returns:

Updated Site object.

Return type:

Site

reauthenticate(username, password)

Reauthenticate with the remote site.

Parameters:

• username (str) – Username for authentication.

• password (str) – Password for authentication.

Returns:

Updated Site object.

Return type:

Site

delete()

Delete this site.

Return type:

None

class pyvergeos.resources.sites.SiteManager

Bases: ResourceManager[Site]

Manager for site operations.

Sites represent connections to other VergeOS systems for disaster recovery, replication, and remote management.

Example

>>> # List all sites
>>> sites = client.sites.list()

>>> # Create a new site
>>> site = client.sites.create(
...     name="DR-Site",
...     url="https://dr.example.com",
...     username="admin",
...     password="secret",
...     config_cloud_snapshots="send",
... )

>>> # Get a site by name
>>> site = client.sites.get(name="DR-Site")

>>> # Enable/disable a site
>>> site = client.sites.enable(site.key)
>>> site = client.sites.disable(site.key)

>>> # Delete a site
>>> client.sites.delete(site.key)

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, enabled=None, status=None, **filter_kwargs)

List sites.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• enabled (bool | None) – Filter by enabled status.

• status (str | None) – Filter by status (idle, authenticating, syncing, error, warning).

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of Site objects sorted by name.

Return type:

list[Site]

Example

>>> # All sites
>>> sites = client.sites.list()

>>> # Enabled sites only
>>> sites = client.sites.list(enabled=True)

>>> # Sites with errors
>>> sites = client.sites.list(status="error")

list_enabled(fields=None)

List enabled sites.

Parameters:

fields (list[str] | None) – List of fields to return.

Returns:

List of enabled Site objects.

Return type:

list[Site]

list_disabled(fields=None)

List disabled sites.

Parameters:

fields (list[str] | None) – List of fields to return.

Returns:

List of disabled Site objects.

Return type:

list[Site]

list_by_status(status, fields=None)

List sites by status.

Parameters:

• status (str) – Status to filter by (idle, authenticating, syncing, error, warning).

• fields (list[str] | None) – List of fields to return.

Returns:

List of Site objects with the specified status.

Return type:

list[Site]

get(key=None, *, name=None, fields=None)

Get a site by key or name.

Parameters:

• key (int | None) – Site $key (ID).

• name (str | None) – Site name.

• fields (list[str] | None) – List of fields to return.

Returns:

Site object.

Raises:

• NotFoundError – If site not found.

• ValueError – If neither key nor name provided.

Return type:

Site

create(name, url, username, password, *, description=None, allow_insecure=False, config_cloud_snapshots='disabled', config_statistics='disabled', config_management='disabled', config_repair_server='disabled', auto_create_syncs=True, domain=None, city=None, country=None, timezone=None, request_url=None)

Create a new site connection.

Parameters:

• name (str) – Site name.

• url (str) – URL of the remote VergeOS system.

• username (str) – Username for authentication.

• password (str) – Password for authentication.

• description (str | None) – Optional site description.

• allow_insecure (bool) – Allow insecure SSL connections (for self-signed certs).

• config_cloud_snapshots (str) – Cloud snapshot config (disabled, send, receive, both).

• config_statistics (str) – Statistics config (disabled, send, receive, both).

• config_management (str) – Management config (disabled, manage, managed, both).

• config_repair_server (str) – Repair server config (disabled, send, receive, both).

• auto_create_syncs (bool) – Automatically create sync configurations.

• domain (str | None) – Domain name for the site.

• city (str | None) – City where the site is located.

• country (str | None) – Country code where the site is located.

• timezone (str | None) – Timezone for the site.

• request_url (str | None) – URL the remote system uses to connect back.

Returns:

Created Site object.

Raises:

• ValidationError – If invalid parameters.

• APIError – If creation fails.

Return type:

Site

Example

>>> site = client.sites.create(
...     name="DR-Site",
...     url="https://dr.example.com",
...     username="admin",
...     password="secret",
...     config_cloud_snapshots="send",
...     allow_insecure=True,
... )

update(key, *, name=None, description=None, enabled=None, config_cloud_snapshots=None, config_statistics=None, config_management=None, config_repair_server=None, domain=None, city=None, country=None, timezone=None, statistics_interval=None, statistics_retention=None)

Update a site’s settings.

Parameters:

• key (int) – Site $key (ID).

• name (str | None) – New site name.

• description (str | None) – New site description.

• enabled (bool | None) – Enable or disable the site.

• config_cloud_snapshots (str | None) – Cloud snapshot config (disabled, send, receive, both).

• config_statistics (str | None) – Statistics config (disabled, send, receive, both).

• config_management (str | None) – Management config (disabled, manage, managed, both).

• config_repair_server (str | None) – Repair server config (disabled, send, receive, both).

• domain (str | None) – Domain name for the site.

• city (str | None) – City where the site is located.

• country (str | None) – Country code where the site is located.

• timezone (str | None) – Timezone for the site.

• statistics_interval (int | None) – Statistics sync interval in seconds.

• statistics_retention (int | None) – Statistics retention period in seconds.

Returns:

Updated Site object.

Return type:

Site

delete(key)

Delete a site.

This will also remove all associated sync configurations.

Parameters:

key (int) – Site $key (ID).

Raises:

NotFoundError – If site not found.

Return type:

None

enable(key)

Enable a site.

Parameters:

key (int) – Site $key (ID).

Returns:

Updated Site object.

Return type:

Site

disable(key)

Disable a site.

Parameters:

key (int) – Site $key (ID).

Returns:

Updated Site object.

Return type:

Site

reauthenticate(key, username, password)

Reauthenticate with a remote site.

Use this to update credentials or resolve authentication issues.

Parameters:

• key (int) – Site $key (ID).

• username (str) – Username for authentication.

• password (str) – Password for authentication.

Returns:

Updated Site object.

Return type:

Site

refresh_site(key)

Refresh site data from the remote system.

Parameters:

key (int) – Site $key (ID).

Returns:

Updated Site object.

Return type:

Site

refresh_settings(key)

Refresh site settings from the remote system.

Parameters:

key (int) – Site $key (ID).

Returns:

Updated Site object.

Return type:

Site

Site Syncs

DR synchronization management.

Site sync resource managers for VergeOS backup/DR operations.

class pyvergeos.resources.site_syncs.SiteSyncOutgoing

Bases: ResourceObject

Outgoing site sync resource object.

Outgoing syncs send cloud snapshots from this system to a remote site for disaster recovery purposes.

Properties:

site_key: Key of the associated site. name: Sync name. description: Sync description. is_enabled: Whether the sync is enabled. status: Sync status (offline, initializing, syncing, error). status_info: Additional status information. state: Sync state (offline, online, warning, error). url: Remote URL. has_encryption: Whether encryption is enabled. has_compression: Whether compression is enabled. has_network_integrity: Whether network integrity checking is enabled. data_threads: Number of data threads. file_threads: Number of file threads. send_throttle: Send throttle in bytes/sec (0 = disabled). destination_tier: Override destination storage tier. queue_retry_count: Number of retry attempts for queued items. queue_retry_interval: Retry interval in seconds. has_retry_multiplier: Whether retry interval multiplier is enabled. last_run_at: When the sync last ran. remote_min_snapshots: Minimum snapshots to retain on remote. note: Optional note.

property site_key: int | None

Get the associated site key.

property name: str

Get sync name.

property description: str

Get sync description.

property is_enabled: bool

Check if sync is enabled.

property status: str

Get sync status (offline, initializing, syncing, error).

property status_info: str

Get additional status information.

property state: str

Get sync state (offline, online, warning, error).

property is_syncing: bool

Check if sync is currently syncing.

property is_online: bool

Check if sync is online.

property has_error: bool

Check if sync has an error.

property url: str

Get remote URL.

property has_encryption: bool

Check if encryption is enabled.

property has_compression: bool

Check if compression is enabled.

property has_network_integrity: bool

Check if network integrity checking is enabled.

property data_threads: int

Get number of data threads.

property file_threads: int

Get number of file threads.

property send_throttle: int

Get send throttle in bytes/sec (0 = disabled).

property destination_tier: str

Get override destination storage tier.

property queue_retry_count: int

Get number of retry attempts for queued items.

property queue_retry_interval: int

Get retry interval in seconds.

property has_retry_multiplier: bool

Check if retry interval multiplier is enabled.

property last_run_at: datetime | None

Get when the sync last ran.

property remote_min_snapshots: int

Get minimum snapshots to retain on remote.

property note: str

Get optional note.

enable()

Enable this sync.

Returns:

Updated SiteSyncOutgoing object.

Return type:

SiteSyncOutgoing

disable()

Disable this sync.

Returns:

Updated SiteSyncOutgoing object.

Return type:

SiteSyncOutgoing

start()

Start (enable) this sync.

Alias for enable().

Returns:

Updated SiteSyncOutgoing object.

Return type:

SiteSyncOutgoing

stop()

Stop (disable) this sync.

Alias for disable().

Returns:

Updated SiteSyncOutgoing object.

Return type:

SiteSyncOutgoing

refresh()

Refresh sync data from server.

Returns:

Updated SiteSyncOutgoing object.

Return type:

SiteSyncOutgoing

add_to_queue(snapshot_key, retention=259200, priority=0, do_not_expire=False, destination_prefix=None)

Add a cloud snapshot to the transfer queue.

Parameters:

• snapshot_key (int) – Key of the cloud snapshot to queue.

• retention (int | timedelta) – Retention period in seconds or timedelta. Default 3 days.

• priority (int) – Priority for syncing (lower = first). Default 0.

• do_not_expire (bool) – If True, snapshot won’t expire until synced.

• destination_prefix (str | None) – Prefix for snapshot name on destination.

Return type:

None

property queue: SiteSyncQueueManager

Access the sync queue for this outgoing sync.

Returns:

SiteSyncQueueManager scoped to this sync.

Example

>>> sync = client.site_syncs.get(1)
>>> items = sync.queue.list()
>>> syncing = sync.queue.list_syncing()

property remote_snapshots: SiteSyncRemoteSnapManager

Access remote snapshots for this outgoing sync.

Returns:

SiteSyncRemoteSnapManager scoped to this sync.

Example

>>> sync = client.site_syncs.get(1)
>>> snaps = sync.remote_snapshots.list()
>>> snap = snaps[0]
>>> snap.request_sync_back()

property stats: SiteSyncStatsManager

Access stats for this outgoing sync.

Returns:

SiteSyncStatsManager scoped to this sync.

Example

>>> sync = client.site_syncs.get(1)
>>> stats = sync.stats.get()
>>> print(f"Sent: {stats.sent_display}")

property logs: SiteSyncOutgoingLogManager

Access logs for this outgoing sync.

Returns:

SiteSyncOutgoingLogManager scoped to this sync.

Example

>>> sync = client.site_syncs.get(1)
>>> logs = sync.logs.list(limit=20)
>>> errors = sync.logs.list_errors()

class pyvergeos.resources.site_syncs.SiteSyncIncoming

Bases: ResourceObject

Incoming site sync resource object.

Incoming syncs receive cloud snapshots from a remote site for disaster recovery purposes.

Properties:

site_key: Key of the associated site. name: Sync name. description: Sync description. is_enabled: Whether the sync is enabled. status: Sync status (offline, syncing, error, etc.). status_info: Additional status information. state: Sync state (offline, online, warning, error). sync_id: Unique sync identifier. registration_code: Code used by remote site to establish connection. public_ip: Public IP/domain of connecting system. force_tier: Force all synced data to this tier. min_snapshots: Minimum snapshots to retain. last_sync_at: When last sync occurred. vsan_host: vSAN connection host. vsan_port: vSAN connection port. request_url: URL remote system uses to connect back. is_system_created: Whether sync was created by system.

property site_key: int | None

Get the associated site key.

property name: str

Get sync name.

property description: str

Get sync description.

property is_enabled: bool

Check if sync is enabled.

property status: str

Get sync status.

property status_info: str

Get additional status information.

property state: str

Get sync state (offline, online, warning, error).

property is_syncing: bool

Check if sync is currently syncing.

property is_online: bool

Check if sync is online.

property has_error: bool

Check if sync has an error.

property sync_id: str

Get unique sync identifier.

property registration_code: str

Get registration code for remote site connection.

property public_ip: str

Get public IP/domain of connecting system.

property force_tier: str

Get forced storage tier (unspecified, 1-5).

property min_snapshots: int

Get minimum snapshots to retain.

property last_sync_at: datetime | None

Get when last sync occurred.

property vsan_host: str

Get vSAN connection host.

property vsan_port: int

Get vSAN connection port.

property request_url: str

Get URL remote system uses to connect back.

property is_system_created: bool

Check if sync was created by system.

enable()

Enable this sync.

Returns:

Updated SiteSyncIncoming object.

Return type:

SiteSyncIncoming

disable()

Disable this sync.

Returns:

Updated SiteSyncIncoming object.

Return type:

SiteSyncIncoming

refresh()

Refresh sync data from server.

Returns:

Updated SiteSyncIncoming object.

Return type:

SiteSyncIncoming

property verified: SiteSyncIncomingVerifiedManager

Access verified sync info for this incoming sync.

Returns:

SiteSyncIncomingVerifiedManager scoped to this sync.

Example

>>> incoming = client.site_syncs_incoming.get(1)
>>> verified = incoming.verified.get()
>>> snaps = verified.list_remote_snapshots()

property logs: SiteSyncIncomingLogManager

Access logs for this incoming sync.

Returns:

SiteSyncIncomingLogManager scoped to this sync.

Example

>>> incoming = client.site_syncs_incoming.get(1)
>>> logs = incoming.logs.list(limit=20)
>>> errors = incoming.logs.list_errors()

class pyvergeos.resources.site_syncs.SiteSyncSchedule

Bases: ResourceObject

Site sync schedule resource object.

Schedules link snapshot profile periods to outgoing site syncs, enabling automatic syncing of snapshots taken by those periods.

Properties:

sync_key: Key of the associated outgoing sync. profile_period_key: Key of the snapshot profile period. retention: Retention period in seconds. retention_timedelta: Retention period as timedelta. priority: Sync priority (lower = first). do_not_expire: Whether source snapshot should not expire until synced. destination_prefix: Prefix for snapshot name on destination.

property sync_key: int | None

Get the associated outgoing sync key.

property profile_period_key: int | None

Get the associated snapshot profile period key.

property retention: int

Get retention period in seconds.

property retention_timedelta: timedelta

Get retention period as timedelta.

property priority: int

Get sync priority (lower = first).

property do_not_expire: bool

Check if source snapshot should not expire until synced.

property destination_prefix: str

Get prefix for snapshot name on destination.

delete()

Delete this schedule.

Return type:

None

class pyvergeos.resources.site_syncs.SiteSyncOutgoingManager

Bases: ResourceManager[SiteSyncOutgoing]

Manager for outgoing site sync operations.

Outgoing syncs send cloud snapshots to remote sites for disaster recovery.

Example

>>> # List all outgoing syncs
>>> syncs = client.site_syncs.list()

>>> # Get syncs for a specific site
>>> syncs = client.site_syncs.list(site_key=1)

>>> # Get a sync by name
>>> sync = client.site_syncs.get(name="DR-Sync")

>>> # Enable/disable a sync
>>> sync = client.site_syncs.enable(sync.key)
>>> sync = client.site_syncs.disable(sync.key)

>>> # Add snapshot to queue
>>> client.site_syncs.add_to_queue(
...     sync_key=1,
...     snapshot_key=5,
...     retention=604800,  # 7 days
... )

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, site_key=None, site_name=None, enabled=None, **filter_kwargs)

List outgoing site syncs.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• site_key (int | None) – Filter by site key.

• site_name (str | None) – Filter by site name (looks up site key).

• enabled (bool | None) – Filter by enabled status.

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of SiteSyncOutgoing objects sorted by name.

Return type:

list[SiteSyncOutgoing]

Example

>>> # All outgoing syncs
>>> syncs = client.site_syncs.list()

>>> # Syncs for a specific site
>>> syncs = client.site_syncs.list(site_key=1)

>>> # Enabled syncs only
>>> syncs = client.site_syncs.list(enabled=True)

list_enabled(fields=None)

List enabled outgoing syncs.

Parameters:

fields (list[str] | None) – List of fields to return.

Returns:

List of enabled SiteSyncOutgoing objects.

Return type:

list[SiteSyncOutgoing]

list_disabled(fields=None)

List disabled outgoing syncs.

Parameters:

fields (list[str] | None) – List of fields to return.

Returns:

List of disabled SiteSyncOutgoing objects.

Return type:

list[SiteSyncOutgoing]

list_for_site(site_key=None, site_name=None, fields=None)

List outgoing syncs for a specific site.

Parameters:

• site_key (int | None) – Site key.

• site_name (str | None) – Site name.

• fields (list[str] | None) – List of fields to return.

Returns:

List of SiteSyncOutgoing objects for the site.

Return type:

list[SiteSyncOutgoing]

get(key=None, *, name=None, site_key=None, site_name=None, fields=None)

Get an outgoing sync by key or name.

Parameters:

• key (int | None) – Sync $key (ID).

• name (str | None) – Sync name (requires site_key or site_name for uniqueness).

• site_key (int | None) – Site key (for name lookup).

• site_name (str | None) – Site name (for name lookup).

• fields (list[str] | None) – List of fields to return.

Returns:

SiteSyncOutgoing object.

Raises:

• NotFoundError – If sync not found.

• ValueError – If neither key nor name provided.

Return type:

SiteSyncOutgoing

enable(key)

Enable an outgoing sync.

Parameters:

key (int) – Sync $key (ID).

Returns:

Updated SiteSyncOutgoing object.

Return type:

SiteSyncOutgoing

disable(key)

Disable an outgoing sync.

Parameters:

key (int) – Sync $key (ID).

Returns:

Updated SiteSyncOutgoing object.

Return type:

SiteSyncOutgoing

start(key)

Start (enable) an outgoing sync.

Alias for enable().

Parameters:

key (int) – Sync $key (ID).

Returns:

Updated SiteSyncOutgoing object.

Return type:

SiteSyncOutgoing

stop(key)

Stop (disable) an outgoing sync.

Alias for disable().

Parameters:

key (int) – Sync $key (ID).

Returns:

Updated SiteSyncOutgoing object.

Return type:

SiteSyncOutgoing

add_to_queue(sync_key, snapshot_key, retention=259200, priority=0, do_not_expire=False, destination_prefix=None)

Add a cloud snapshot to the transfer queue.

Parameters:

• sync_key (int) – Key of the outgoing sync.

• snapshot_key (int) – Key of the cloud snapshot to queue.

• retention (int | timedelta) – Retention period in seconds or timedelta. Default 3 days.

• priority (int) – Priority for syncing (lower = first). Default 0.

• do_not_expire (bool) – If True, snapshot won’t expire until synced.

• destination_prefix (str | None) – Prefix for snapshot name on destination.

Raises:

ValidationError – If invalid parameters.

Return type:

None

invoke(sync_key, snapshot_key, retention=259200, priority=0, do_not_expire=False, destination_prefix=None)

Manually trigger a sync for a cloud snapshot.

Alias for add_to_queue().

Parameters:

• sync_key (int) – Key of the outgoing sync.

• snapshot_key (int) – Key of the cloud snapshot to queue.

• retention (int | timedelta) – Retention period in seconds or timedelta. Default 3 days.

• priority (int) – Priority for syncing (lower = first). Default 0.

• do_not_expire (bool) – If True, snapshot won’t expire until synced.

• destination_prefix (str | None) – Prefix for snapshot name on destination.

Return type:

None

set_throttle(key, throttle)

Set send throttle for an outgoing sync.

Parameters:

• key (int) – Sync $key (ID).

• throttle (int) – Throttle in bytes/sec (0 = disable).

Returns:

Updated SiteSyncOutgoing object.

Return type:

SiteSyncOutgoing

disable_throttle(key)

Disable send throttle for an outgoing sync.

Parameters:

key (int) – Sync $key (ID).

Returns:

Updated SiteSyncOutgoing object.

Return type:

SiteSyncOutgoing

refresh_remote_snapshots(key)

Refresh the list of snapshots on the destination.

Parameters:

key (int) – Sync $key (ID).

Returns:

Updated SiteSyncOutgoing object.

Return type:

SiteSyncOutgoing

class pyvergeos.resources.site_syncs.SiteSyncIncomingManager

Bases: ResourceManager[SiteSyncIncoming]

Manager for incoming site sync operations.

Incoming syncs receive cloud snapshots from remote sites for disaster recovery.

Example

>>> # List all incoming syncs
>>> syncs = client.site_syncs_incoming.list()

>>> # Get syncs for a specific site
>>> syncs = client.site_syncs_incoming.list(site_key=1)

>>> # Get a sync by name
>>> sync = client.site_syncs_incoming.get(name="DR-Sync")

>>> # Enable/disable a sync
>>> sync = client.site_syncs_incoming.enable(sync.key)
>>> sync = client.site_syncs_incoming.disable(sync.key)

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, site_key=None, site_name=None, enabled=None, **filter_kwargs)

List incoming site syncs.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• site_key (int | None) – Filter by site key.

• site_name (str | None) – Filter by site name (looks up site key).

• enabled (bool | None) – Filter by enabled status.

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of SiteSyncIncoming objects sorted by name.

Return type:

list[SiteSyncIncoming]

Example

>>> # All incoming syncs
>>> syncs = client.site_syncs_incoming.list()

>>> # Syncs for a specific site
>>> syncs = client.site_syncs_incoming.list(site_key=1)

>>> # Enabled syncs only
>>> syncs = client.site_syncs_incoming.list(enabled=True)

list_for_site(site_key=None, site_name=None, fields=None)

List incoming syncs for a specific site.

Parameters:

• site_key (int | None) – Site key.

• site_name (str | None) – Site name.

• fields (list[str] | None) – List of fields to return.

Returns:

List of SiteSyncIncoming objects for the site.

Return type:

list[SiteSyncIncoming]

get(key=None, *, name=None, site_key=None, site_name=None, fields=None)

Get an incoming sync by key or name.

Parameters:

• key (int | None) – Sync $key (ID).

• name (str | None) – Sync name (requires site_key or site_name for uniqueness).

• site_key (int | None) – Site key (for name lookup).

• site_name (str | None) – Site name (for name lookup).

• fields (list[str] | None) – List of fields to return.

Returns:

SiteSyncIncoming object.

Raises:

• NotFoundError – If sync not found.

• ValueError – If neither key nor name provided.

Return type:

SiteSyncIncoming

enable(key)

Enable an incoming sync.

Parameters:

key (int) – Sync $key (ID).

Returns:

Updated SiteSyncIncoming object.

Return type:

SiteSyncIncoming

disable(key)

Disable an incoming sync.

Parameters:

key (int) – Sync $key (ID).

Returns:

Updated SiteSyncIncoming object.

Return type:

SiteSyncIncoming

class pyvergeos.resources.site_syncs.SiteSyncScheduleManager

Bases: ResourceManager[SiteSyncSchedule]

Manager for site sync schedule operations.

Schedules link snapshot profile periods to outgoing syncs, enabling automatic syncing of snapshots taken by those periods.

Example

>>> # List all schedules
>>> schedules = client.site_sync_schedules.list()

>>> # Get schedules for a specific sync
>>> schedules = client.site_sync_schedules.list(sync_key=1)

>>> # Create a new schedule
>>> schedule = client.site_sync_schedules.create(
...     sync_key=1,
...     profile_period_key=2,
...     retention=604800,  # 7 days
... )

>>> # Delete a schedule
>>> client.site_sync_schedules.delete(schedule.key)

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, sync_key=None, sync_name=None, **filter_kwargs)

List site sync schedules.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• sync_key (int | None) – Filter by outgoing sync key.

• sync_name (str | None) – Filter by outgoing sync name.

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of SiteSyncSchedule objects sorted by priority.

Return type:

list[SiteSyncSchedule]

Example

>>> # All schedules
>>> schedules = client.site_sync_schedules.list()

>>> # Schedules for a specific sync
>>> schedules = client.site_sync_schedules.list(sync_key=1)

list_for_sync(sync_key=None, sync_name=None, fields=None)

List schedules for a specific outgoing sync.

Parameters:

• sync_key (int | None) – Outgoing sync key.

• sync_name (str | None) – Outgoing sync name.

• fields (list[str] | None) – List of fields to return.

Returns:

List of SiteSyncSchedule objects for the sync.

Return type:

list[SiteSyncSchedule]

get(key, *, fields=None)

Get a schedule by key.

Parameters:

• key (int) – Schedule $key (ID).

• fields (list[str] | None) – List of fields to return.

Returns:

SiteSyncSchedule object.

Raises:

NotFoundError – If schedule not found.

Return type:

SiteSyncSchedule

create(sync_key, profile_period_key, retention, *, priority=None, do_not_expire=False, destination_prefix='remote')

Create a new site sync schedule.

Links a snapshot profile period to an outgoing sync so that snapshots taken by that period are automatically queued for sync.

Parameters:

• sync_key (int) – Key of the outgoing sync.

• profile_period_key (int) – Key of the snapshot profile period.

• retention (int | timedelta) – Retention period in seconds or timedelta.

• priority (int | None) – Sync priority (lower = first). Auto-assigned if not specified.

• do_not_expire (bool) – If True, source snapshot won’t expire until synced.

• destination_prefix (str) – Prefix for snapshot name on destination.

Returns:

Created SiteSyncSchedule object.

Raises:

ValidationError – If invalid parameters.

Return type:

SiteSyncSchedule

Example

>>> schedule = client.site_sync_schedules.create(
...     sync_key=1,
...     profile_period_key=2,
...     retention=timedelta(days=7),
...     destination_prefix="remote",
... )

delete(key)

Delete a site sync schedule.

Parameters:

key (int) – Schedule $key (ID).

Raises:

NotFoundError – If schedule not found.

Return type:

None

class pyvergeos.resources.site_syncs.SiteSyncStats

Bases: ResourceObject

Site sync statistics resource object.

Provides performance metrics for a site sync operation.

Properties:

parent_key: Key of the parent sync. checked_bytes: Total bytes checked (file-level, pre-deduplication). scanned_bytes: Total bytes scanned (block comparison). sent_bytes: Bytes determined to need sending (pre-compression). sent_net_bytes: Actual bytes sent on wire (post-compression). dirs_checked: Number of directories checked. files_checked: Number of files checked. files_updated: Number of files updated. last_run_time_ms: Last run time in milliseconds. started_at: When sync started. stopped_at: When sync stopped. error_at: When error occurred. last_error: Last error message. send_throttle: Current throttle rate in bytes/sec. retry_count: Number of retry attempts. snapshot_name: Name of snapshot being synced. last_retry_at: When last retry occurred.

property parent_key: int | None

Get the parent sync/queue item key.

property checked_bytes: int

Get total bytes checked (file-level).

property scanned_bytes: int

Get total bytes scanned (block comparison).

property sent_bytes: int

Get bytes to send (pre-compression).

property sent_net_bytes: int

Get bytes actually sent (post-compression).

property checked_display: str

Get human-readable checked size.

property scanned_display: str

Get human-readable scanned size.

property sent_display: str

Get human-readable sent size.

property sent_net_display: str

Get human-readable net sent size.

property dirs_checked: int

Get number of directories checked.

property files_checked: int

Get number of files checked.

property files_updated: int

Get number of files updated.

property last_run_time_ms: int

Get last run time in milliseconds.

property last_run_time_seconds: float

Get last run time in seconds.

property started_at: datetime | None

Get when sync started.

property stopped_at: datetime | None

Get when sync stopped.

property error_at: datetime | None

Get when error occurred.

property last_error: str

Get last error message.

property has_error: bool

Check if there was an error.

property send_throttle: int

Get current throttle rate in bytes/sec.

property retry_count: int

Get number of retry attempts.

property snapshot_name: str

Get name of snapshot being synced.

property last_retry_at: datetime | None

Get when last retry occurred.

property compression_ratio: float

Calculate compression ratio (sent / sent_net).

Returns ratio > 1 means compression is effective. Returns 0 if no data sent.

property dedup_ratio: float

Calculate deduplication ratio (checked / sent).

Returns ratio > 1 means deduplication is effective. Returns 0 if no data sent.

class pyvergeos.resources.site_syncs.SiteSyncStatsHistory

Bases: ResourceObject

Site sync stats history entry.

Long-term historical metrics for sync operations.

property parent_key: int | None

Get the parent sync key.

property checked_bytes: int

Get total bytes checked.

property scanned_bytes: int

Get total bytes scanned.

property sent_bytes: int

Get bytes to send.

property sent_net_bytes: int

Get bytes actually sent.

property dirs_checked: int

Get directories checked.

property files_checked: int

Get files checked.

property files_updated: int

Get files updated.

property last_run_time_ms: int

Get run time in milliseconds.

property snapshot_name: str

Get snapshot name.

property timestamp: datetime | None

Get when record was created.

class pyvergeos.resources.site_syncs.SiteSyncStatsManager

Bases: object

Manager for site sync stats (scoped to a sync).

Example

>>> sync = client.site_syncs.get(1)
>>> stats = sync.stats.get()
>>> print(f"Checked: {stats.checked_display}")

>>> # Get historical stats
>>> history = sync.stats.history()
>>> for entry in history:
...     print(f"{entry.snapshot_name}: {entry.sent_bytes} bytes")

__init__(client, sync_key)

Parameters:

• client (VergeClient)

• sync_key (int)

Return type:

None

get(fields=None)

Get current stats for this sync.

Parameters:

fields (list[str] | None) – List of fields to return.

Returns:

SiteSyncStats object or None if no stats available.

Return type:

SiteSyncStats | None

list(limit=20, offset=None, fields=None)

List recent stats entries.

Parameters:

• limit (int | None) – Maximum entries to return.

• offset (int | None) – Skip this many entries.

• fields (list[str] | None) – List of fields to return.

Returns:

List of SiteSyncStats objects, newest first.

Return type:

list[SiteSyncStats]

history(limit=100, offset=None, fields=None)

Get historical stats (long-term).

Parameters:

• limit (int | None) – Maximum entries to return.

• offset (int | None) – Skip this many entries.

• fields (list[str] | None) – List of fields to return.

Returns:

List of SiteSyncStatsHistory objects, newest first.

Return type:

list[SiteSyncStatsHistory]

class pyvergeos.resources.site_syncs.SiteSyncQueueItem

Bases: ResourceObject

Site sync queue item resource object.

Represents a cloud snapshot queued for sync to a remote site.

Properties:

sync_key: Key of the parent outgoing sync. cloud_snapshot_key: Key of the cloud snapshot. priority: Sync priority (lower = first). status: Queue status (queue, paused, syncing, complete, error, retry). retention: Retention period in seconds. remote_expiration_at: When snapshot will expire on remote. destination_prefix: Prefix for snapshot name on remote. created_at: When item was queued. do_not_expire: Whether snapshot should not expire until synced.

property sync_key: int | None

Get the parent outgoing sync key.

property queue_id: str

Get the queue item ID.

property cloud_snapshot_key: int | None

Get the cloud snapshot key.

property priority: int

Get sync priority (lower = first).

property status: str

Get queue status.

Values: queue, paused, syncing, complete, error, retry, initializing, skip_retention.

property is_queued: bool

Check if item is queued (waiting to sync).

property is_syncing: bool

Check if item is currently syncing.

property is_complete: bool

Check if sync completed successfully.

property has_error: bool

Check if item has an error.

property is_paused: bool

Check if item is paused.

property retention: int

Get retention period in seconds.

property retention_timedelta: timedelta

Get retention period as timedelta.

property remote_expiration_at: datetime | None

Get when snapshot expires on remote.

property destination_prefix: str

Get prefix for snapshot name on remote.

property created_at: datetime | None

Get when item was queued.

property do_not_expire: bool

Check if snapshot should not expire until synced.

get_stats()

Get stats for this queue item.

Returns:

SiteSyncStats object or None if no stats available.

Return type:

SiteSyncStats | None

delete()

Remove this item from the queue.

Return type:

None

class pyvergeos.resources.site_syncs.SiteSyncQueueManager

Bases: object

Manager for site sync queue (scoped to an outgoing sync).

Example

>>> sync = client.site_syncs.get(1)
>>> # List queued items
>>> items = sync.queue.list()
>>> for item in items:
...     print(f"{item.key}: {item.status} (priority {item.priority})")

>>> # Get items currently syncing
>>> syncing = sync.queue.list_syncing()

>>> # Get items with errors
>>> errors = sync.queue.list_errors()

__init__(client, sync_key)

Parameters:

• client (VergeClient)

• sync_key (int)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, status=None, **filter_kwargs)

List queue items for this sync.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum results to return.

• offset (int | None) – Skip this many results.

• status (str | None) – Filter by status (queue, syncing, complete, error, etc.).

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of SiteSyncQueueItem objects sorted by priority.

Return type:

list[SiteSyncQueueItem]

list_queued(fields=None)

List items waiting to sync.

Parameters:

fields (list[str] | None) – List of fields to return.

Returns:

List of queued SiteSyncQueueItem objects.

Return type:

list[SiteSyncQueueItem]

list_syncing(fields=None)

List items currently syncing.

Parameters:

fields (list[str] | None) – List of fields to return.

Returns:

List of syncing SiteSyncQueueItem objects.

Return type:

list[SiteSyncQueueItem]

list_complete(limit=20, fields=None)

List completed items.

Parameters:

• limit (int | None) – Maximum results (default 20).

• fields (list[str] | None) – List of fields to return.

Returns:

List of completed SiteSyncQueueItem objects.

Return type:

list[SiteSyncQueueItem]

list_errors(fields=None)

List items with errors.

Parameters:

fields (list[str] | None) – List of fields to return.

Returns:

List of error/retry SiteSyncQueueItem objects.

Return type:

list[SiteSyncQueueItem]

get(key, fields=None)

Get a queue item by key.

Parameters:

• key (int) – Queue item $key (ID).

• fields (list[str] | None) – List of fields to return.

Returns:

SiteSyncQueueItem object.

Raises:

NotFoundError – If item not found.

Return type:

SiteSyncQueueItem

delete(key)

Remove an item from the queue.

Parameters:

key (int) – Queue item $key (ID).

Return type:

None

count()

Get total count of items in queue.

Returns:

Number of queue items.

Return type:

int

count_pending()

Get count of items waiting to sync.

Returns:

Number of queued items.

Return type:

int

class pyvergeos.resources.site_syncs.SiteSyncRemoteSnap

Bases: ResourceObject

Remote snapshot on destination site.

Represents a cloud snapshot that has been synced to the remote site.

Properties:

sync_key: Key of the parent outgoing sync. name: Snapshot name on remote. status: Status (offline, requesting, downloading, error). status_info: Additional status information. remote_key: Key of snapshot on remote system. created_at: When snapshot was created. description: Snapshot description. expires_at: When snapshot expires on remote.

property sync_key: int | None

Get the parent outgoing sync key.

property name: str

Get snapshot name.

property status: str

Get status (offline, request, downloading, error, unsupported).

property status_info: str

Get additional status information.

property is_downloading: bool

Check if snapshot is being downloaded (sync back).

property has_error: bool

Check if there’s an error.

property remote_key: int | None

Get the snapshot key on remote system.

property created_at: datetime | None

Get when snapshot was created.

property description: str

Get snapshot description.

property expires_at: datetime | None

Get when snapshot expires on remote.

request_sync_back()

Request this snapshot be synced back to local system.

This initiates a “sync back” operation to restore this snapshot from the remote site to the local system.

Return type:

None

set_retention(expires)

Set the retention/expiration for this remote snapshot.

Parameters:

expires (datetime | int) – New expiration as datetime or Unix timestamp.

Return type:

None

class pyvergeos.resources.site_syncs.SiteSyncRemoteSnapManager

Bases: object

Manager for remote snapshots (scoped to an outgoing sync).

Example

>>> sync = client.site_syncs.get(1)
>>> # Refresh list of remote snapshots
>>> sync.refresh_remote_snapshots()

>>> # List remote snapshots
>>> snaps = sync.remote_snapshots.list()
>>> for snap in snaps:
...     print(f"{snap.name}: expires {snap.expires_at}")

>>> # Request a snapshot to be synced back
>>> snap = snaps[0]
>>> snap.request_sync_back()

__init__(client, sync_key)

Parameters:

• client (VergeClient)

• sync_key (int)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List remote snapshots.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum results to return.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of SiteSyncRemoteSnap objects sorted by expiration.

Return type:

list[SiteSyncRemoteSnap]

get(key=None, *, name=None, fields=None)

Get a remote snapshot by key or name.

Parameters:

• key (int | None) – Snapshot $key (ID).

• name (str | None) – Snapshot name.

• fields (list[str] | None) – List of fields to return.

Returns:

SiteSyncRemoteSnap object.

Raises:

• NotFoundError – If not found.

• ValueError – If neither key nor name provided.

Return type:

SiteSyncRemoteSnap

request_sync_back(key)

Request a remote snapshot to be synced back.

Parameters:

key (int) – Remote snapshot $key (ID).

Return type:

None

set_retention(key, expires)

Set retention for a remote snapshot.

Parameters:

• key (int) – Remote snapshot $key (ID).

• expires (datetime | int) – New expiration as datetime or Unix timestamp.

Return type:

None

count()

Get count of remote snapshots.

Returns:

Number of remote snapshots.

Return type:

int

class pyvergeos.resources.site_syncs.SiteSyncIncomingVerified

Bases: ResourceObject

Verified incoming sync resource object.

Represents a verified/registered incoming sync connection.

Properties:

incoming_sync_key: Key of the parent incoming sync. name: Name (from parent sync). is_registered: Whether sync is registered. registered_at: When sync was registered.

property incoming_sync_key: int | None

Get the parent incoming sync key.

property name: str

Get name (from parent sync).

property is_registered: bool

Check if sync is registered.

property registered_at: datetime | None

Get when sync was registered.

list_remote_snapshots()

Request list of snapshots available on the remote sender.

Returns:

List of snapshot information dicts.

Return type:

list[dict[str, Any]]

request_snapshot(snapshot_name, retention=259200)

Request a snapshot to be synced from the remote sender.

Parameters:

• snapshot_name (str) – Name of snapshot on remote system.

• retention (int | timedelta) – Retention period in seconds or timedelta.

Return type:

None

set_retention(snapshot_name, retention)

Set retention for a synced snapshot.

Parameters:

• snapshot_name (str) – Name of the snapshot.

• retention (int | timedelta) – New retention period in seconds or timedelta.

Return type:

None

class pyvergeos.resources.site_syncs.SiteSyncIncomingVerifiedManager

Bases: object

Manager for verified incoming syncs (scoped to an incoming sync).

Example

>>> incoming = client.site_syncs_incoming.get(1)
>>> verified = incoming.verified.get()
>>> print(f"Registered: {verified.is_registered}")

>>> # List snapshots available on sender
>>> snaps = verified.list_remote_snapshots()

>>> # Request a snapshot to sync back
>>> verified.request_snapshot("cloud-snap-2024-01-01", retention=604800)

__init__(client, incoming_sync_key)

Parameters:

• client (VergeClient)

• incoming_sync_key (int)

Return type:

None

get(fields=None)

Get the verified sync entry for this incoming sync.

Parameters:

fields (list[str] | None) – List of fields to return.

Returns:

SiteSyncIncomingVerified object or None.

Return type:

SiteSyncIncomingVerified | None

list_remote_snapshots(verified_key)

Request list of snapshots available on the remote sender.

Parameters:

verified_key (int) – Verified sync $key (ID).

Returns:

List of snapshot information dicts.

Return type:

list[dict[str, Any]]

request_snapshot(verified_key, snapshot_name, retention=259200)

Request a snapshot to be synced from the remote sender.

Parameters:

• verified_key (int) – Verified sync $key (ID).

• snapshot_name (str) – Name of snapshot on remote system.

• retention (int | timedelta) – Retention period in seconds or timedelta.

Return type:

None

set_retention(verified_key, snapshot_name, retention)

Set retention for a synced snapshot.

Parameters:

• verified_key (int) – Verified sync $key (ID).

• snapshot_name (str) – Name of the snapshot.

• retention (int | timedelta) – New retention period in seconds or timedelta.

Return type:

None

class pyvergeos.resources.site_syncs.SiteSyncLog

Bases: ResourceObject

Site sync log entry.

Properties:

level: Log level (audit, message, warning, error, critical). level_display: Human-readable level name. text: Log message text. timestamp_us: Timestamp in microseconds. logged_at: Datetime when logged. user: User who triggered the log (if applicable).

property level: str

Get log level.

property level_display: str

Get human-readable level name.

property is_error: bool

Check if this is an error or critical log.

property is_warning: bool

Check if this is a warning log.

property text: str

Get log message text.

property timestamp_us: int

Get timestamp in microseconds.

property logged_at: datetime | None

Get datetime when logged.

property user: str

Get user who triggered the log.

class pyvergeos.resources.site_syncs.SiteSyncOutgoingLogManager

Bases: object

Manager for outgoing sync logs (scoped to an outgoing sync).

Example

>>> sync = client.site_syncs.get(1)
>>> logs = sync.logs.list(limit=20)
>>> for log in logs:
...     print(f"[{log.level}] {log.text}")

>>> # Get only errors
>>> errors = sync.logs.list_errors()

__init__(client, sync_key)

Parameters:

• client (VergeClient)

• sync_key (int)

Return type:

None

list(filter=None, fields=None, limit=100, offset=None, *, level=None, **filter_kwargs)

List logs for this sync.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum entries (default 100).

• offset (int | None) – Skip this many entries.

• level (str | None) – Filter by level (audit, message, warning, error, critical).

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of SiteSyncLog objects, newest first.

Return type:

list[SiteSyncLog]

list_errors(limit=100, fields=None)

List error and critical logs.

Parameters:

• limit (int | None) – Maximum entries.

• fields (list[str] | None) – List of fields to return.

Returns:

List of error/critical SiteSyncLog objects.

Return type:

list[SiteSyncLog]

list_warnings(limit=100, fields=None)

List warning logs.

Parameters:

• limit (int | None) – Maximum entries.

• fields (list[str] | None) – List of fields to return.

Returns:

List of warning SiteSyncLog objects.

Return type:

list[SiteSyncLog]

class pyvergeos.resources.site_syncs.SiteSyncIncomingLogManager

Bases: object

Manager for incoming sync logs (scoped to an incoming sync).

Example

>>> incoming = client.site_syncs_incoming.get(1)
>>> logs = incoming.logs.list(limit=20)
>>> for log in logs:
...     print(f"[{log.level}] {log.text}")

>>> # Get only errors
>>> errors = incoming.logs.list_errors()

__init__(client, sync_key)

Parameters:

• client (VergeClient)

• sync_key (int)

Return type:

None

list(filter=None, fields=None, limit=100, offset=None, *, level=None, **filter_kwargs)

List logs for this sync.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum entries (default 100).

• offset (int | None) – Skip this many entries.

• level (str | None) – Filter by level (audit, message, warning, error, critical).

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of SiteSyncLog objects, newest first.

Return type:

list[SiteSyncLog]

list_errors(limit=100, fields=None)

List error and critical logs.

Parameters:

• limit (int | None) – Maximum entries.

• fields (list[str] | None) – List of fields to return.

Returns:

List of error/critical SiteSyncLog objects.

Return type:

list[SiteSyncLog]

list_warnings(limit=100, fields=None)

List warning logs.

Parameters:

• limit (int | None) – Maximum entries.

• fields (list[str] | None) – List of fields to return.

Returns:

List of warning SiteSyncLog objects.

Return type:

list[SiteSyncLog]

Organization

Tags

Tag resource managers for VergeOS tags, categories, and members.

class pyvergeos.resources.tags.TagMember

Bases: ResourceObject

Tag member resource object.

Represents a membership record linking a resource to a tag.

key

Membership primary key ($key).

tag_key

Parent tag key.

resource_type

Type of tagged resource (vms, vnets, etc.).

resource_key

Key of the tagged resource.

resource_ref

API reference to the resource.

property tag_key: int

Get the parent tag key.

property resource_ref: str

Get the resource API reference (e.g., ‘vms/123’).

property resource_type: str | None

Get the resource type (vms, vnets, tenants, etc.).

property resource_type_display: str

Get the display name for the resource type.

property resource_key: int | None

Get the resource key (ID).

remove()

Remove this tag assignment.

Raises:

ValueError – If membership key is not available.

Return type:

None

class pyvergeos.resources.tags.TagMemberManager

Bases: ResourceManager[TagMember]

Manager for tag membership operations.

This manager handles adding and removing resources from a tag. It can be accessed via tag.members or directly via client.tags.members().

Example

>>> # List members of a tag
>>> for member in client.tags.members(tag_key).list():
...     print(f"{member.resource_type}: {member.resource_key}")

>>> # Add a VM to a tag
>>> client.tags.members(tag_key).add_vm(vm_key)

>>> # Remove a member
>>> client.tags.members(tag_key).remove(membership_key)

__init__(client, tag_key)

Parameters:

• client (VergeClient)

• tag_key (int)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, resource_type=None, **filter_kwargs)

List members of this tag.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• resource_type (str | None) – Filter by resource type (vms, vnets, tenants, etc.).

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of TagMember objects.

Return type:

list[TagMember]

Example

>>> members = client.tags.members(tag_key).list()
>>> for m in members:
...     print(f"{m.resource_type}: {m.resource_key}")

>>> # List only VMs
>>> vm_members = client.tags.members(tag_key).list(resource_type="vms")

add(resource_type, resource_key)

Add a resource to this tag.

Parameters:

• resource_type (str) – Type of resource (vms, vnets, tenants, etc.).

• resource_key (int) – Resource $key (ID) to add.

Returns:

Created TagMember object.

Raises:

ConflictError – If resource is already tagged.

Return type:

TagMember

Example

>>> member = client.tags.members(tag_key).add("vms", vm.key)

add_vm(vm_key)

Add a VM to this tag.

Parameters:

vm_key (int) – VM $key (ID) to add.

Returns:

Created TagMember object.

Return type:

TagMember

Example

>>> member = client.tags.members(tag_key).add_vm(vm.key)

add_network(network_key)

Add a network to this tag.

Parameters:

network_key (int) – Network $key (ID) to add.

Returns:

Created TagMember object.

Return type:

TagMember

Example

>>> member = client.tags.members(tag_key).add_network(network.key)

add_tenant(tenant_key)

Add a tenant to this tag.

Parameters:

tenant_key (int) – Tenant $key (ID) to add.

Returns:

Created TagMember object.

Return type:

TagMember

Example

>>> member = client.tags.members(tag_key).add_tenant(tenant.key)

add_user(user_key)

Add a user to this tag.

Parameters:

user_key (int) – User $key (ID) to add.

Returns:

Created TagMember object.

Return type:

TagMember

Example

>>> member = client.tags.members(tag_key).add_user(user.key)

add_node(node_key)

Add a node to this tag.

Parameters:

node_key (int) – Node $key (ID) to add.

Returns:

Created TagMember object.

Return type:

TagMember

Example

>>> member = client.tags.members(tag_key).add_node(node.key)

add_cluster(cluster_key)

Add a cluster to this tag.

Parameters:

cluster_key (int) – Cluster $key (ID) to add.

Returns:

Created TagMember object.

Return type:

TagMember

Example

>>> member = client.tags.members(tag_key).add_cluster(cluster.key)

add_site(site_key)

Add a site to this tag.

Parameters:

site_key (int) – Site $key (ID) to add.

Returns:

Created TagMember object.

Return type:

TagMember

Example

>>> member = client.tags.members(tag_key).add_site(site.key)

add_group(group_key)

Add a group to this tag.

Parameters:

group_key (int) – Group $key (ID) to add.

Returns:

Created TagMember object.

Return type:

TagMember

Example

>>> member = client.tags.members(tag_key).add_group(group.key)

remove(membership_key)

Remove a membership by its key.

Parameters:

membership_key (int) – Membership $key (ID) to remove.

Return type:

None

Example

>>> client.tags.members(tag_key).remove(membership.key)

remove_resource(resource_type, resource_key)

Remove a resource from this tag.

Parameters:

• resource_type (str) – Type of resource (vms, vnets, tenants, etc.).

• resource_key (int) – Resource $key (ID) to remove.

Raises:

NotFoundError – If resource is not tagged with this tag.

Return type:

None

Example

>>> client.tags.members(tag_key).remove_resource("vms", vm.key)

remove_vm(vm_key)

Remove a VM from this tag.

Parameters:

vm_key (int) – VM $key (ID) to remove.

Raises:

NotFoundError – If VM is not tagged.

Return type:

None

Example

>>> client.tags.members(tag_key).remove_vm(vm.key)

remove_network(network_key)

Remove a network from this tag.

Parameters:

network_key (int) – Network $key (ID) to remove.

Raises:

NotFoundError – If network is not tagged.

Return type:

None

Example

>>> client.tags.members(tag_key).remove_network(network.key)

remove_tenant(tenant_key)

Remove a tenant from this tag.

Parameters:

tenant_key (int) – Tenant $key (ID) to remove.

Raises:

NotFoundError – If tenant is not tagged.

Return type:

None

Example

>>> client.tags.members(tag_key).remove_tenant(tenant.key)

class pyvergeos.resources.tags.Tag

Bases: ResourceObject

Tag resource object.

Represents a tag within a category in VergeOS.

key

Tag primary key ($key).

name

Tag name.

description

Tag description.

category_key

Parent category key.

category_name

Parent category name (if fetched with category info).

created

Creation timestamp (Unix epoch).

modified

Last modified timestamp (Unix epoch).

property description: str | None

Get the tag description.

property category_key: int

Get the parent category key.

property category_name: str | None

Get the parent category name (if fetched).

property created: int | None

Get the creation timestamp (Unix epoch).

property modified: int | None

Get the last modified timestamp (Unix epoch).

property members: TagMemberManager

Access tag member operations for this tag.

Returns:

TagMemberManager for this tag.

Example

>>> # List members
>>> for member in tag.members.list():
...     print(member.resource_ref)

>>> # Add a VM
>>> tag.members.add_vm(vm.key)

refresh()

Refresh tag data from the server.

Returns:

Updated Tag object.

Return type:

Tag

save(**kwargs)

Save changes to this tag.

Parameters:

**kwargs (Any) – Fields to update (name, description).

Returns:

Updated Tag object.

Return type:

Tag

delete()

Delete this tag.

Return type:

None

class pyvergeos.resources.tags.TagManager

Bases: ResourceManager[Tag]

Manager for VergeOS tag operations.

Provides CRUD operations and management for tags.

Example

>>> # List all tags
>>> for tag in client.tags.list():
...     print(f"{tag.name} (Category: {tag.category_name})")

>>> # List tags in a specific category
>>> env_tags = client.tags.list(category_key=1)

>>> # Create a tag
>>> tag = client.tags.create(
...     name="Production",
...     category_key=1,
...     description="Production resources"
... )

>>> # Manage tag members
>>> client.tags.members(tag.key).add_vm(vm.key)

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, category_key=None, category_name=None, **filter_kwargs)

List tags with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• category_key (int | None) – Filter by category key.

• category_name (str | None) – Filter by category name (performs lookup).

• **filter_kwargs (Any) – Shorthand filter arguments (name, etc.).

Returns:

List of Tag objects.

Return type:

list[Tag]

Example

>>> # List all tags
>>> tags = client.tags.list()

>>> # List tags in a category
>>> env_tags = client.tags.list(category_key=1)

>>> # List by name
>>> tags = client.tags.list(name="Production")

get(key=None, *, name=None, category_key=None, category_name=None, fields=None)

Get a single tag by key or name.

Parameters:

• key (int | None) – Tag $key (ID).

• name (str | None) – Tag name (requires category_key or category_name for uniqueness).

• category_key (int | None) – Category key (used with name lookup).

• category_name (str | None) – Category name (used with name lookup).

• fields (list[str] | None) – List of fields to return.

Returns:

Tag object.

Raises:

• NotFoundError – If tag not found.

• ValueError – If neither key nor name provided.

Return type:

Tag

Example

>>> # Get by key
>>> tag = client.tags.get(123)

>>> # Get by name in category
>>> tag = client.tags.get(name="Production", category_name="Environment")

create(name, category_key, *, description=None)

Create a new tag.

Parameters:

• name (str) – Tag name (must be unique within category).

• category_key (int) – Parent category $key (ID).

• description (str | None) – Tag description (optional).

Returns:

Created Tag object.

Return type:

Tag

Example

>>> # Create a tag
>>> tag = client.tags.create(
...     name="Production",
...     category_key=1,
...     description="Production resources"
... )

update(key, *, name=None, description=None)

Update a tag.

Parameters:

• key (int) – Tag $key (ID).

• name (str | None) – New tag name.

• description (str | None) – New description.

Returns:

Updated Tag object.

Return type:

Tag

Example

>>> # Update description
>>> client.tags.update(tag.key, description="New description")

>>> # Rename tag
>>> client.tags.update(tag.key, name="NewName")

delete(key)

Delete a tag.

Parameters:

key (int) – Tag $key (ID).

Return type:

None

Note

Deleting a tag also removes all tag member assignments.

Example

>>> client.tags.delete(tag.key)

members(tag_key)

Get a member manager for a specific tag.

Parameters:

tag_key (int) – Tag $key (ID).

Returns:

TagMemberManager for the specified tag.

Return type:

TagMemberManager

Example

>>> # List members
>>> members = client.tags.members(tag.key).list()

>>> # Add VM to tag
>>> client.tags.members(tag.key).add_vm(vm.key)

class pyvergeos.resources.tags.TagCategory

Bases: ResourceObject

Tag category resource object.

Represents a tag category in VergeOS that organizes tags and defines which resource types can be tagged.

key

Category primary key ($key).

name

Category name.

description

Category description.

is_single_tag_selection

Whether only one tag from this category can be applied to a resource.

taggable_*

Boolean flags for each resource type that can be tagged.

created

Creation timestamp (Unix epoch).

modified

Last modified timestamp (Unix epoch).

property description: str | None

Get the category description.

property is_single_tag_selection: bool

Check if only one tag from this category can be applied.

property taggable_vms: bool

Check if VMs can be tagged with this category.

property taggable_networks: bool

Check if networks can be tagged with this category.

property taggable_volumes: bool

Check if volumes can be tagged with this category.

property taggable_network_rules: bool

Check if network rules can be tagged with this category.

property taggable_vmware_containers: bool

Check if VMware containers can be tagged with this category.

property taggable_users: bool

Check if users can be tagged with this category.

property taggable_tenant_nodes: bool

Check if tenant nodes can be tagged with this category.

property taggable_sites: bool

Check if sites can be tagged with this category.

property taggable_nodes: bool

Check if nodes can be tagged with this category.

property taggable_groups: bool

Check if groups can be tagged with this category.

property taggable_clusters: bool

Check if clusters can be tagged with this category.

property taggable_tenants: bool

Check if tenants can be tagged with this category.

property created: int | None

Get the creation timestamp (Unix epoch).

property modified: int | None

Get the last modified timestamp (Unix epoch).

get_taggable_types()

Get a list of resource types that can be tagged with this category.

Returns:

List of resource type names (vms, vnets, etc.).

Return type:

list[str]

Example

>>> category.get_taggable_types()
['vms', 'vnets', 'tenants']

property tags: list[Tag]

Get all tags in this category.

Returns:

List of Tag objects in this category.

Example

>>> for tag in category.tags:
...     print(tag.name)

refresh()

Refresh category data from the server.

Returns:

Updated TagCategory object.

Return type:

TagCategory

save(**kwargs)

Save changes to this category.

Parameters:

**kwargs (Any) – Fields to update.

Returns:

Updated TagCategory object.

Return type:

TagCategory

delete()

Delete this category.

Note

Category must not contain any tags. Delete tags first.

Return type:

None

class pyvergeos.resources.tags.TagCategoryManager

Bases: ResourceManager[TagCategory]

Manager for VergeOS tag category operations.

Provides CRUD operations and management for tag categories.

Example

>>> # List all categories
>>> for category in client.tag_categories.list():
...     print(f"{category.name}: {category.get_taggable_types()}")

>>> # Create a category
>>> category = client.tag_categories.create(
...     name="Environment",
...     description="Deployment environment",
...     taggable_vms=True,
...     taggable_networks=True,
...     single_tag_selection=True
... )

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List tag categories with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return (uses defaults if not specified).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Shorthand filter arguments (name, etc.).

Returns:

List of TagCategory objects.

Return type:

list[TagCategory]

Example

>>> # List all categories
>>> categories = client.tag_categories.list()

>>> # List by name
>>> categories = client.tag_categories.list(name="Environment")

get(key=None, *, name=None, fields=None)

Get a single tag category by key or name.

Parameters:

• key (int | None) – Category $key (ID).

• name (str | None) – Category name.

• fields (list[str] | None) – List of fields to return.

Returns:

TagCategory object.

Raises:

• NotFoundError – If category not found.

• ValueError – If neither key nor name provided.

Return type:

TagCategory

Example

>>> # Get by key
>>> category = client.tag_categories.get(123)

>>> # Get by name
>>> category = client.tag_categories.get(name="Environment")

create(name, *, description=None, single_tag_selection=False, taggable_vms=False, taggable_networks=False, taggable_volumes=False, taggable_network_rules=False, taggable_vmware_containers=False, taggable_users=False, taggable_tenant_nodes=False, taggable_sites=False, taggable_nodes=False, taggable_groups=False, taggable_clusters=False, taggable_tenants=False)

Create a new tag category.

Parameters:

• name (str) – Category name (must be unique).

• description (str | None) – Category description (optional).

• single_tag_selection (bool) – If True, only one tag from this category can be applied to a resource.

• taggable_vms (bool) – Allow tagging VMs.

• taggable_networks (bool) – Allow tagging networks.

• taggable_volumes (bool) – Allow tagging volumes.

• taggable_network_rules (bool) – Allow tagging network rules.

• taggable_vmware_containers (bool) – Allow tagging VMware containers.

• taggable_users (bool) – Allow tagging users.

• taggable_tenant_nodes (bool) – Allow tagging tenant nodes.

• taggable_sites (bool) – Allow tagging sites.

• taggable_nodes (bool) – Allow tagging nodes.

• taggable_groups (bool) – Allow tagging groups.

• taggable_clusters (bool) – Allow tagging clusters.

• taggable_tenants (bool) – Allow tagging tenants.

Returns:

Created TagCategory object.

Return type:

TagCategory

Example

>>> # Create an environment category
>>> category = client.tag_categories.create(
...     name="Environment",
...     description="Deployment environment",
...     taggable_vms=True,
...     taggable_networks=True,
...     taggable_tenants=True,
...     single_tag_selection=True
... )

update(key, *, name=None, description=None, single_tag_selection=None, taggable_vms=None, taggable_networks=None, taggable_volumes=None, taggable_network_rules=None, taggable_vmware_containers=None, taggable_users=None, taggable_tenant_nodes=None, taggable_sites=None, taggable_nodes=None, taggable_groups=None, taggable_clusters=None, taggable_tenants=None)

Update a tag category.

Parameters:

• key (int) – Category $key (ID).

• name (str | None) – New category name.

• description (str | None) – New description.

• single_tag_selection (bool | None) – Update single tag selection mode.

• taggable_* – Update taggable resource types.

• taggable_vms (bool | None)

• taggable_networks (bool | None)

• taggable_volumes (bool | None)

• taggable_network_rules (bool | None)

• taggable_vmware_containers (bool | None)

• taggable_users (bool | None)

• taggable_tenant_nodes (bool | None)

• taggable_sites (bool | None)

• taggable_nodes (bool | None)

• taggable_groups (bool | None)

• taggable_clusters (bool | None)

• taggable_tenants (bool | None)

Returns:

Updated TagCategory object.

Return type:

TagCategory

Example

>>> # Update description
>>> client.tag_categories.update(
...     category.key,
...     description="New description"
... )

>>> # Enable additional resource types
>>> client.tag_categories.update(
...     category.key,
...     taggable_nodes=True,
...     taggable_clusters=True
... )

delete(key)

Delete a tag category.

Parameters:

key (int) – Category $key (ID).

Return type:

None

Note

The category must not contain any tags. Delete all tags first.

Example

>>> client.tag_categories.delete(category.key)

Resource Groups

Resource group management for VergeOS hardware device pools.

class pyvergeos.resources.resource_groups.ResourceGroup

Bases: ResourceObject

Represents a resource group in VergeOS.

Resource groups define collections of hardware devices (GPU, PCI, USB, SR-IOV NIC, vGPU) that can be assigned to virtual machines for device passthrough.

Resource groups are read-only - they are typically configured through the VergeOS UI to associate physical devices with virtual machines.

Note

Resource groups use UUID as their primary key, not integer IDs. The key property returns the UUID string.

property key: str

Resource group key (UUID).

Resource groups use UUID as their primary identifier.

property uuid: str

Resource group UUID (same as key).

property name: str

Resource group name.

property description: str

Resource group description.

property device_type: str

Device type (raw API value).

One of: node_pci_devices, node_sriov_nic_devices, node_usb_devices, node_host_gpu_devices, node_nvidia_vgpu_devices

property device_type_display: str

Human-readable device type.

One of: PCI, SR-IOV NIC, USB, Host GPU, NVIDIA vGPU

property device_class: str

Device class (raw API value).

One of: gpu, vgpu, storage, hid, usb, network, media, audio, fpga, pci, unknown

property device_class_display: str

Human-readable device class.

One of: GPU, vGPU, Storage, Human Input Device, Generic USB Device, Network, Media, Audio, FPGA, Generic PCI, Unknown

property is_enabled: bool

Whether the resource group is enabled.

property resource_count: int

Number of resources (devices) in this group.

property created_at: datetime | None

Creation timestamp.

property modified_at: datetime | None

Last modification timestamp.

property rules: ResourceRuleManager

Access resource rules for this resource group.

Returns:

ResourceRuleManager scoped to this resource group.

Example

>>> # List rules for this group
>>> for rule in group.rules.list():
...     print(f"{rule.name}: {rule.filter_expression}")

>>> # Create a rule
>>> rule = group.rules.create(
...     name="Intel NICs",
...     filter_expression="vendor ct 'Intel'",
... )

refresh()

Refresh this resource group’s data from the server.

Return type:

ResourceGroup

save(**kwargs)

Update this resource group with the given values.

Parameters:

kwargs (Any)

Return type:

ResourceGroup

delete()

Delete this resource group.

Return type:

None

class pyvergeos.resources.resource_groups.ResourceGroupManager

Bases: ResourceManager[ResourceGroup]

Manages resource groups in VergeOS.

Resource groups define collections of hardware devices (GPU, PCI, USB, SR-IOV NIC, vGPU) that can be assigned to VMs for device passthrough.

Device Types:

• PCI: General PCI passthrough (network cards, storage controllers, etc.)

• SR-IOV NIC: SR-IOV enabled NICs for direct network virtualization

• USB: USB device passthrough

• Host GPU: Full GPU passthrough to a single VM

• NVIDIA vGPU: NVIDIA vGPU for GPU sharing across multiple VMs

Device Classes:

GPU, vGPU, Storage, Human Input Device, Generic USB Device, Network, Media, Audio, FPGA, Generic PCI, Unknown

Example

>>> # List all resource groups
>>> for rg in client.resource_groups.list():
...     print(f"{rg.name}: {rg.device_type_display} ({rg.device_class_display})")

>>> # Get a specific resource group
>>> gpu_group = client.resource_groups.get(name="GPU Pool")
>>> print(f"Devices: {gpu_group.resource_count}")

>>> # Filter by device type
>>> gpu_groups = client.resource_groups.list_by_type("Host GPU")
>>> pci_groups = client.resource_groups.list_by_type("PCI")

>>> # Filter by device class
>>> network_groups = client.resource_groups.list_by_class("Network")

>>> # List enabled groups only
>>> enabled_groups = client.resource_groups.list_enabled()

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List resource groups with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of ResourceGroup objects.

Return type:

list[ResourceGroup]

Example

>>> # List all resource groups
>>> groups = client.resource_groups.list()

>>> # Filter by enabled status
>>> enabled = client.resource_groups.list(enabled=True)

>>> # Filter with OData
>>> gpu_groups = client.resource_groups.list(
...     filter="class eq 'gpu' and enabled eq true"
... )

get(key=None, *, name=None, uuid=None, fields=None)

Get a resource group by key (UUID), name, or UUID.

Parameters:

• key (str | int | None) – Resource group key (UUID string).

• name (str | None) – Resource group name.

• uuid (str | None) – Resource group UUID (alias for key).

• fields (list[str] | None) – List of fields to return.

Returns:

ResourceGroup object.

Raises:

• NotFoundError – If resource group not found.

• ValueError – If no identifier provided.

Return type:

ResourceGroup

Example

>>> # Get by UUID key
>>> rg = client.resource_groups.get("12345678-1234-1234-1234-123456789abc")

>>> # Get by name
>>> rg = client.resource_groups.get(name="GPU Pool")

>>> # Get by uuid parameter (same as key)
>>> rg = client.resource_groups.get(uuid="12345678-1234-1234-1234-123456789abc")

list_enabled(fields=None)

List enabled resource groups.

Parameters:

fields (list[str] | None) – List of fields to return.

Returns:

List of enabled ResourceGroup objects.

Return type:

list[ResourceGroup]

Example

>>> enabled_groups = client.resource_groups.list_enabled()
>>> for rg in enabled_groups:
...     print(f"{rg.name}: {rg.device_type_display}")

list_disabled(fields=None)

List disabled resource groups.

Parameters:

fields (list[str] | None) – List of fields to return.

Returns:

List of disabled ResourceGroup objects.

Return type:

list[ResourceGroup]

list_by_type(device_type, *, enabled=None, fields=None)

List resource groups by device type.

Parameters:

• device_type (str) – Device type - either display name (PCI, SR-IOV NIC, USB, Host GPU, NVIDIA vGPU) or API value (node_pci_devices, etc.)

• enabled (bool | None) – Filter by enabled status (optional).

• fields (list[str] | None) – List of fields to return.

Returns:

List of ResourceGroup objects matching the device type.

Return type:

list[ResourceGroup]

Example

>>> # List all Host GPU resource groups
>>> gpu_groups = client.resource_groups.list_by_type("Host GPU")

>>> # List enabled PCI resource groups
>>> pci_groups = client.resource_groups.list_by_type("PCI", enabled=True)

>>> # Use API value
>>> usb_groups = client.resource_groups.list_by_type("node_usb_devices")

list_by_class(device_class, *, enabled=None, fields=None)

List resource groups by device class.

Parameters:

• device_class (str) – Device class - either display name (GPU, vGPU, Storage, Network, etc.) or API value (gpu, vgpu, storage, network, etc.)

• enabled (bool | None) – Filter by enabled status (optional).

• fields (list[str] | None) – List of fields to return.

Returns:

List of ResourceGroup objects matching the device class.

Return type:

list[ResourceGroup]

Example

>>> # List all GPU class resource groups
>>> gpu_groups = client.resource_groups.list_by_class("GPU")

>>> # List enabled Network resource groups
>>> net_groups = client.resource_groups.list_by_class("Network", enabled=True)

>>> # List storage device groups
>>> storage_groups = client.resource_groups.list_by_class("Storage")

create(name, device_type, *, description='', device_class='unknown', enabled=True, settings=None, device_keys=None)

Create a new resource group.

Parameters:

• name (str) – Resource group name.

• device_type (Literal['node_pci_devices', 'node_sriov_nic_devices', 'node_usb_devices', 'node_host_gpu_devices', 'node_nvidia_vgpu_devices']) – Type of devices in this group.

• description (str) – Resource group description.

• device_class (str) – Device classification for UI icon.

• enabled (bool) – Whether the resource group is enabled.

• settings (dict[str, Any] | None) – Type-specific settings (see create_* methods for details).

• device_keys (list[int] | None) – List of device keys to auto-create rules from.

Returns:

Created ResourceGroup object.

Return type:

ResourceGroup

Example

>>> # Create a PCI device group
>>> group = client.resource_groups.create(
...     name="GPU Pool",
...     device_type="node_host_gpu_devices",
...     device_class="gpu",
... )

create_nvidia_vgpu(name, driver_file, *, nvidia_vgpu_profile=None, make_guest_driver_iso=False, driver_iso=None, scheduler_policy='1', strict_round_robin='', frequency=0, averaging_factor=33, time_slice_length_ns=0, description='', enabled=True, device_keys=None)

Create an NVIDIA vGPU resource group.

Parameters:

• name (str) – Resource group name.

• driver_file (int) – File key for the NVIDIA vGPU driver bundle.

• nvidia_vgpu_profile (int | None) – vGPU profile key to use.

• make_guest_driver_iso (bool) – Auto-create guest driver ISO from bundle.

• driver_iso (int | None) – Pre-existing guest driver ISO file key.

• scheduler_policy (Literal['1', '2', '3']) – vGPU scheduler policy (1=Best Effort, 2=Equal Share, 3=Fixed Share).

• strict_round_robin (Literal['', '0', '1']) – Enable strict round robin (“”, “0”, “1”).

• frequency (int) – Scheduler frequency (0-960).

• averaging_factor (int) – Averaging factor (1-60, default 33).

• time_slice_length_ns (int) – Time slice length in nanoseconds (0-30000000).

• description (str) – Resource group description.

• enabled (bool) – Whether the resource group is enabled.

• device_keys (list[int] | None) – List of PCI device keys to auto-create rules from.

Returns:

Created ResourceGroup object.

Return type:

ResourceGroup

Example

>>> group = client.resource_groups.create_nvidia_vgpu(
...     name="vGPU A100 Pool",
...     driver_file=driver.key,
...     nvidia_vgpu_profile=profile.key,
...     make_guest_driver_iso=True,
... )

create_usb(name, *, allow_guest_reset=True, allow_guest_reset_all=False, device_class='usb', description='', enabled=True, device_keys=None)

Create a USB device resource group.

Parameters:

• name (str) – Resource group name.

• allow_guest_reset (bool) – Allow VM to reset the USB device.

• allow_guest_reset_all (bool) – Allow VM to reset the USB hub.

• device_class (str) – Device classification for UI icon.

• description (str) – Resource group description.

• enabled (bool) – Whether the resource group is enabled.

• device_keys (list[int] | None) – List of USB device keys to auto-create rules from.

Returns:

Created ResourceGroup object.

Return type:

ResourceGroup

Example

>>> group = client.resource_groups.create_usb(
...     name="USB License Keys",
...     device_class="hid",
...     device_keys=[usb_device.key],
... )

create_sriov_nic(name, *, vf_count=1, native_vlan=0, vlan_qos=0, vlan_protocol='802.1Q', max_tx_rate=0, min_tx_rate=0, trust='off', spoof_checking='on', query_rss='default', virtual_link_state='default', mac_allow_override=True, vlan_allow_override=False, qos_allow_override=False, proto_allow_override=False, max_tx_rate_allow_override=False, min_tx_rate_allow_override=False, trust_allow_override=False, spoofchk_allow_override=False, query_rss_allow_override=False, state_allow_override=False, description='', enabled=True, device_keys=None)

Create an SR-IOV NIC resource group.

Parameters:

• name (str) – Resource group name.

• vf_count (int) – Number of VFs to create per physical device.

• native_vlan (int) – Default VLAN tag (0 disables VLAN tagging).

• vlan_qos (int) – VLAN QOS priority (0-7).

• vlan_protocol (Literal['802.1Q', '802.1ad']) – VLAN protocol (802.1Q or 802.1ad for QinQ).

• max_tx_rate (int) – Maximum transmit bandwidth in Mbps (0 disables).

• min_tx_rate (int) – Minimum transmit bandwidth in Mbps (0 disables).

• trust (Literal['default', 'on', 'off']) – Enable VF trust mode for special features.

• spoof_checking (Literal['default', 'on', 'off']) – Enable MAC spoof checking.

• query_rss (Literal['default', 'on', 'off']) – Allow querying RSS configuration.

• virtual_link_state (Literal['default', 'auto', 'enable', 'disable']) – Virtual link state (auto mirrors PF state).

• mac_allow_override (bool) – Allow VMs to override MAC address.

• vlan_allow_override (bool) – Allow VMs to override VLAN.

• qos_allow_override (bool) – Allow VMs to override QOS.

• proto_allow_override (bool) – Allow VMs to override protocol.

• max_tx_rate_allow_override (bool) – Allow VMs to override max TX rate.

• min_tx_rate_allow_override (bool) – Allow VMs to override min TX rate.

• trust_allow_override (bool) – Allow VMs to override trust.

• spoofchk_allow_override (bool) – Allow VMs to override spoof checking.

• query_rss_allow_override (bool) – Allow VMs to override query RSS.

• state_allow_override (bool) – Allow VMs to override link state.

• description (str) – Resource group description.

• enabled (bool) – Whether the resource group is enabled.

• device_keys (list[int] | None) – List of PCI device keys to auto-create rules from.

Returns:

Created ResourceGroup object.

Return type:

ResourceGroup

Example

>>> group = client.resource_groups.create_sriov_nic(
...     name="SR-IOV NIC Pool",
...     vf_count=8,
...     native_vlan=100,
...     device_keys=[pci_device.key],
... )

create_pci(name, *, device_class='pci', description='', enabled=True, device_keys=None)

Create a PCI passthrough resource group.

Parameters:

• name (str) – Resource group name.

• device_class (str) – Device classification for UI icon (gpu, storage, network, pci, etc.).

• description (str) – Resource group description.

• enabled (bool) – Whether the resource group is enabled.

• device_keys (list[int] | None) – List of PCI device keys to auto-create rules from.

Returns:

Created ResourceGroup object.

Return type:

ResourceGroup

Example

>>> group = client.resource_groups.create_pci(
...     name="NVMe Controllers",
...     device_class="storage",
...     device_keys=[pci_device.key],
... )

create_host_gpu(name, *, description='', enabled=True, device_keys=None)

Create a host GPU passthrough resource group.

Parameters:

• name (str) – Resource group name.

• description (str) – Resource group description.

• enabled (bool) – Whether the resource group is enabled.

• device_keys (list[int] | None) – List of GPU device keys to auto-create rules from.

Returns:

Created ResourceGroup object.

Return type:

ResourceGroup

Example

>>> group = client.resource_groups.create_host_gpu(
...     name="GPU Passthrough Pool",
...     device_keys=[gpu_device.key],
... )

update(key, **kwargs)

Update a resource group.

Parameters:

• key (str) – Resource group UUID.

• **kwargs (Any) – Fields to update. Common fields: - name: Resource group name - description: Description - enabled: Whether enabled - settings_args: Type-specific settings dict

Returns:

Updated ResourceGroup object.

Return type:

ResourceGroup

Example

>>> group = client.resource_groups.update(
...     group.key,
...     name="Renamed Pool",
...     enabled=False,
... )

delete(key)

Delete a resource group.

Parameters:

key (str) – Resource group UUID.

Raises:

ConflictError – If there are machine devices using this group.

Return type:

None

Note

All machine devices using this resource group must be removed first.

property rules: ResourceRuleManager

Access resource rules globally (unscoped).

Returns:

ResourceRuleManager for all resource rules.

Example

>>> # List all resource rules
>>> rules = client.resource_groups.rules.list()

class pyvergeos.resources.resource_groups.ResourceRule

Bases: ResourceObject

Resource rule that defines which devices belong to a resource group.

Resource rules use filter expressions to match devices by attributes such as vendor, slot, serial number, etc.

property resource_group_key: int | None

Parent resource group key.

property resource_group_name: str

Parent resource group name.

property name: str

Rule name.

property is_enabled: bool

Whether the rule is enabled.

property device_type: str

Device type (raw API value).

property device_type_display: str

Human-readable device type.

property node_key: int | None

Node filter (None = all nodes).

property node_name: str

Node name filter.

property filter_expression: str

OData-style filter expression for matching devices.

property filter_configuration: dict[str, Any]

Structured filter configuration.

property resource_count: int

Number of devices matched by this rule.

property is_system_created: bool

Whether this rule was auto-generated by the system.

property modified_at: datetime | None

Last modification timestamp.

refresh()

Refresh this rule’s data from the server.

Return type:

ResourceRule

save(**kwargs)

Update this rule with the given values.

Parameters:

kwargs (Any)

Return type:

ResourceRule

delete()

Delete this rule.

Return type:

None

class pyvergeos.resources.resource_groups.ResourceRuleManager

Bases: ResourceManager[ResourceRule]

Manages resource rules for device passthrough.

Resource rules define which physical devices belong to a resource group using filter expressions that match device attributes.

Example

>>> # List all rules for a resource group
>>> rules = resource_group.rules.list()

>>> # Create a rule matching devices by vendor
>>> rule = resource_group.rules.create(
...     name="Intel NICs",
...     filter="vendor ct 'Intel'",
... )

>>> # Create a rule for a specific PCI slot
>>> rule = resource_group.rules.create(
...     name="GPU in slot 3",
...     filter="slot eq '03:00.0'",
...     node=node.key,
... )

__init__(client, resource_group_key=None)

Parameters:

• client (VergeClient)

• resource_group_key (str | int | None)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, node_key=None, enabled_only=False, **filter_kwargs)

List resource rules.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• node_key (int | None) – Filter by node.

• enabled_only (bool) – Only return enabled rules.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of ResourceRule objects.

Return type:

list[ResourceRule]

get(key=None, *, name=None, fields=None)

Get a resource rule by key or name.

Parameters:

• key (int | None) – Rule $key (ID).

• name (str | None) – Rule name.

• fields (list[str] | None) – List of fields to return.

Returns:

ResourceRule object.

Raises:

• NotFoundError – If rule not found.

• ValueError – If no identifier provided.

Return type:

ResourceRule

create(name, filter_expression, *, node=None, enabled=True, auto_create_from_device=None)

Create a new resource rule.

Parameters:

• name (str) – Rule name.

• filter_expression (str) – OData-style filter for matching devices. Examples: “vendor ct ‘Intel’”, “slot eq ‘03:00.0’”, “vendor_device_hex eq ‘8086:8c31’”

• node (int | None) – Restrict to a specific node (None = all nodes).

• enabled (bool) – Whether the rule is enabled.

• auto_create_from_device (int | None) – Device key to auto-generate filter from.

Returns:

Created ResourceRule object.

Raises:

ValueError – If not scoped to a resource group.

Return type:

ResourceRule

Example

>>> rule = group.rules.create(
...     name="Intel X710 NICs",
...     filter_expression="vendor ct 'Intel' and device ct 'X710'",
... )

update(key, **kwargs)

Update a resource rule.

Parameters:

• key (int) – Rule $key (ID).

• **kwargs (Any) – Fields to update. Common fields: - name: Rule name - filter: Filter expression - node: Node filter (None = all nodes) - enabled: Whether enabled

Returns:

Updated ResourceRule object.

Return type:

ResourceRule

delete(key)

Delete a resource rule.

Parameters:

key (int) – Rule $key (ID).

Return type:

None

Shared Objects

Shared object management for tenant VM sharing.

class pyvergeos.resources.shared_objects.SharedObject

Bases: dict[str, Any]

Shared object resource representing a VM shared with a tenant.

__init__(data, manager)

Parameters:

• data (dict[str, Any])

• manager (SharedObjectManager)

Return type:

None

property key: int

Get the shared object’s primary key.

property name: str

Get the shared object name.

property description: str | None

Get the shared object description.

property tenant_key: int

Get the recipient tenant’s key.

property tenant_name: str | None

Get the recipient tenant’s name.

property object_type: str

Get the type of shared object (e.g., ‘vm’).

property object_id: str | None

Get the object ID (e.g., ‘vms/123’).

property snapshot_path: str | None

Get the snapshot path.

property snapshot_key: int | None

Get the snapshot key from the snapshot path.

property is_inbox: bool

Check if this is an inbox item (pending import).

property created_at: datetime | None

Get the creation timestamp.

import_object()

Import this shared object into the tenant.

This triggers the import process which creates a copy of the shared VM within the tenant’s environment.

Returns:

Action response (may include task information).

Return type:

dict[str, Any] | None

Example

>>> shared_obj = client.shared_objects.get(key=42)
>>> shared_obj.import_object()

refresh()

Refresh shared object data from API.

Returns:

Updated SharedObject.

Return type:

SharedObject

delete()

Delete this shared object.

This removes the share from the tenant. It does not affect VMs that have already been imported.

Return type:

None

class pyvergeos.resources.shared_objects.SharedObjectManager

Bases: object

Manager for shared object operations.

Shared objects allow parent systems to share VMs with tenants. The shared VM can then be imported by the tenant to create their own copy.

Example

>>> # List shared objects for a tenant
>>> shared = client.shared_objects.list(tenant_key=123)
>>> for obj in shared:
...     print(f"{obj.name}: {obj.object_type}")

>>> # Share a VM with a tenant
>>> shared = client.shared_objects.create(
...     tenant_key=123,
...     vm_key=456,
...     name="Ubuntu Template",
...     description="Pre-configured Ubuntu server"
... )

>>> # Import a shared object in the tenant
>>> client.shared_objects.import_object(shared.key)

>>> # Remove a share
>>> client.shared_objects.delete(shared.key)

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(tenant_key=None, tenant=None, name=None, inbox_only=False, fields=None, limit=None, offset=None)

List shared objects with optional filtering.

Parameters:

• tenant_key (int | None) – Filter by recipient tenant key.

• tenant (Tenant | None) – Filter by recipient Tenant object (alternative to tenant_key).

• name (str | None) – Filter by shared object name (exact match).

• inbox_only (bool) – Only return inbox items (pending imports).

• fields (builtins.list[str] | None) – List of fields to return (defaults to rich field set).

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

Returns:

List of SharedObject objects.

Return type:

builtins.list[SharedObject]

Example

>>> # List all shared objects for a tenant
>>> shared = client.shared_objects.list(tenant_key=123)

>>> # List inbox items only
>>> inbox = client.shared_objects.list(tenant_key=123, inbox_only=True)

>>> # List by tenant object
>>> tenant = client.tenants.get(name="my-tenant")
>>> shared = client.shared_objects.list(tenant=tenant)

get(key=None, *, tenant_key=None, name=None, fields=None)

Get a single shared object by key or by tenant/name.

Parameters:

• key (int | None) – Shared object $key (ID).

• tenant_key (int | None) – Tenant key (required when using name).

• name (str | None) – Shared object name (requires tenant_key).

• fields (list[str] | None) – List of fields to return (defaults to rich field set).

Returns:

SharedObject object.

Raises:

• NotFoundError – If shared object not found.

• ValueError – If neither key nor tenant_key/name provided.

Return type:

SharedObject

Example

>>> # Get by key
>>> shared = client.shared_objects.get(42)

>>> # Get by tenant and name
>>> shared = client.shared_objects.get(tenant_key=123, name="Ubuntu Template")

create(tenant_key=None, tenant=None, vm_key=None, vm_name=None, name=None, description=None, snapshot_name=None)

Share a VM with a tenant.

Creates a shared object that the tenant can import to create their own copy of the VM. This automatically creates a machine snapshot of the VM to share.

Parameters:

• tenant_key (int | None) – Recipient tenant $key (ID).

• tenant (Tenant | None) – Recipient Tenant object (alternative to tenant_key).

• vm_key (int | None) – VM $key to share.

• vm_name (str | None) – VM name to share (alternative to vm_key, will be looked up).

• name (str | None) – Name for the shared object (defaults to VM name).

• description (str | None) – Optional description.

• snapshot_name (str | None) – Optional name for the machine snapshot. If not provided, a unique name is generated.

Returns:

Created SharedObject.

Raises:

• ValueError – If tenant or VM not specified.

• NotFoundError – If VM not found by name.

• APIError – If snapshot or shared object creation fails.

Return type:

SharedObject

Example

>>> # Share by tenant key and VM key
>>> shared = client.shared_objects.create(
...     tenant_key=123,
...     vm_key=456,
...     name="Ubuntu Template"
... )

>>> # Share by objects
>>> tenant = client.tenants.get(name="my-tenant")
>>> vm = client.vms.get(name="template-vm")
>>> shared = client.shared_objects.create(
...     tenant=tenant,
...     vm_key=vm.key,
...     description="Pre-configured template"
... )

import_object(key)

Import a shared object into the tenant.

This triggers the import process which creates a copy of the shared VM within the tenant’s environment. The import runs asynchronously.

Parameters:

key (int) – Shared object $key to import.

Returns:

Action response (may include task information).

Return type:

dict[str, Any] | None

Example

>>> # Import by key
>>> client.shared_objects.import_object(42)

>>> # Import from object
>>> shared = client.shared_objects.get(tenant_key=123, name="Template")
>>> shared.import_object()

refresh_object(key)

Refresh a shared object.

This updates the shared object’s snapshot.

Parameters:

key (int) – Shared object $key to refresh.

Returns:

Action response (may include task information).

Return type:

dict[str, Any] | None

delete(key)

Delete a shared object.

This removes the share from the tenant. It does not affect VMs that have already been imported by the tenant.

Parameters:

key (int) – Shared object $key to delete.

Return type:

None

Example

>>> client.shared_objects.delete(42)

>>> # Or via object
>>> shared = client.shared_objects.get(42)
>>> shared.delete()

list_for_tenant(tenant, inbox_only=False)

List shared objects for a specific tenant.

Convenience method that wraps list() with a Tenant object.

Parameters:

• tenant (Tenant) – Tenant object to list shared objects for.

• inbox_only (bool) – Only return inbox items (pending imports).

Returns:

List of SharedObject objects.

Return type:

builtins.list[SharedObject]

Example

>>> tenant = client.tenants.get(name="my-tenant")
>>> shared = client.shared_objects.list_for_tenant(tenant)

Cloud-Init Files

Cloud-init file resource manager for VM provisioning automation.

class pyvergeos.resources.cloudinit_files.CloudInitFile

Bases: ResourceObject

Cloud-init file resource object.

Represents a cloud-init configuration file in VergeOS used for VM provisioning automation. Cloud-init files provide user-data, meta-data, network-config, and other configuration to VMs during boot.

Properties:

name: File name (typically /user-data, /meta-data, /network-config). owner: Owner reference (e.g., “vms/123”). vm_key: Key of the VM this file belongs to. render: Render type (API value: no, variables, jinja2). render_display: Friendly render type name. contains_variables: Whether file contains VergeOS variables. filesize: Size of file contents in bytes. allocated_bytes: Allocated storage size. used_bytes: Used storage size on disk. creator: Username who created the file. modified_at: Datetime when file was last modified. contents: File contents (if loaded).

property name: str

Get file name.

property owner: str

Get owner reference (e.g., ‘vms/123’).

property vm_key: int | None

Get the key of the VM this file belongs to.

property render: str

no, variables, jinja2).

Type:

Get render type (API value

property render_display: str

Get friendly render type name.

property contains_variables: bool

Check if file contains VergeOS variables.

property filesize: int

Get size of file contents in bytes.

property allocated_bytes: int

Get allocated storage size in bytes.

property used_bytes: int

Get used storage size on disk in bytes.

property creator: str

Get username who created the file.

property modified_at: datetime | None

Get datetime when file was last modified.

property contents: str | None

Get file contents from the raw API response.

Note: The VergeOS API does not return file contents in standard GET responses. This property will typically return None. To retrieve actual file contents, use the get_content() method which fetches from the download endpoint.

Example

>>> file = client.cloudinit_files.get(key=123)
>>> file.contents  # Usually None
>>> content = file.get_content()  # Actual content

get_content(*, as_bytes=False)

Retrieve the full file contents.

Parameters:

as_bytes (bool) – If True, return contents as bytes instead of string.

Returns:

File contents as string (default) or bytes.

Return type:

str | bytes

save(**kwargs)

Update this cloud-init file.

Parameters:

**kwargs (Any) – Fields to update (name, contents, render).

Returns:

Updated CloudInitFile object.

Return type:

CloudInitFile

delete()

Delete this cloud-init file.

Return type:

None

class pyvergeos.resources.cloudinit_files.CloudInitFileManager

Bases: ResourceManager[CloudInitFile]

Manager for cloud-init file operations.

Provides CRUD operations for cloud-init files used in VM provisioning. Cloud-init files are associated with specific VMs and provide configuration for automated VM setup during boot.

Example

>>> # List cloud-init files for a VM
>>> files = client.cloudinit_files.list(vm_key=123)
>>>
>>> # Create a user-data file
>>> user_data = '''#cloud-config
... users:
...   - name: admin
...     sudo: ALL=(ALL) NOPASSWD:ALL
... '''
>>> file = client.cloudinit_files.create(
...     vm_key=123,
...     name="/user-data",
...     contents=user_data,
...     render="No"
... )
>>>
>>> # Get file contents
>>> content = file.get_content()
>>>
>>> # Update file
>>> file = client.cloudinit_files.update(file.key, render="Variables")
>>>
>>> # Delete file
>>> client.cloudinit_files.delete(file.key)

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, vm_key=None, name=None, render=None, **filter_kwargs)

List cloud-init files with optional filtering.

Note: File contents are not returned in list operations. Use get_content() to retrieve actual file contents.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• vm_key (int | None) – Filter by VM $key.

• name (str | None) – Filter by file name (exact match or wildcard *).

• render (str | None) – Filter by render type (No, Variables, Jinja2).

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of CloudInitFile objects.

Return type:

list[CloudInitFile]

get(key=None, *, name=None, vm_key=None, fields=None)

Get a cloud-init file by key or name.

Note: File contents are not returned in GET operations. Use get_content() to retrieve actual file contents.

Parameters:

• key (int | None) – CloudInitFile $key (ID).

• name (str | None) – File name (exact match). Requires vm_key if using name.

• vm_key (int | None) – VM $key (required when searching by name).

• fields (list[str] | None) – List of fields to return.

Returns:

CloudInitFile object.

Raises:

• NotFoundError – If file not found.

• ValueError – If neither key nor (name + vm_key) provided.

Return type:

CloudInitFile

create(vm_key, name, *, contents=None, render='No')

Create a new cloud-init file.

Parameters:

• vm_key (int) – VM $key (ID) to attach the file to.

• name (str) – File name (typically /user-data, /meta-data, /network-config). Maximum 256 characters.

• contents (str | None) – File contents. Maximum 64KB.

• render (str) – Render type for variable processing: - No: File is used as-is without processing (default). - Variables: File supports VergeOS variable substitution. - Jinja2: File is processed as a Jinja2 template.

Returns:

Created CloudInitFile object.

Raises:

• ValidationError – If parameters invalid or contents too large.

• ConflictError – If file with same name already exists for VM.

Return type:

CloudInitFile

update(key, *, name=None, contents=None, render=None)

Update a cloud-init file.

Parameters:

• key (int) – CloudInitFile $key (ID).

• name (str | None) – New file name.

• contents (str | None) – New file contents. Maximum 64KB.

• render (str | None) – New render type (No, Variables, Jinja2).

Returns:

Updated CloudInitFile object.

Raises:

• NotFoundError – If file not found.

• ValidationError – If parameters invalid.

Return type:

CloudInitFile

delete(key)

Delete a cloud-init file.

Parameters:

key (int) – CloudInitFile $key (ID).

Raises:

NotFoundError – If file not found.

Return type:

None

get_content(key, *, as_bytes=False)

Retrieve the raw contents of a cloud-init file.

This method downloads the file contents directly from the API, which is useful when you need the exact file content without any metadata.

Parameters:

• key (int) – CloudInitFile $key (ID).

• as_bytes (bool) – If True, return contents as bytes instead of string.

Returns:

File contents as string (default) or bytes.

Raises:

NotFoundError – If file not found.

Return type:

str | bytes

list_for_vm(vm_key)

List all cloud-init files for a specific VM.

Convenience method that filters by VM key.

Note: File contents are not returned. Use get_content() to retrieve actual file contents for individual files.

Parameters:

vm_key (int) – VM $key (ID).

Returns:

List of CloudInitFile objects for the VM.

Return type:

list[CloudInitFile]

class pyvergeos.resources.cloudinit_files.VMCloudInitFileManager

Bases: CloudInitFileManager

Manager for cloud-init files scoped to a specific VM.

This manager is accessed through a VM object’s cloudinit_files property and automatically filters operations to that VM.

Example

>>> vm = client.vms.get(name="my-vm")
>>> # List cloud-init files for this VM
>>> files = vm.cloudinit_files.list()
>>> # Create user-data file
>>> vm.cloudinit_files.create(name="/user-data", contents="...", render="No")

__init__(client, vm)

Parameters:

• client (VergeClient)

• vm (VM)

Return type:

None

property vm_key: int

Get the VM key.

list(filter=None, fields=None, limit=None, offset=None, *, name=None, render=None, **filter_kwargs)

List cloud-init files for this VM.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• name (str | None) – Filter by file name (exact match or wildcard *).

• render (str | None) – Filter by render type (No, Variables, Jinja2).

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of CloudInitFile objects for this VM.

Return type:

list[CloudInitFile]

get(key=None, *, name=None, fields=None)

Get a cloud-init file by key or name for this VM.

Parameters:

• key (int | None) – CloudInitFile $key (ID).

• name (str | None) – File name (exact match).

• fields (list[str] | None) – List of fields to return.

Returns:

CloudInitFile object.

Raises:

• NotFoundError – If file not found.

• ValueError – If neither key nor name provided.

Return type:

CloudInitFile

create(name, *, contents=None, render='No')

Create a cloud-init file for this VM.

Parameters:

• name (str) – File name (e.g., /user-data, /meta-data, /network-config).

• contents (str | None) – File contents. Maximum 64KB. Optional for initial creation.

• render (str) – Render type: No, Variables, or Jinja2 (default: No).

Returns:

Created CloudInitFile object.

Raises:

ValidationError – If parameters invalid.

Return type:

CloudInitFile

Example

>>> vm = client.vms.get(name="my-vm")
>>> # Create user-data with cloud-config
>>> vm.cloudinit_files.create(
...     name="/user-data",
...     contents="#cloud-config\nusers:\n  - name: admin\n",
...     render="No"
... )

Files

File management for VergeOS media catalog.

class pyvergeos.resources.files.File

Bases: ResourceObject

Represents a file in the VergeOS media catalog.

Files can be ISO images for mounting to VM drives, disk images for import, OVA/OVF packages, or other media types.

property name: str

File name.

property file_type: str

File type (iso, qcow2, vmdk, etc.).

property type_display: str

Human-readable file type.

property description: str

File description.

property size_bytes: int

File size in bytes.

property size_gb: float

File size in GB.

property allocated_bytes: int

Allocated storage in bytes.

property allocated_gb: float

Allocated storage in GB.

property used_bytes: int

Used storage in bytes (actual on-disk size).

property used_gb: float

Used storage in GB.

property preferred_tier: int | None

Preferred storage tier (1-5).

property modified: datetime | None

Last modification timestamp.

property creator: str

Username who created the file.

class pyvergeos.resources.files.FileManager

Bases: ResourceManager[File]

Manages files in the VergeOS media catalog.

Files in the media catalog can be used as: - ISO images for VM CD-ROM drives - Disk images for VM drive import - OVA/OVF packages for VM import

Example

>>> files = client.files.list(file_type="iso")
>>> for f in files:
...     print(f"{f.name}: {f.size_gb} GB")

>>> # Upload a file
>>> uploaded = client.files.upload("/path/to/image.iso", tier=1)

>>> # Download a file
>>> client.files.download(name="ubuntu.iso", destination="/tmp/")

list(filter=None, fields=None, limit=None, offset=None, file_type=None, **filter_kwargs)

List files in the media catalog.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• file_type (str | list[str] | None) – Filter by file type(s) - “iso”, “qcow2”, “vmdk”, etc.

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of File objects.

Return type:

list[File]

Example

>>> # List all ISO files
>>> isos = client.files.list(file_type="iso")

>>> # List importable disk images
>>> images = client.files.list(file_type=["ova", "ovf", "vmdk", "qcow2"])

get(key=None, *, name=None, fields=None)

Get a file by key or name.

Parameters:

• key (int | None) – File $key (ID).

• name (str | None) – File name.

• fields (list[str] | None) – List of fields to return.

Returns:

File object.

Raises:

• NotFoundError – If file not found.

• ValueError – If neither key nor name provided.

Return type:

File

upload(path, name=None, description=None, tier=None, progress_callback=None)

Upload a file to the media catalog.

Parameters:

• path (str | Path) – Local path to the file to upload.

• name (str | None) – Name for the file in VergeOS (defaults to local filename).

• description (str | None) – Optional description.

• tier (int | None) – Preferred storage tier (1-5).

• progress_callback (Callable[[int, int], None] | None) – Optional callback(bytes_uploaded, total_bytes).

Returns:

Uploaded File object.

Raises:

• FileNotFoundError – If local file doesn’t exist.

• ValidationError – If upload fails.

Return type:

File

Example

>>> def show_progress(uploaded, total):
...     pct = (uploaded / total) * 100
...     print(f"\rUploading: {pct:.1f}%", end="")
>>> client.files.upload("/path/to/image.iso", tier=1, progress_callback=show_progress)

download(key=None, *, name=None, destination='.', filename=None, overwrite=False, progress_callback=None)

Download a file from the media catalog.

Parameters:

• key (int | None) – File $key (ID).

• name (str | None) – File name (alternative to key).

• destination (str | Path) – Directory or full path for downloaded file.

• filename (str | None) – Override the filename (defaults to file’s name).

• overwrite (bool) – Whether to overwrite existing files.

• progress_callback (Callable[[int, int], None] | None) – Optional callback(bytes_downloaded, total_bytes).

Returns:

Path to the downloaded file.

Raises:

• NotFoundError – If file not found.

• FileExistsError – If destination exists and overwrite=False.

• ValueError – If neither key nor name provided.

Return type:

Path

Example

>>> path = client.files.download(name="ubuntu.iso", destination="/tmp/")
>>> print(f"Downloaded to: {path}")

delete(key)

Delete a file from the media catalog.

Parameters:

key (int) – File $key (ID).

Raises:

• NotFoundError – If file not found.

• ValidationError – If file is in use by VM drives.

Return type:

None

Note

Files that are referenced by VM drives cannot be deleted until the references are removed.

Webhooks

Webhook resource manager for VergeOS notification integrations.

class pyvergeos.resources.webhooks.Webhook

Bases: ResourceObject

Webhook URL configuration resource object.

Represents a webhook URL configuration in VergeOS that can receive notifications when events occur.

Properties:

name: Webhook name (unique identifier). webhook_type: Webhook type (currently only ‘custom’). url: Destination URL for webhook payloads. headers: Dict of custom HTTP headers. headers_raw: Raw header string in “Name:Value” format. authorization_type: Auth method (none, basic, bearer, apikey). authorization_type_display: Friendly auth type name. is_insecure: True if insecure SSL connections are allowed. timeout: Request timeout in seconds (3-120). retries: Number of retry attempts (0-100).

property name: str

Get webhook name.

property webhook_type: str

Get webhook type (currently only ‘custom’).

property url: str

Get destination URL.

property headers: dict[str, str]

Get headers as dictionary.

property headers_raw: str

Value’ format.

Type:

Get raw header string in ‘Name

property authorization_type: str

Get authorization type (API value).

property authorization_type_display: str

Get friendly authorization type name.

property is_insecure: bool

Check if insecure SSL connections are allowed.

property timeout: int

Get request timeout in seconds.

property retries: int

Get number of retry attempts.

send(message=None)

Send a test/manual message to this webhook.

Parameters:

message (str | dict[str, Any] | None) – JSON message payload. Can be a JSON string or dict. Defaults to a simple test message.

Returns:

Action response (may include task info).

Return type:

dict[str, Any] | None

history(*, status=None, pending=False, failed=False, limit=100)

Get execution history for this webhook.

Parameters:

• status (str | None) – Filter by status (queued, running, sent, error).

• pending (bool) – If True, show only pending (queued/running) messages.

• failed (bool) – If True, show only failed (error) messages.

• limit (int) – Maximum number of entries to return.

Returns:

List of WebhookHistory objects.

Return type:

list[WebhookHistory]

class pyvergeos.resources.webhooks.WebhookHistory

Bases: ResourceObject

Webhook execution history resource object.

Represents a webhook message delivery attempt and its status.

Properties:

webhook_key: Key of the parent webhook URL. status: Delivery status (API value). status_display: Friendly status name. status_info: Additional status/error information. message: Parsed message payload (if JSON). message_raw: Raw message string. is_pending: True if message is queued or running. is_sent: True if message was successfully sent. has_error: True if delivery failed. last_attempt_at: Datetime of last delivery attempt. created_at: Datetime when message was queued.

property webhook_key: int | None

Get parent webhook URL key.

property status: str

Get delivery status (API value).

property status_display: str

Get friendly status name.

property status_info: str

Get additional status/error information.

property message: dict[str, Any] | str | None

Get parsed message payload (if JSON).

property message_raw: str

Get raw message string.

property is_pending: bool

Check if message is pending (queued or running).

property is_sent: bool

Check if message was successfully sent.

property has_error: bool

Check if delivery failed.

property last_attempt_at: datetime | None

Get datetime of last delivery attempt.

property created_at: datetime | None

Get datetime when message was queued.

class pyvergeos.resources.webhooks.WebhookManager

Bases: ResourceManager[Webhook]

Manager for webhook URL configurations.

Provides CRUD operations for webhook URL configurations and methods to send test messages and view delivery history.

Example

>>> # List all webhooks
>>> webhooks = client.webhooks.list()
>>>
>>> # Create a webhook
>>> webhook = client.webhooks.create(
...     name="slack-alerts",
...     url="https://hooks.slack.com/services/xxx",
...     authorization_type="none"
... )
>>>
>>> # Send a test message
>>> client.webhooks.send(webhook.key, message='{"text": "Hello!"}')
>>>
>>> # View delivery history
>>> history = client.webhooks.history(webhook_key=webhook.key)

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, *, authorization_type=None, **filter_kwargs)

List webhooks with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• authorization_type (str | None) – Filter by auth type (None, Basic, Bearer, ApiKey).

• **filter_kwargs (Any) – Additional filter arguments.

Returns:

List of Webhook objects.

Return type:

list[Webhook]

get(key=None, *, name=None, fields=None)

Get a webhook by key or name.

Parameters:

• key (int | None) – Webhook $key (ID).

• name (str | None) – Webhook name (exact match).

• fields (list[str] | None) – List of fields to return.

Returns:

Webhook object.

Raises:

• NotFoundError – If webhook not found.

• ValueError – If neither key nor name provided.

Return type:

Webhook

create(name, url, *, headers=None, authorization_type='None', authorization_value=None, allow_insecure=False, timeout=None, retries=None)

Create a new webhook URL configuration.

Parameters:

• name (str) – Webhook name (unique).

• url (str) – Destination URL (must start with http:// or https://).

• headers (dict[str, str] | str | None) – Custom HTTP headers as dict or “Name:Value” string.

• authorization_type (str) – Auth method (None, Basic, Bearer, ApiKey).

• authorization_value (str | None) – Auth credential value. - Basic: “username:password” (will be base64 encoded) - Bearer: token value - ApiKey: key value

• allow_insecure (bool) – Allow insecure SSL connections.

• timeout (int | None) – Request timeout in seconds (3-120, default 5).

• retries (int | None) – Number of retry attempts (0-100, default 3).

Returns:

Created Webhook object.

Raises:

• ValidationError – If parameters invalid.

• ConflictError – If webhook with name already exists.

Return type:

Webhook

update(key, *, name=None, url=None, headers=None, authorization_type=None, authorization_value=None, allow_insecure=None, timeout=None, retries=None)

Update a webhook configuration.

Parameters:

• key (int) – Webhook $key (ID).

• name (str | None) – New webhook name.

• url (str | None) – New destination URL.

• headers (dict[str, str] | str | None) – New custom HTTP headers. Pass empty dict to clear.

• authorization_type (str | None) – New auth method.

• authorization_value (str | None) – New auth credential value.

• allow_insecure (bool | None) – New allow insecure setting.

• timeout (int | None) – New request timeout.

• retries (int | None) – New retry count.

Returns:

Updated Webhook object.

Raises:

• NotFoundError – If webhook not found.

• ValidationError – If parameters invalid.

Return type:

Webhook

delete(key)

Delete a webhook configuration.

This also deletes any pending messages in the queue for this webhook.

Parameters:

key (int) – Webhook $key (ID).

Raises:

NotFoundError – If webhook not found.

Return type:

None

send(key, *, message=None)

Send a message to a webhook.

The message is queued for delivery. Use history() to check delivery status.

Parameters:

• key (int) – Webhook $key (ID).

• message (str | dict[str, Any] | None) – JSON message payload. Can be a JSON string or dict. Defaults to a simple test message.

Returns:

Action response (may include task info).

Raises:

NotFoundError – If webhook not found.

Return type:

dict[str, Any] | None

history(key=None, *, webhook_key=None, webhook_name=None, status=None, pending=False, failed=False, limit=100, fields=None)

Get webhook execution history.

Parameters:

• key (int | None) – History entry $key (ID) to get specific entry.

• webhook_key (int | None) – Filter by webhook $key.

• webhook_name (str | None) – Filter by webhook name.

• status (str | None) – Filter by status (queued, running, sent, error).

• pending (bool) – If True, show only pending (queued/running) messages.

• failed (bool) – If True, show only failed (error) messages.

• limit (int) – Maximum number of entries to return.

• fields (list[str] | None) – List of fields to return.

Returns:

List of WebhookHistory objects.

Return type:

list[WebhookHistory]

get_history(key)

Get a specific webhook history entry by key.

Parameters:

key (int) – History entry $key (ID).

Returns:

WebhookHistory object.

Raises:

NotFoundError – If history entry not found.

Return type:

WebhookHistory

list_pending(webhook_key=None, limit=100)

List pending webhook messages (queued or running).

Parameters:

• webhook_key (int | None) – Filter by webhook $key.

• limit (int) – Maximum number of entries to return.

Returns:

List of WebhookHistory objects.

Return type:

list[WebhookHistory]

list_failed(webhook_key=None, limit=100)

List failed webhook messages.

Parameters:

• webhook_key (int | None) – Filter by webhook $key.

• limit (int) – Maximum number of entries to return.

Returns:

List of WebhookHistory objects.

Return type:

list[WebhookHistory]

Base Classes

Base resource manager providing CRUD operations.

class pyvergeos.resources.base.ResourceObject

Bases: dict[str, Any]

Dict subclass with attribute access and resource methods.

Provides a dict-like object that also supports attribute access and common resource operations like refresh, save, and delete.

__init__(data, manager)

Parameters:

• data (dict[str, Any])

• manager (ResourceManager[Any])

Return type:

None

property key: int

Resource primary key ($key).

Raises:

ValueError – If resource has no $key (not yet persisted).

refresh()

Refresh resource data from API.

Returns:

Updated resource object.

Return type:

ResourceObject

save(**kwargs)

Save changes to resource.

Parameters:

**kwargs (Any) – Fields to update.

Returns:

Updated resource object.

Return type:

ResourceObject

delete()

Delete this resource.

Return type:

None

class pyvergeos.resources.base.ResourceManager

Bases: Generic[T]

Base class for resource managers.

Provides standard CRUD operations and filtering for API resources. Subclasses should set _endpoint and optionally override _to_model.

__init__(client)

Parameters:

client (VergeClient)

Return type:

None

list(filter=None, fields=None, limit=None, offset=None, **filter_kwargs)

List resources with optional filtering.

Parameters:

• filter (str | None) – OData filter string.

• fields (list[str] | None) – List of fields to return.

• limit (int | None) – Maximum number of results.

• offset (int | None) – Skip this many results.

• **filter_kwargs (Any) – Shorthand filter arguments.

Returns:

List of resource objects.

Return type:

list[T]

get(key=None, *, name=None, fields=None)

Get a single resource by key or name.

Parameters:

• key (int | None) – Resource $key (ID).

• name (str | None) – Resource name (will search if key not provided).

• fields (list[str] | None) – List of fields to return.

Returns:

Resource object.

Raises:

• NotFoundError – If resource not found.

• ValueError – If neither key nor name provided.

Return type:

T

create(**kwargs)

Create a new resource.

Parameters:

**kwargs (Any) – Resource attributes.

Returns:

Created resource object.

Return type:

T

update(key, **kwargs)

Update an existing resource.

Parameters:

• key (int) – Resource $key (ID).

• **kwargs (Any) – Attributes to update.

Returns:

Updated resource object.

Return type:

T

delete(key)

Delete a resource.

Parameters:

key (int) – Resource $key (ID).

Return type:

None

action(key, action_name, **kwargs)

Execute an action on a resource.

Parameters:

• key (int) – Resource $key (ID).

• action_name (str) – Name of the action (e.g., “poweron”, “snapshot”).

• **kwargs (Any) – Action parameters.

Returns:

Action response (often includes task information).

Return type:

dict[str, Any] | None

iter_all(page_size=100, **kwargs)

Iterate through all resources, handling pagination automatically.

Parameters:

• page_size (int) – Number of items per page.

• **kwargs (Any) – Additional filter arguments.

Yields:

Resource objects.

Return type:

Iterator[T]

__iter__()

Iterate over all resources (uses iter_all with default page size).

Return type:

Iterator[T]