Changelog
All notable changes to pyvergeos will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
[1.7.1] - 2026-09-27
Upgrading from 1.6.1
Most of this release is fixes, but four of them change what a caller sees. Check for these before you upgrade:
LicenseManager.generate_payload()returnsbytes, notstr. Write the result in binary mode. (#184)skip_missedis gone from snapshot profile periods.periods.create()andSnapshotProfile.add_period()raiseTypeErrorif you pass it, andupdate()andsave()raiseValueError. (#139)ResourceRule.resource_group_keyandDevice.resource_group_keyreturn the resource group UUID as astr. They used to raise on every real row, so nothing could have depended on the old type. (#151)A manager handed out by a parent, such as
network.rules,tenant.nodesorvm.drives, raisesNotFoundErrorfor a key that belongs to a different parent. It used to act on that row. (#168, #182, #188)
Added
auth_sources.update(..., merge_settings=True)gives the merge semantics the docstring used to promise: the SDK reads the current document withget(key, include_settings=True), shallow-merges your keys on top, and writes the result back, so changingscopealone keeps the client credentials. It requiressettings(raisingValueErrorotherwise), costs one extra API call, and is read-modify-write rather than atomic – a concurrent write landing between the read and the write is lost. The default remainsFalse, preserving replace semantics for existing callers. (#142)
Fixed
Managers handed out by a parent now refuse another parent’s rows. That covers network rules, aliases and hosts, DNS views, zones and records, WireGuard interfaces and peers, IPsec connections and policies, proxies, tenant nodes, storage, snapshots, network blocks, external IPs and Layer 2 networks, volume and NAS service antivirus, resource group rules, task events and triggers, and OIDC allowed users and groups. They used to
get,updateordeletea row by key even when it belonged to a different parent. They now read the row’s parent column first and raiseNotFoundErrorbefore anything is written. Code that passed another parent’s key has to use that parent’s manager instead. (#188)IPSecConnectionManagerscopes phase 1 rows by theiripsecconfig, not by avnetcolumn thevnet_ipsec_phase1stable does not have.create(),get(key),update(key)anddelete(key)on the network’s own connections work again. A connection whose config belongs to another network is still refused before any write. A scopedget(key)with nofieldsprojects the manager’s default fields plus its scope columns, soWireGuardPeerStatusManager,IPSecActiveConnectionManager,VolumeAntivirusInfectionManagerandVolumeAntivirusLogManageraccept their own rows. An unprojected read on VergeOS 26.1.8 returns a short set that often omits the parent column. (#191)LicenseManager.generate_payload()returns the license request as bytes.license_actionsgeneratewrites a binary.lrqinto the media catalog and returns a file reference (filekey,filename); the method used tojson.dumpsthat reference (~155 characters) and leave a new catalog file on every call. The method now downloads the.lrqthrough the files manager and returns the raw bytes. Lab files are not UTF-8 text (they start with8a3a0000), so decoding them raisedAPIErrorand skipped the catalog delete. By default the catalog copy is deleted after a successful read. Passdelete_catalog_file=Falseto keep the file. An empty or missing file is still an error and is left in the catalog. On VergeOS 26.1.8 the reference looks like{"response": {"filekey": "files/76", "filename": "license-request-….lrq", ...}}. (#184)DeviceManagerandVMCloudInitFileManagerrequire the row to belong to the VM on by-key calls. Devices comparemachinewith the VM machine key. Cloud-init files compareownerwithvms/<vm key>.get(key),update(key),delete(key), andget_content(key)raiseNotFoundErrorwhen the key belongs to another VM, before a write or before file contents are returned.list()was already filtered. (#182)VolumeAntivirusManager.create()no longer fails withConflictErrorwhen the volume already has an antivirus row. VergeOS creates that row with the volume, and the table allows one row per volume, so a POST always hit the unique constraint.create()updates the existing row, including when a POST races and returns 409. Examples lead withget()andupdate(). Measured on VergeOS 26.1.8. (#170)NasServiceAntivirusManager.list()honours its service scope.nas_service.antivirus.list()returned every NAS service’s antivirus config, not just that service’s. The antivirus docstrings no longer mentionclient.volume_antivirus, which does not exist. (#152)VM.hotplug_drive()raisesValueErrorbefore creating a drive whenmediais notdiskorinterfaceis notvirtioorvirtio-scsi. VergeOS hot plugs only those disks. ide, ahci, nvme, and media that is not a disk were created and then refused, leaving an offline drive that came online on the next boot. Ifhotplugdriveorhotplugnicis still rejected after the device is created (for example the VM is not running yet), the drive or NIC from that call is deleted and the API error is raised again. Measured on VergeOS 26.1.8. (#169)VMSnapshotManager.restore(..., power_on=True)andVMSnapshot.restore(power_on=True)power the restored VM on. Clone mode reads the new VM key fromresponse.vmkey(VergeOS returns{"response": {"vmkey": "..."}}) and still accepts top level$keyorkey. In place restore (replace_original=True) powers on the original VM even when the action body is empty. A failed power on POST is raised instead of ignored. (#172)VMSnapshotManager,DriveManager, andNICManagerrequire the row’smachineto equal the VM inget(key).update(key),delete(key), andVMSnapshotManager.restore(key)use that check and raiseNotFoundErrorwhen the key belongs to another VM, before sending a write.list()was already filtered by machine. (#168)NetworkAlias,NetworkAliasManager, andNetworkAliasManager.create()describe router IP aliases (vnet_addressesrows withtype: ipalias): extra addresses on the network’s router. They are not thevnet_rule_aliasesthat a firewall rule’salias:<name>syntax resolves. This SDK has no manager forvnet_rule_aliasesyet. Measured on VergeOS 26.1.8. (#155)TaskScriptManager.delete()documents that deleting a script also deletes its associated tasks. The previous note said scripts with associated tasks cannot be deleted, which the platform does not enforce. Measured on VergeOS 26.1.8. (#155)TagCategory.delete()andTagCategoryManager.delete()document that deleting a category also deletes every tag in it and every assignment of those tags. VergeOS does not require the category to be empty;DELETE tag_categories/<key>cascades. The previous notes said to delete tags first, which read as a refusal the platform does not enforce. Measured on VergeOS 26.1.8. (#154)ResourceRule.resource_group_keyandDevice.resource_group_keyreturn the resource group UUID asstr | None. Both properties calledint()onresource_group, which raisedValueErrorfor every real rule because resource groups are keyed by UUID. (#151)SnapshotProfilePeriodManager.create(),update()/save(), andSnapshotProfile.add_period()no longer acceptskip_missed.snapshot_profile_periodshas no such column; VergeOS accepts the name and drops it, so the write looked successful andSnapshotProfilePeriod.skip_missedalways read false. The property and the default field list drop it too. Passing it toupdate()orsave()raisesValueError. The other period write fields match columns measured on VergeOS 26.1.8. (#139)VM.hotplug_drive()andVM.hotplug_nic()sent the create spec (name,disksize,interface, and so on) as the action params. VergeOShotplugdriveandhotplugnicattach an existing device and require its key asdevice, so both raisedValidationError: Device is a required parameter. Each method now creates the drive or NIC, then posts the action withparams: {"device": <key>}.hotplug_drive(size=...)still takes bytes and must be a positive whole number of GiB, because the drive is created throughdrives.create(size_gb=...). Measured on VergeOS 26.1.8. (#150)ClusterTier.get_status()readcapacity,used,used_pct,redundant,encryptedandworkingas the string'online'.get_tier_status()expanded those columns throughClusterTier’sstatus#joins, and oncluster_tier_statusstatusis a plain string, so every join came back as'online'.capacity_bytes,used_bytesandused_percentthen raisedValueError, and the redundancy flags were truthy strings. Status, stats and history queries now project the columns of the endpoint they call. (#149)VMSnapshotManager.create(retention=0)now sendsexpires: 0so the platform stores a never-expiring snapshot. Omittingexpirespreviously let VergeOS default to +72 hours, contradicting the documented “use 0 for never expires” behaviour (andVMSnapshot.never_expires, which already treatedexpires == 0as never). Measured on VergeOS 26.1.8. (#146)VMSnapshotManager.create()rejects a negativeretention(andNone) instead of storingexpires: 0. Omittingretentionstill defaults to 24 hours. (#146)VMSnapshot.restore()now delegates toVMSnapshotManager.restore(), which resolvessnap_machine(a machine key) to the snapshot VM before posting tovm_actions. The object method previously posted the machine key as a VM key, which raisedNotFoundErrorand could clone the wrong VM if keys later collided. (#147)PhysicalDriveManagernode scoping no longer filters on a nonexistentnodecolumn (which silently returned[]for every node). It now resolvesnodes.machine→machine_drives→parent_drivefilters, raisesNotFoundErrorfor a missing node, and projectsparent_drive#machine#name as node_namein the default field set so identical hardware across nodes is distinguishable. Verified against a live VergeOS 26.1.8 lab. (#143)auth_sources.update()no longer claims thatsettingsare “merged with existing”. They are not: the API replaces the stored settings document wholesale, so a partial write deletes every key it omits. Measured on VergeOS 26.1.8, updating a source withsettings={"scope": "openid"}leaves exactly that one key behind –client_id,client_secretand the endpoints are gone, no error is raised, and the next SSO login simply fails. The client secret usually cannot be read back from the identity provider, so the configuration has to be rebuilt by hand.Anyone following the old docstring to change one field was destroying a working SSO configuration. The docstring now says the document is replaced in full and that omitted keys are deleted, and the manager and module examples no longer demonstrate the partial write that causes it. Behaviour is unchanged – this was always what the API did. (#142)
Docs
AuthSource.settingsdocuments that the server injects adebugkey into the stored document that was never sent, so a round-trip comparison against what you wrote reports drift that is not there, and that the property is only populated when the source was fetched withinclude_settings=True. (#142)
[1.6.1] - 2026-09-23
Fixed
cloud_snapshots.create(wait=True)now actually waits. Snapshot creation is not backed by a task row – the POST response carries notaskkey and the row’staskfield stays null – so the old code, which waited only when a task key was present, never waited at all:wait=Truereturned immediately with a snapshot stillbuildingand a stalestatus. It now polls the snapshot row until it reports a settled status – reading the raw field so a not-yet-populated status right after the POST is treated as still in progress rather than defaulting tonormaland returning early – honouringwait_timeout(raisingVergeTimeoutErroron expiry) and returning the snapshot fetched fresh, so itsstatusreflects reality.wait=Falsebehaviour is unchanged. (#133)
Docs
ClusterStatus.can_lose_one_node()no longer describes itself as “conservative”. It dividesonline_ramevenly acrossonline_nodes, but the real worst case is losing the largest node, so on a cluster of unequal nodes it errs toward True, in the unsafe direction, which is the opposite of what “conservative” promises. Two nodes of 68352 and 69120 MB give an even-spread ceiling of 68736 MB while only 68352 MB survives losing the larger one, so anyused_ramin between reported True for a load the survivor could not hold.This is a wording fix, not a logic change:
cluster_statusexposes only aggregates, so the method cannot compute a worst case from its own data and even-spread is the best available at that layer. The docstring now states that it is an optimistic approximation, that a True is not an N-1 guarantee on unevenly sized clusters, and shows the per-node recipe overNode.vm_ram_mbfor callers gating a real drain. Two tests pin the optimistic window so the behaviour and the caveat cannot drift apart. The 1.5.0 entry above was corrected to match. (#135)
[1.6.0] - 2026-09-23
Added
cloud_snapshots.create()can now takeinclude_tags,exclude_tagsandquiesce_tagsto create a partial (tag-scoped) system snapshot – capture only, or all-but, the VMs carrying the given tags, a VergeOS 26.1 feature that was previously unreachable from the SDK. Tags may be given as a$key, a name, or a Tag object; names are resolved to keys (an ambiguous name raises rather than guessing, since names are unique only within a category).include_tagsandexclude_tagsare mutually exclusive, andquiesce_tagsrequires one of them. A create with none of these is a full snapshot exactly as before. (#129)
[1.5.0] - 2026-09-23
Added
cluster_statusmanager (client.cluster_statusand, scoped,cluster.cluster_status) exposing thecluster_statustable – the live per-cluster node/RAM/core capacity figures behind an N-1 capacity pre-check. Previously reachable only through a privateclient._request().ClusterStatus.can_lose_one_node()provides an even-spread approximation. (#127, wording corrected in 1.6.1 per #135)machine_drive_statsmanager (client.machine_drive_statsand, scoped,drive.drive_stats) exposing per-drive IO counters. It addresses rows by a filter onparent_drive; path-key access (machine_drive_stats/<n>) returns the row whose own$keyisn, which belongs to a different drive, and previously reported another drive’s counters – e.g. writes on a VM that had never booted.MachineDriveStats.has_bootedreports whether the guest has issued disk writes, the reliable signal that it actually booted rather than merely powering on. (#128)
Notes
The
machine_nic_statsmanager referenced in #128 already existed; onlymachine_drive_statswas missing. Both scoped stats managers now defaultlist()to their projection, so a barelist()returns populated rows rather than only$key.
[1.4.0] - 2026-09-23
Added
Projected, a descriptor that declares an accessor and the projection entry that feeds it in one place, plusResourceObject.projected_entries()so a manager derives its default projection from those declarations instead of restating them. Adding an accessor now adds its field to every query that reads it. See Contributing. (#125)display_map()andepoch_utc()transforms, andsplit_reference()/reference_key()/reference_table()for reading"table/key"references. (#125, #126)Task.owner_tablewas already present;TaskEvent.owner_keynow reports the key it previously discarded. (#126)
Fixed
Four accessors declared
-> intcoerced withint()on columns that hold a polymorphic reference ("vms/39"), a name-keyed reference ("vm_recipes/winbind-v1") or a plain non-numeric value ("deprecated",""). Reading them raisedValueErroron ordinary rows, so iterating alarms or tasks crashed on the first one:for alarm in client.alarms.list(): print(alarm.owner_key) # ValueError before this release
alarms.owner_key,alarms.alarm_type_key,alarms.sub_owner,tasks.owner_key,tasks.creator_keyandtask_schedules.creator_keynow report the key part of the reference.task_events.owner_keyreturnedNonefor these rather than raising, discarding the key; it now reports it. (#126)
Changed
Type change. The accessors above widen from
int | Nonetostr | int | None, because a VergeOS key is not always numeric. Numeric references are unaffected –39and"27"still read asint– and an absent column still reads asNone. Only values that previously raised behave differently. (#126)Every accessor for a computed field is now declared with
Projectedrather than written by hand. This is a refactor: behaviour is unchanged, verified by comparing each accessor against the implementation it replaced across present, null, empty, falsy, absent-but-requested and never-requested values, and by checking that every manager’s projection is unchanged in content. (#125)Contributors adding an accessor should read the new section in Contributing; a test enforces that no
@propertycallsrequire_projected.
[1.3.0] - 2026-09-23
Added
FieldNotProjectedError, raised when an accessor is asked for a field the request never fetched. Exported frompyvergeosand documented in Error Handling. It is deliberately not anAttributeError, sogetattr(vm, "is_running", None)andhasattr(vm, "is_running")propagate it rather than quietly answeringNone/False; anAttributeErrorsubclass would be swallowed byResourceObject’s dict attribute fallback. Use"running" in vmfor a non-raising check. (#117)
Changed
Behaviour change. An accessor whose backing field was not fetched now raises
FieldNotProjectedErrorinstead of returningFalse,"",0or"unknown". This affects callers that narrowfieldsand then readis_running,status,member_countand similar: they previously received a silently wrong answer.A wrong answer in this direction is the dangerous one -
is_runningis exactly the guard placed in front of a destructive operation, and a storage tier reported as"Offline"with zero capacity invites action on a healthy tier.No signatures changed, and the default projection is unaffected. To get a usable answer, use the manager’s default fields, pass
fields=["all"], or name the field - all three now agree:vm = client.vms.get(name="web-01") vm = client.vms.get(name="web-01", fields=["all"]) vm = client.vms.get(name="web-01", fields=["$key", "running"])
Accessors that can still answer from another fetched field keep their tolerant behaviour -
device_type_displayfalls back to thedevice_typecolumn,size_gbtodisksize. (#117)Accessors declared
-> str | Nonenow return astr. Several returned whatever the API sent, sopermission.identity_nameanswered the integer1where its own annotation promised text. Affects 32 accessors; compare against"1"rather than1. (#117)
Fixed
fields=["all"]is no longer a silently lossy projection.allresolves server-side to a resource’s own columns, so nothing the server computes came back with it: aliased traversals (machine#status#running as running), aggregates (count(members) as member_count) and sub-selections (stats[reads,writes]) alike, and onnodesandstorage_tiersnot even$key. A running VM read back underallreportedis_running is False, andnode.keyraised “Resource has no $key” for a plainly persisted node.allis now expanded with the manager’s computed entries and$key. (#117)Naming a field no longer selects the wrong one.
fields=["$key", "name", "running"]selected thevmstable’s ownrunningcolumn, which is null on every row, sois_runningansweredFalsefor a running VM. A projection entry matching one of the manager’s alias names now resolves to the manager’s entry for it. Narrowing is still honoured and is never widened. (#117)An object built from a write response no longer inherits the projection of whatever the manager last queried.
POSTanswers with a receipt andPUTwith{}, sonetworks.list()followed bynetworks.update(...)produced an object that answeredis_runningasFalsefrom a row that never containedrunning- an answer that depended on unrelated earlier calls. (#117)refresh()adopts the refetched projection, so a refreshed object no longer disagrees with an identically fetched one. (#117)A field the server omits because a polymorphic reference is null - such as
creator#$displayon a task with no creator - is reported as its default rather than as unfetched. Absence alone is not proof that a field was not requested. (#117)
[1.2.8] - 2026-09-22
Fixed
fields="$key,name"no longer silently destroys the projection.fieldswas typed as a list but every call site serialised it with",".join(fields); a caller-supplied string - the API’s own native format - was joined character by character ('$,k,e,y,,,n,a,m,e'), which the API accepted and answered with rows containing no usable fields. All 272 call sites now serialise throughnormalize_fields(), which accepts a list of names or a comma-separated string, and thefieldssignatures were widened to match. The same footgun corrupted write-path sequence parameters (ip_allow_list/ip_deny_liston API keys,valid_users/valid_groups/admin_users/admin_groups/allowed_hosts/denied_hostson CIFS shares,include/excludeon volume syncs,dns_serverson networks); those now serialise throughserialize_list(), which passes strings through unchanged. An AST tripwire test fails CI if any function joins a caller-supplied parameter directly. (#101)The
namesearch intasks,task_scripts,task_schedulesandcloudinit_filesno longer fails open for all-wildcard patterns. These managers carried a hand-rolled workaround that stripped*/?and used actcontains match; a name of"*"(or"?") stripped to an empty search term and appended no condition at all, returning every row - the fail-open shape of #96 - andname="Backup*"matched as a case-insensitive contains (also matchingNightly Backup). All four now share the wildcard translation, so prefix patterns match prefixes, matching is case-sensitive, and a condition is always sent. Ported from the parallel fix in PR #104. (#103)Wildcard and list filter shorthands no longer emit operators VergeOS rejects.
build_filter()andFilterproducedlike(fromname="web*") andin(fromstatus=[...]), neither of which is in the platform’s filter grammar - every such filter failed with HTTP 422 “Invalid argument”. Wildcards now translate to supported operators (foo*->bw,*foo->ew,*foo*->cs, complex patterns -> anchored POSIX-ERErxwith metacharacters escaped), and lists expand to a parenthesizedorchain of conditions - parenthesized because the platform evaluatesand/orstrictly left-to-right with no precedence. Wildcard matching is case-sensitive, consistent witheq. (#103)list()no longer returns every row when a filter cannot be applied. Shorthand filter kwargs were silently dropped whenever a manager supplied its ownfilterstring, soclient.vms.list(name=...)ignored the name and returned every non-snapshot VM - making the ordinary cleanup idiomfor v in client.vms.list(name=missing): client.vms.delete(...)a destructive operation. A newcombine_filters()helper merges both forms as(filter) and (built), and the 33 managerlist()overrides that documented**kwargsas “additional filter arguments” without ever reading them now merge those kwargs into the filter they send. (#96)drive.tier = 2; drive.save()is no longer a silent no-op.ResourceObject._save()sends locally modified fields as a raw PUT that bypasses the typedupdate(), so thetier->preferred_tiertranslation added in #81 was skipped and VergeOS accepted the rawtierfield with HTTP 200 and ignored it. A newResourceManager._prepare_write_fields()hook applies alias translation on every write path, so attribute assignment andupdate()behave identically:tier->preferred_tier(drives),network->vnet(NICs), emptycloudinit_datasource->"none"(VMs), and frequency/day validation plusmax_tiercoercion (snapshot profile periods). (#97)ResourceObject.refresh()now updates the object it is called on instead of returning a new one and leaving the receiver stale. The obvious wait loop (while not vm.running: vm.refresh()) converges as soon as the state changes rather than always running to its deadline.refresh()returnsself, sovm = vm.refresh()remains correct, and the 26 subclass overrides that existed only to narrow the return type were removed.SharedObject.refresh()gained the same in-place semantics;UpdateSource.refresh(), which triggers an update check, is unchanged. (#98)Iterating a scoped collection no longer returns zero rows.
iter_all()/__iter__passlimit/offsettolist(), and 19 overrides consumed them as**kwargsfilter arguments, producing filters such as(machine eq 55) and (limit eq 100 and offset eq 0)that matched nothing. Those overrides now declarelimit/offsetand send them as request parameters, so iteration works and pages server-side instead of re-fetching the full table. An AST-based guard test fails CI if a futurelist()override consumes**kwargswithout declaring them. (#102)A
fieldsstring containing no field names -","," ",",,,"- was passed through to the API, which answered with a single{"$count": N}row instead of the requested resources. Measured on VergeOS 26.1.8, a five-VM list collapsed to one meaningless row: the same silent-empty result #101 was filed for. Such values now mean “no projection requested”.normalize_fields()andsplit_fields()also clean field names identically, so the string and sequence forms are interchangeable ("$key,"and["$key", ""]now agree). A mapping, or a sequence containing a non-string, is rejected withTypeErrorrather than serialized into a plausible-looking but wrong projection. (#101)ResourceObject.update()andsetdefault()bypassed dirty tracking, soobj.update({...}); obj.save()reported success while persisting nothing - the fields were changed locally and an emptyPUTwas sent. Both now route through the tracked__setitem__, so a batch update behaves like a sequence of assignments.refresh()still bypasses tracking, as it loads server state rather than local edits. All 165 resource classes inherit the fix. (#110)save()with nothing to save no longer issues an emptyPUT. An empty write is still subject to permissions, audit logging and update side effects, for a request the caller did not make; current state is returned instead. (#111)OidcApplicationManager.create()failed on any system without auth source key 0 and user key 0 - that is, any normal system. Bothforce_auth_sourceandmap_userare required by the API but are resolved as row references, and the SDK coerced an unsupplied value fromNoneto0, which VergeOS rejects with HTTP 404error setting field ... No such file or directory.nullis the accepted “not set” value and is now sent, so creating an application with only a name works. Explicitly supplied keys are unaffected. (#107)Every multi-value write parameter (
ssh_keys,dns_servers,ip_allow_list,domain_list,redirect_uri, the NAS CIFS user and host lists, volume-syncinclude/exclude) rejects a mapping, an unordered collection and non-string values instead of serializing them. Iterating a mapping yields its keys, sossh_keys={"a": 1}was sent as'a'; asetwas joined in arbitrary order, and order is part of the value - the first entry ofdnslistis the primary DNS server. (#101)WebhookManager.update(headers="")stored a lone blank line instead of clearing the header block, whichheaders={}already did correctly. Both forms now clear it. (#101)CertificateManager.get()and.list()silently ignoredinclude_keyswhenever an explicitfieldsprojection was supplied, so the requested key material was missing from the result. The key fields are now appended to whatever projection was asked for, without duplicating entries, matchingAuthSourceManager.get(include_settings=...)andOidcApplicationManager.get(include_secret=...). (#101)Six
get()/list()methods still corrupted afieldsstring after the #101 sweep:auth_sources,certificates,cloudinit_files(list and get),oidc_applicationsandwebhooksbuild an augmented projection (addingsettings,client_secretand similar), so they aliased the parameter withlist(fields)before joining and bypassednormalize_fields().list("$key,name")splits into characters exactly as",".join()does. A newsplit_fields()helper returns the list form, and the AST tripwire now follows locals that alias a parameter, which is how the original guard missed these. (#101)Filter values are no longer interpolated straight into a quoted literal.
quote_value()exists so a caller-supplied value cannot be parsed as filter grammar, but 91 conditions across 40 modules never called it, writingf"key ct '{key_contains}'"instead. A value containing an apostrophe broke out of the literal and the remainder was evaluated as grammar: measured on a live system,settings.list(key_contains="zzzz' or key ne 'zzzz")returned all 68 rows instead of zero, and the same shape leaked whole tables fromtasks.list_by_action()andtask_events.list(). The #100 brace effect reached these sites too -key_contains="clou{x}"silently matchedclou- and a trailing backslash was rejected outright. This is not a privilege escalation: the injected condition runs with the caller’s own permissions. The damage is wrong rows, and since the standard pattern is look-up-by-name then act on the returned key, aget_by_*resolving to the wrong row can lead to modifying or deleting the wrong object. All 91 now route throughquote_value(); output is byte-identical for values with no reserved characters, so behaviour is unchanged otherwise. An AST tripwire fails CI if any filter condition interpolates a value directly inside'...'. (#115)quote_value()now escapes{, so a lookup by a name containing a brace no longer resolves to a different object. VergeOS reserves three characters inside a filter string literal -\\,'and{- and only the first two were escaped.{opens a balanced, nesting-aware construct, so a balanced{...}was consumed silently and the query matched whatever the stripped string named:get(name="br{x}ace")returned the unrelated rowbrace, and because the standard pattern is look-up-by-name then act on the returned key, a caller could update or delete an object it never asked for. An unbalanced{was merely rejected with HTTP 422. The reserved set was re-measured by sweeping all 95 printable ASCII characters against a live system and by round-tripping rows whose names contain each one;}is not reserved. Therxpath is fixed by the same change - a brace there carries both the POSIX-ERE escape and the literal escape, and the previous single escape matched nothing. A tripwire test now pins the reserved set and fails if any{can reach the wire unescaped. (#100)Network.power_off(force=True)no longer sends an action the platform rejects. It emittedaction="killpower", which is not in the vnet action list, so every forced power off of a network failed withValidationError: value 'killpower' is not in list for field 'action'- forced power off was simply unavailable through the SDK. The valid value iskill, the same value #42 applied to VMs; that fix was never carried across to networks, and the unit test asserted the broken string, so CI defended the bug. The_power_action()docstring advertisedkillpoweras well. A new AST tripwire scans every resource module, so a third occurrence cannot ship. (#112)
Changed
Filter kwargs whose values are all
None(for exampleclient.networks.list(name=None)) now raiseValueErrorinstead of producing an empty filter that matched every row. This matches the existing behaviour ofget(name=None). Filter kwargs that are only partlyNonestill filter on the non-Noneconditions. (#96)Invalid snapshot profile period fields now raise at
save()as well asupdate(), rather than being sent raw and silently ignored. (#97)An empty sequence passed as a filter value (
list(name=[])) now raisesValueErrorinstead of sendingin (), which the platform rejected with an opaque 422. (#103)
Added
Filtergained methods for the platform’s native string operators:bw()(begins-with),ew()(ends-with),cs()(contains, case-sensitive),ct()(contains, case-insensitive) andrx()(POSIX-ERE regex). (#103)
[1.2.7] - 2026-09-21
Added
UpdateSourceManager.run_preinstall_check()exposing the VergeOS 26.1 table-levelPOST /update_actions/runpreinstallcheckaction. Theinstallaction runs this check automatically; the method surfaces it directly as a convenience. (#68)
Fixed
DriveManager.update()now translatestierto the API’spreferred_tierfield (as a string), matchingcreate()andimport_drive(). Previously the rawtierfield was sent, which VergeOS accepted with HTTP 200 and silently ignored, so a drive could be placed on a tier at creation but never re-tiered.tier=Noneis dropped; explicitpreferred_tierpasses through unchanged. (#81)VMDriveManager.create()now rejectssize_gbforefidiskmedia. A caller-sized efidisk is created as a raw volume without the templated OVMF vars layout, so UEFI variables cannot persist andapply_universal_vars()fails withOperation not permitted(verified on VergeOS 26.1.8). Omit the size so the platform templates the vars store. Documented thatapply_universal_varsrequires the path-form invocation - the generic?action=form is accepted with HTTP 200 but is a silent no-op. (#68)
[1.2.6] - 2026-09-21
Fixed
ResourceObject.save()now sends fields modified via attribute or item assignment (vm.cpu_cores = 4; vm.save()). Previously only keyword arguments were transmitted, so thesetattr+save()pattern issued an emptyPUTand silently persisted nothing. Keyword arguments still take precedence over locally modified fields. (#80)System setting updates no longer send the read-only
keyfield, which the API rejected with HTTP 422 (field 'key' is readonly). Onlyvalueis transmitted. (#86)Accept an empty
cloudinit_datasourceas a disable alias in VM creation, updates, and explicitsave()arguments, consistent withset_cloudinit_datasource(). Requests send VergeOS’s valid"none"value; disabling delivery preserves files until callers explicitly delete them. (#82)
[1.2.5] - 2026-09-11
Added
Added
vm_recipe_instances.simulate()to return recipe practice-run reports containing rendered cloud-init files, logs, and resolved answers. The helper recognizes VergeOS’s HTTP 405Simulation completeresponse without creating a persistent instance.create()also acceptssimulateandverifyflags.
Fixed
Recognize native group membership references such as
users/1andgroups/3, as well as prefixed references. Membership types and keys now resolve correctly, allowing removal helpers to find native memberships. Stored references are unchanged.Preserve the complete JSON error body in
APIError.response_bodyand all subclasses, including the generic VergeOSresponsepayload. Non-JSON error responses retain their raw text; error messages and status codes remain available.Fixed resource lookups and generated filters containing apostrophes or backslashes, including NAS paths and related-resource name resolution. Shared
quote_value()now uses VergeOS backslash escaping instead of SQL quote doubling. Rawfilter=expressions remain caller-controlled.
[1.2.4] - 2026-09-10
Added
Added
Drive.ms_2023_kek_appliedandDrive.apply_universal_vars()/DriveManager.apply_universal_vars()for Microsoft 2023 Secure Boot key status and application on EFI disks.Added
TagandTagCategorylog object-type mappings.
[1.2.3] - 2026-05-21
Added
Added
session=andclose_session=kwargs toVergeClientfor caller-managedrequests.Sessionsupport.
Changed
VergeConnectionnow exposes its session as the publicsessionfield. The previous private_sessionattribute has been removed.Caller-supplied sessions are not closed by default on disconnect, and VergeOS auth/content headers are restored to their pre-connect values.
Retry and
verify_sslconnection options are ignored with a warning when a caller-supplied session is used; configure those behaviors on the supplied session instead.Caller-supplied sessions must not be shared by multiple active
VergeClientinstances because authentication is stored in session headers while connected.close_session=Falsenow requires a caller-supplied session to avoid leaking SDK-created connection pools.
[1.0.0] - 2026-02-01
First stable release with full API coverage for VergeOS 26.0+.
Added
Core Automation (Phase 1)
VM Import/Export System
VmImportManager- Import VMs from VMDK, QCOW2, OVA, OVF formatsVmImportLogManager- Track import progress and errorsVolumeVmExportManager- Export VMs to NAS volumes for backupVolumeVmExportStatManager- Monitor export progress
Recipe/Provisioning System
VmRecipeManager- VM recipe templatesVmRecipeInstanceManager- Deployed VM instances from recipesVmRecipeLogManager- Recipe deployment logsTenantRecipeManager- Tenant recipe templatesTenantRecipeInstanceManager- Deployed tenant instancesTenantRecipeLogManager- Tenant recipe deployment logsRecipeQuestionManager- Recipe configuration questionsRecipeSectionManager- Recipe form sections
Task Scheduling System
TaskScheduleManager- Cron-style schedule definitionsTaskScheduleTriggerManager- Schedule triggers for tasksTaskEventManager- Event definitions for task triggersTaskScriptManager- Task script managementEnhanced
TaskManagerwith full CRUD operations
Catalog Management
CatalogRepositoryManager- Repository sources (local, remote, git)CatalogManager- Catalog entriesCatalogRepositoryStatusManager- Repository sync statusCatalogLogManager- Catalog activity logs
Enterprise Networking (Phase 2)
Network Routing Protocols
NetworkRoutingManager- Entry point vianetwork.routingBgpRouterManager- BGP router configurationBgpInterfaceManager- BGP interface configurationBgpRouteMapManager- BGP route mapsBgpIpCommandManager- BGP prefix-lists and AS-path access-listsOspfCommandManager- OSPF protocol commandsEigrpRouterManager- EIGRP router configuration
Tenant Proxy
VnetProxyManager- Reverse proxy service configurationVnetProxyTenantManager- Tenant FQDN mappings
Infrastructure Monitoring (Phase 3)
Machine Stats & Monitoring
MachineStatsManager- Real-time VM/node performance metricsMachineStatsHistory- Historical metrics (short-term and long-term)MachineStatusManager- VM/node operational statusMachineLogManager- VM/node-specific logsMachineDeviceManager- GPU, TPM, USB device management
GPU/vGPU Management
NvidiaVgpuProfileManager- Available vGPU profilesNodeVgpuDeviceManager- Physical vGPU devicesNodeVgpuProfileManager- Node-specific vGPU profilesNodeGpuManager- Physical GPU configurationNodeGpuStatsManager- GPU utilization metrics with historyNodeGpuInstanceManager- GPU instances assigned to VMsNodeHostGpuDeviceManager- Host GPU devices for passthrough
Cluster Tier Management
ClusterTierManager- Storage tier managementClusterTierStatus- Tier health statusClusterTierStats- Tier I/O performance metrics
Tenant Stats & Monitoring
TenantStatsManager- Tenant resource utilizationTenantStatsHistory- Historical tenant metricsTenantDashboardManager- Aggregated tenant overviewTenantLogManager- Tenant activity logging
Billing System
BillingManager- Resource usage tracking and billing reportsTime-based filtering with datetime or epoch timestamps
Summary statistics with averages and peak values
Existing Resource Enhancements (Phase 4)
VM Enhancements
migrate()- Live migrate VM to another nodehibernate()- Hibernate VM to diskchange_cd()- Change CD/DVD mediarestore()- Restore from snapshothotplug_drive()- Hot-add drive to running VMhotplug_nic()- Hot-add NIC to running VMtag()/untag()- Tag managementfavorite()/unfavorite()- VM favorites
Network Enhancements
NetworkMonitorStatsManager- Network performance monitoringNetworkDashboardManager- Network topology discoveryIPSecActiveConnectionManager- IPSec connection trackingWireGuardPeerStatusManager- WireGuard peer status
Site Sync Enhancements
SiteSyncQueueManager- Sync queue managementSiteSyncRemoteSnapManager- Remote snapshot visibilitySiteSyncIncomingVerifiedManager- Verified incoming syncsSiteSyncStatsManager- Sync performance metrics
Authentication & Security (Phase 5)
Authentication Sources
AuthSourceManager- External auth providers (OAuth2, OIDC, Azure AD, Okta)AuthSourceStateManager- Auth source connection state
OIDC Applications
OidcApplicationManager- Use VergeOS as identity providerOidcApplicationUserManager- User ACLs for OIDC appsOidcApplicationGroupManager- Group ACLs for OIDC appsOidcApplicationLogManager- OIDC application logs
Update Management
UpdateSettingsManager- Update configurationUpdateSourceManager- Update source managementUpdateBranchManager- Available update branchesUpdatePackageManager- Available packagesUpdateDashboardManager- Update status dashboardUpdateLogManager- Update history
Documentation (Phase 6)
Sphinx documentation with autodoc API reference
Tutorials for VM import/export, recipes, task scheduling, routing, GPU passthrough
Migration guide from direct API calls
Troubleshooting guide
25 example scripts covering major use cases
Changed
Minimum VergeOS version requirement: 26.0+
Test coverage increased to 83% (3,686+ tests)
All resource managers now export type-safe model classes
Improved error messages with actionable context
Fixed
Consistent retry behavior across all HTTP methods
Proper handling of 40-character hex string keys in recipes and catalogs
Scoped managers correctly inherit parent context
[0.1.1] - 2026-01-29
Added
Configurable retry strategy for HTTP requests
retry_total- Number of retry attempts (default: 3)retry_backoff_factor- Exponential backoff multiplier (default: 1)retry_status_codes- HTTP codes to retry (default: 429, 500, 502, 503, 504)
System enhancements for diagnostics, certificates, and settings
Unit tests for remaining resource managers
[0.1.0] - 2026-01-15
Initial release.
Added
Core client with username/password and token authentication
Virtual machine management (CRUD, power operations, snapshots)
Network management (CRUD, firewall rules, DNS)
Tenant management
NAS/storage management
User and group management
Task monitoring and waiting
OData filter builder
Automatic retry with exponential backoff
Comprehensive exception hierarchy
Full type annotations