Client

The VergeClient class is the main entry point for interacting with VergeOS.

VergeClient

class pyvergeos.VergeClient

Bases: object

Main client for interacting with VergeOS API v4.

Thread Safety:

This client is NOT thread-safe. Each thread should use its own VergeClient instance, or external locking should be used.

Example

>>> client = VergeClient(
...     host="192.168.1.100",
...     username="admin",
...     password="secret"
... )
>>> vms = client.vms.list()
>>> client.disconnect()

# Or use as context manager >>> with VergeClient(host=”…”, …) as client: … vms = client.vms.list()

# Or from environment variables >>> client = VergeClient.from_env()

__init__(host, username=None, password=None, token=None, verify_ssl=True, timeout=30, auto_connect=True, retry_total=3, retry_backoff_factor=1, retry_status_codes=None)

Initialize VergeClient.

Parameters:

• host (str) – VergeOS hostname or IP address.

• username (str | None) – Username for basic authentication.

• password (str | None) – Password for basic authentication.

• token (str | None) – API token for bearer authentication.

• verify_ssl (bool) – Whether to verify SSL certificates.

• timeout (int) – Default request timeout in seconds.

• auto_connect (bool) – Whether to connect immediately.

• retry_total (int) – Number of retry attempts for transient failures (default: 3).

• retry_backoff_factor (float) – Backoff factor for retry delay calculation. Delay = backoff_factor * (2 ** retry_count). Default: 1.

• retry_status_codes (frozenset[int] | None) – HTTP status codes that trigger automatic retry. Default: 429, 500, 502, 503, 504.

Raises:

ValueError – If neither token nor username/password provided.

Return type:

None

classmethod from_env()

Create client from environment variables.

Environment variables:

VERGE_HOST: VergeOS hostname or IP (required) VERGE_USERNAME: Username for basic auth VERGE_PASSWORD: Password for basic auth VERGE_TOKEN: API token for bearer auth VERGE_VERIFY_SSL: Whether to verify SSL (default: true) VERGE_TIMEOUT: Request timeout in seconds (default: 30) VERGE_RETRY_TOTAL: Number of retry attempts (default: 3) VERGE_RETRY_BACKOFF: Retry backoff factor (default: 1)

Returns:

Configured VergeClient instance.

Raises:

ValueError – If VERGE_HOST is not set.

Return type:

VergeClient

connect()

Establish connection to VergeOS.

Returns:

Self for method chaining.

Raises:

• ConnectionError – If connection fails.

• AuthenticationError – If authentication fails.

• ValueError – If credentials not provided.

Return type:

VergeClient

disconnect()

Disconnect from VergeOS and cleanup resources.

Return type:

None

property is_connected: bool

Check if client is connected.

property version: str | None

Get VergeOS version (yb_version).

property os_version: str | None

Get VergeOS OS version.

property cloud_name: str | None

Get the cloud name of the connected system.

property alarms: AlarmManager

Access alarm operations.

property auth_sources: AuthSourceManager

Access authentication source operations for external identity providers.

Authentication sources enable SSO via OAuth2/OIDC providers such as Azure AD, Google, GitLab, Okta, and generic OpenID Connect.

Example

>>> # List all auth sources
>>> for source in client.auth_sources.list():
...     print(f"{source.name} ({source.driver})")

>>> # Get an Azure AD source
>>> azure = client.auth_sources.get(name="Azure AD")

>>> # Create a Google auth source
>>> source = client.auth_sources.create(
...     name="Google",
...     driver="google",
...     settings={
...         "client_id": "your-client-id",
...         "client_secret": "your-secret",
...     }
... )

property auth_source_states: AuthSourceStateManager

Access authentication source OAuth state tokens.

States are ephemeral tokens created during the OAuth authentication flow. They expire after 15 minutes.

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}")

property logs: LogManager

Access log operations.

property vms: VMManager

Access VM operations.

property networks: NetworkManager

Access network operations.

property tenants: TenantManager

Access tenant operations.

property tenant_dashboard: TenantDashboardManager

Access tenant dashboard with aggregated metrics.

Provides high-level overview of all tenant status and resource utilization for monitoring and capacity planning.

Example

>>> dashboard = client.tenant_dashboard.get()
>>> print(f"Online: {dashboard.tenants_online}/{dashboard.tenants_count}")
>>> print(f"Errors: {dashboard.tenants_error}")

property billing: BillingManager

Access billing records for resource usage tracking and chargeback.

Provides access to system-wide resource utilization records for billing, chargeback, and capacity planning purposes.

Example

>>> # List billing records
>>> records = client.billing.list(limit=100)
>>> for record in records:
...     print(f"{record.created}: {record.used_cores} cores")

>>> # Get the latest billing record
>>> latest = client.billing.get_latest()
>>> print(f"CPU: {latest.cpu_utilization_pct:.1f}%")

>>> # Generate a new billing report
>>> client.billing.generate()

>>> # Get summary over time
>>> from datetime import datetime, timedelta
>>> since = datetime.now() - timedelta(days=30)
>>> summary = client.billing.get_summary(since=since)

property network_dashboard: NetworkDashboardManager

Access network dashboard with aggregated metrics.

Provides high-level overview of all network status, counts by type and state, and top bandwidth consumers for monitoring.

Example

>>> dashboard = client.network_dashboard.get()
>>> print(f"Online: {dashboard.vnets_online}/{dashboard.vnets_count}")
>>> print(f"External: {dashboard.ext_online}/{dashboard.ext_count}")
>>> print(f"Internal: {dashboard.int_online}/{dashboard.int_count}")
>>> if dashboard.has_errors:
...     print(f"WARNING: {dashboard.vnets_error} networks in error state!")

>>> # Get health summary by type
>>> health = dashboard.get_health_summary()
>>> for net_type, counts in health.items():
...     print(f"{net_type}: {counts['online']}/{counts['count']}")

property users: UserManager

Access user operations.

property api_keys: APIKeyManager

Access API key operations.

property groups: GroupManager

Access group operations.

property permissions: PermissionManager

Access permission operations.

property clusters: ClusterManager

Access cluster operations.

property nodes: NodeManager

Access node operations.

property tasks: TaskManager

Access task operations.

property files: FileManager

Access file/media catalog operations.

property storage_tiers: StorageTierManager

Access storage tier operations.

property nas_services: NASServiceManager

Access NAS service operations.

property nas_volumes: NASVolumeManager

Access NAS volume operations.

property nas_volume_snapshots: NASVolumeSnapshotManager

Access NAS volume snapshot operations.

property cifs_shares: NASCIFSShareManager

Access NAS CIFS/SMB share operations.

property nfs_shares: NASNFSShareManager

Access NAS NFS share operations.

property nas_users: NASUserManager

Access NAS local user operations.

property volume_syncs: NASVolumeSyncManager

Access NAS volume sync operations.

property shared_objects: SharedObjectManager

Access shared object operations for tenant VM sharing.

property system: SystemManager

Access system operations (settings, statistics, licenses, inventory).

property sites: SiteManager

Access site operations for backup/DR remote site connections.

property site_syncs: SiteSyncOutgoingManager

Access outgoing site sync operations for backup/DR.

property site_syncs_incoming: SiteSyncIncomingManager

Access incoming site sync operations for backup/DR.

property site_sync_schedules: SiteSyncScheduleManager

Access site sync schedule operations for backup/DR.

property snapshot_profiles: SnapshotProfileManager

Access snapshot profile operations for backup/DR.

property cloud_snapshots: CloudSnapshotManager

Access cloud (system) snapshot operations for backup/DR.

property resource_groups: ResourceGroupManager

Access resource group operations for hardware device passthrough.

Resource groups define collections of hardware devices (GPU, PCI, USB, SR-IOV NIC, vGPU) that can be assigned to VMs.

property webhooks: WebhookManager

Access webhook operations for notification integrations.

Webhooks allow VergeOS to send notifications to external systems when events occur. Configure webhook URLs and view delivery history.

property cloudinit_files: CloudInitFileManager

Access cloud-init file operations for VM provisioning automation.

Cloud-init files provide user-data, meta-data, and other configuration to VMs during boot for automated provisioning.

property certificates: CertificateManager

Access SSL/TLS certificate operations.

Manage SSL/TLS certificates including manual uploads, Let’s Encrypt (ACME) certificates, and self-signed certificates.

property tags: TagManager

Access tag operations for resource organization.

Tags provide a flexible way to categorize and organize resources like VMs, networks, and tenants. Tags are organized within categories.

Example

>>> # List all tags
>>> for tag in client.tags.list():
...     print(f"{tag.name} (Category: {tag.category_name})")

>>> # Create a tag
>>> tag = client.tags.create(
...     name="Production",
...     category_key=1,
...     description="Production resources"
... )

>>> # Tag a VM
>>> client.tags.members(tag.key).add_vm(vm.key)

property tag_categories: TagCategoryManager

Access tag category operations for organizing tags.

Tag categories organize tags and define which resource types can be tagged with tags in each category.

Example

>>> # List all categories
>>> for cat in client.tag_categories.list():
...     print(f"{cat.name}: {cat.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
... )

property vm_imports: VmImportManager

Access VM import operations for importing VMs from files.

VM imports allow importing virtual machines from various formats including VMDK, QCOW2, OVA, and OVF files.

Example

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

>>> # 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}")

property vm_import_logs: VmImportLogManager

Access VM import log operations.

VM import logs provide detailed progress and error information for VM import operations.

Example

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

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

property volume_vm_exports: VolumeVmExportManager

Access volume VM export operations for exporting VMs to NAS volumes.

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.volume_name}: {exp.status}")

>>> # Create an export configuration
>>> exp = client.volume_vm_exports.create(
...     volume=123,
...     max_exports=5,
...     quiesced=True
... )

>>> # 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")

property volume_vm_export_stats: VolumeVmExportStatManager

Access volume VM export statistics.

VM export stats provide information about completed export operations including size, duration, and success/error counts.

Example

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

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

property vm_recipes: VmRecipeManager

Access VM recipe operations for automated VM provisioning.

VM recipes are templates that can be deployed to create new VMs with pre-configured settings and software.

Example

>>> # List all VM 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})

property vm_recipe_instances: VmRecipeInstanceManager

Access VM recipe instance operations.

VM recipe instances represent deployed VMs created from recipes.

Example

>>> # List all VM recipe instances
>>> for inst in client.vm_recipe_instances.list():
...     print(f"{inst.name}: {inst.version}")

>>> # List instances for a specific recipe
>>> insts = client.vm_recipe_instances.list(recipe="8f73f8bcc9...")

property vm_recipe_logs: VmRecipeLogManager

Access VM recipe log operations.

VM recipe logs provide detailed progress and error information for recipe operations.

Example

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

>>> # List errors only
>>> errors = client.vm_recipe_logs.list_errors()

property tenant_recipes: TenantRecipeManager

Access tenant recipe operations for automated tenant provisioning.

Tenant recipes are templates that can be deployed to create new tenants with pre-configured settings and resources.

Example

>>> # List all tenant 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})

property tenant_recipe_instances: TenantRecipeInstanceManager

Access tenant recipe instance operations.

Tenant recipe instances represent deployed tenants created from recipes.

Example

>>> # List all tenant recipe instances
>>> for inst in client.tenant_recipe_instances.list():
...     print(f"{inst.name}: {inst.version}")

>>> # List instances for a specific recipe
>>> insts = client.tenant_recipe_instances.list(recipe="8f73f8bcc9...")

property tenant_recipe_logs: TenantRecipeLogManager

Access tenant recipe log operations.

Tenant recipe logs provide detailed progress and error information for recipe operations.

Example

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

>>> # List errors only
>>> errors = client.tenant_recipe_logs.list_errors()

property recipe_questions: RecipeQuestionManager

Access 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/8f73f8bcc9..."
... )
>>> for q in questions:
...     print(f"{q.name}: {q.question_type}")

property recipe_sections: RecipeSectionManager

Access 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/8f73f8bcc9..."
... )
>>> for s in sections:
...     print(f"{s.name}: {s.description}")

property task_schedules: TaskScheduleManager

Access task schedule operations.

Task schedules define when scheduled tasks should run. They support various repeat intervals (minute, hour, day, week, month, year).

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="Nightly Backup",
...     repeat_every="day",
...     start_time_of_day=7200,  # 2 AM
... )

>>> # Get upcoming execution times
>>> times = schedule.get_schedule(max_results=10)

property task_schedule_triggers: TaskScheduleTriggerManager

Access task schedule trigger operations.

Task schedule triggers link tasks to schedules. When a schedule fires, all linked tasks are executed.

Example

>>> # List all triggers
>>> for trigger in client.task_schedule_triggers.list():
...     print(f"{trigger.task_display} -> {trigger.schedule_display}")

>>> # Link a task to a schedule
>>> 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)

property task_events: TaskEventManager

Access task event operations.

Task events enable event-driven automation by linking tasks to system events. When a specific event occurs on a resource, linked tasks execute.

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 VMs only
>>> events = client.task_events.list(table="vms")

>>> # Manually trigger an event
>>> client.task_events.trigger(event.key, context={"key": "value"})

property task_scripts: TaskScriptManager

Access task script operations.

Task scripts are GCS (VergeOS scripting) code that can be executed as tasks. Scripts can define questions that are prompted when running.

Example

>>> # List all scripts
>>> for script in client.task_scripts.list():
...     print(f"{script.name}: {script.task_count} tasks")

>>> # Create a script
>>> script = client.task_scripts.create(
...     name="Cleanup Script",
...     script="log('Cleanup started')",
...     task_settings={"questions": []},
... )

>>> # Run a script
>>> result = script.run()

property catalog_repositories: CatalogRepositoryManager

Access catalog repository operations.

Catalog repositories define where catalogs and recipes are sourced from. Types include local, remote, git, and Verge.io marketplace.

Example

>>> # List all repositories
>>> for repo in client.catalog_repositories.list():
...     print(f"{repo.name} ({repo.type})")

>>> # Get the Verge.io marketplace
>>> marketplace = client.catalog_repositories.get(name="Verge.io Recipes")

>>> # Refresh a repository
>>> repo.refresh()

>>> # List catalogs in a repository
>>> for catalog in repo.catalogs.list():
...     print(f"  {catalog.name}")

property catalogs: CatalogManager

Access 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")

property catalog_logs: CatalogLogManager

Access catalog log operations.

Catalog logs provide activity history for catalog operations.

Example

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

>>> # List errors only
>>> errors = client.catalog_logs.list_errors()

property catalog_repository_logs: CatalogRepositoryLogManager

Access catalog repository log operations.

Repository logs provide activity history for repository operations including refresh, download, and sync activities.

Example

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

>>> # List errors only
>>> errors = client.catalog_repository_logs.list_errors()

property catalog_repository_status: CatalogRepositoryStatusManager

Access catalog repository status operations.

Repository status provides current operational state information.

Example

>>> # List all repository statuses
>>> 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)

property vgpu_profiles: NvidiaVgpuProfileManager

Access NVIDIA vGPU profile operations.

vGPU profiles define the characteristics of virtual GPUs that can be created. Profiles are read-only and determined by NVIDIA drivers and available hardware.

Example

>>> # List all vGPU profiles
>>> for profile in client.vgpu_profiles.list():
...     print(f"{profile.name}: {profile.framebuffer}")

>>> # List AI/ML profiles only
>>> ml_profiles = client.vgpu_profiles.list(profile_type="C")

>>> # Get a specific profile
>>> profile = client.vgpu_profiles.get(name="nvidia-256")

property oidc_applications: OidcApplicationManager

Access OIDC application operations 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.

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}")

>>> # Restrict access to specific users
>>> app = client.oidc_applications.update(app.key, restrict_access=True)
>>> app.allowed_users.add(user_key=123)

property oidc_application_users: OidcApplicationUserManager

Access OIDC application user ACL operations.

User ACLs define which users can use an OIDC application when restrict_access is enabled.

Example

>>> # List all user ACL entries
>>> for entry in client.oidc_application_users.list(oidc_application=1):
...     print(f"{entry.user_display}")

property oidc_application_groups: OidcApplicationGroupManager

Access OIDC application group ACL operations.

Group ACLs define which groups can use an OIDC application when restrict_access is enabled.

Example

>>> # List all group ACL entries
>>> for entry in client.oidc_application_groups.list(oidc_application=1):
...     print(f"{entry.group_display}")

property oidc_application_logs: OidcApplicationLogManager

Access OIDC application audit log operations.

Logs provide activity history for OIDC application operations.

Example

>>> # List logs for an application
>>> for log in client.oidc_application_logs.list(oidc_application=1):
...     print(f"{log.level}: {log.text}")

>>> # List errors only
>>> errors = client.oidc_application_logs.list(
...     filter="(level eq 'error') or (level eq 'critical')"
... )

property update_settings: UpdateSettingsManager

Access update settings for system update configuration.

Update settings is a singleton that controls how the system handles software updates including auto-check, auto-update, scheduled times, and snapshot behavior.

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 and install updates
>>> client.update_settings.download()
>>> 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,
... )

property update_sources: UpdateSourceManager

Access update source operations.

Update sources define where updates come from (Verge.io update servers). Most systems have one or two sources configured.

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_key)

>>> # Check source status
>>> status = source.get_status()
>>> print(f"Status: {status.status}")

property update_branches: UpdateBranchManager

Access update branch operations.

Update branches define version streams (e.g., stable-4.13). 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
>>> settings = client.update_settings.get()
>>> branch = client.update_branches.get(settings.branch_key)

property update_packages: UpdatePackageManager

Access 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")

property update_source_packages: UpdateSourcePackageManager

Access update source package operations.

Source packages represent what’s available from an update source for a specific branch, including download status.

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 not yet downloaded
>>> pending = client.update_source_packages.list_pending()

property update_source_status: UpdateSourceStatusManager

Access update source status operations.

Source status provides the current operational state of update sources (idle, refreshing, downloading, installing, applying, error).

Example

>>> # Get status for the active source
>>> settings = client.update_settings.get()
>>> status = client.update_source_status.get_for_source(settings.source_key)
>>> print(f"Status: {status.status}")

>>> # Check if update is in progress
>>> if status.is_busy:
...     print("Update in progress...")

property update_logs: UpdateLogManager

Access 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()

property update_dashboard: UpdateDashboardManager

Access update dashboard for aggregated update information.

The update dashboard provides a consolidated 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')}")

Connection

Connection and session management for VergeOS API.

class pyvergeos.connection.AuthMethod

Bases: Enum

Authentication methods supported by VergeOS API.

BASIC = 'basic'

TOKEN = 'token'

class pyvergeos.connection.VergeConnection

Bases: object

Manages connection state to a VergeOS system.

host

VergeOS hostname or IP address.

Type:

str

username

Username for authentication.

Type:

str

api_base_url

Computed API base URL.

Type:

str

token

Authentication token (Basic or Bearer).

Type:

str | None

token_expires

Token expiration time (if applicable).

Type:

datetime.datetime | None

verify_ssl

Whether to verify SSL certificates.

Type:

bool

retry_total

Number of retry attempts for transient failures.

Type:

int

retry_backoff_factor

Backoff factor for retry delay calculation.

Type:

float

retry_status_codes

HTTP status codes that trigger automatic retry.

Type:

collections.abc.Iterable[int]

connected_at

Timestamp when connection was established.

Type:

datetime.datetime | None

vergeos_version

VergeOS version from system endpoint.

Type:

str | None

is_connected

Whether connection is active.

Type:

bool

host: str

username: str = ''

api_base_url: str

token: str | None = None

token_expires: datetime | None = None

verify_ssl: bool = True

retry_total: int = 3

retry_backoff_factor: float = 1

retry_status_codes: Iterable[int] = frozenset({HTTPStatus.TOO_MANY_REQUESTS, HTTPStatus.INTERNAL_SERVER_ERROR, HTTPStatus.BAD_GATEWAY, HTTPStatus.SERVICE_UNAVAILABLE, HTTPStatus.GATEWAY_TIMEOUT})

connected_at: datetime | None = None

vergeos_version: str | None = None

os_version: str | None = None

cloud_name: str | None = None

is_connected: bool = False

is_token_valid()

Check if the current token/credentials are valid.

Returns:

True if connected and token not expired.

Return type:

bool

disconnect()

Clear connection state and close the HTTP session.

Resets all authentication and connection state including token, expiration time, and connection timestamp. The underlying requests session is also closed to release network resources.

Note

After calling disconnect(), the connection object can be reused by establishing a new connection through the client.

Return type:

None

__init__(host, username='', token=None, token_expires=None, verify_ssl=True, retry_total=3, retry_backoff_factor=1, retry_status_codes=frozenset({HTTPStatus.TOO_MANY_REQUESTS, HTTPStatus.INTERNAL_SERVER_ERROR, HTTPStatus.BAD_GATEWAY, HTTPStatus.SERVICE_UNAVAILABLE, HTTPStatus.GATEWAY_TIMEOUT}), connected_at=None, vergeos_version=None, os_version=None, cloud_name=None, is_connected=False, _session=None)

Parameters:

• host (str)

• username (str)

• token (str | None)

• token_expires (datetime | None)

• verify_ssl (bool)

• retry_total (int)

• retry_backoff_factor (float)

• retry_status_codes (Iterable[int])

• connected_at (datetime | None)

• vergeos_version (str | None)

• os_version (str | None)

• cloud_name (str | None)

• is_connected (bool)

• _session (Session | None)

Return type:

None

pyvergeos.connection.build_auth_header(method, username=None, password=None, token=None)

Build the Authorization header based on auth method.

Parameters:

• method (AuthMethod) – Authentication method to use.

• username (str | None) – Username for basic auth.

• password (str | None) – Password for basic auth.

• token (str | None) – API token for token auth.

Returns:

Dictionary with Authorization header.

Raises:

ValueError – If required credentials not provided.

Return type:

dict[str, str]