VergeOS TypeScript SDK (tsvergeos)

tsvergeos is a TypeScript SDK for managing VergeOS through the REST API, offering a zero-dependency, tree-shakeable, typed interface for automating VMs, networking, storage, tenants, and multi-site.

Overview

tsvergeos is a TypeScript SDK for managing VergeOS infrastructure through the REST API. It provides a zero-dependency, tree-shakeable, fully typed interface for automating VM lifecycle, networking, storage, multi-tenant operations, and multi-site management, making it ideal for automation scripts, tooling development, and integrations.

Key Features

• Zero Dependencies: Nothing to audit, nothing to break
• Tree-Shakeable: Import only the services you use; unused services are dead-code eliminated
• Full Type Coverage: Every resource, parameter, and response is typed with TSDoc documentation
• 93 Services: Complete coverage of every VergeOS API endpoint
• Multi-Site Built In: Query and manage multiple VergeOS deployments from a single SiteManager
• Cross-Platform: Works in Node.js 20+, Deno, Bun, and modern browsers
• Filtering: OData filter support with both a fluent Filter builder and a functional buildFilter shorthand

Requirements

• Node.js 20+ (also supports Deno and Bun)
• VergeOS 6.x (API v4)

Installation

From npm (Recommended)

npm install @vergeio/tsvergeos

Using pnpm / yarn / bun

pnpm add @vergeio/tsvergeos
# or
yarn add @vergeio/tsvergeos
# or
bun add @vergeio/tsvergeos

Authentication

The SDK supports multiple authentication methods:

API Key (Recommended)

import { VergeClient } from "@vergeio/tsvergeos";

const client = await VergeClient.connect({
  host: "192.168.1.100",
  apiKey: "your-api-key",
  verifySsl: false, // for self-signed certificates
});

SSL Certificate Verification

Set verifySsl: false only for environments with self-signed certificates. For production environments with valid certificates, omit this parameter or set it to true.

Username / Password

const client = await VergeClient.connect({
  host: "192.168.1.100",
  username: "admin",
  password: "secret",
});

Environment Variables

export VERGEOS_HOST=192.168.1.100
export VERGEOS_API_KEY=your-api-key
# Optional:
export VERGEOS_VERIFY_SSL=false
export VERGEOS_TIMEOUT=60

const client = await VergeClient.connectFromEnv();

Recommended for Production

Using environment variables keeps credentials out of your source code and makes it easy to use different credentials across environments.

Service Registration

The SDK uses tree-shakeable imports — services are registered via side-effect imports so unused services are dead-code eliminated from your bundle.

Three Import Levels

// 1. Default: ~48 most-used services (VMs, networks, tenants, storage, etc.)
import { VergeClient } from "@vergeio/tsvergeos";

// 2. Full: all 93 services (alarms, update settings, storage tiers, etc.)
import { VergeClient } from "@vergeio/tsvergeos";
import "@vergeio/tsvergeos/full";

// 3. Individual: pick exactly what you need
import { VergeClient } from "@vergeio/tsvergeos";
import "@vergeio/tsvergeos/services/alarm";
import "@vergeio/tsvergeos/services/storage-tier";

Unregistered Services

The default import does not include every service. If you access a service that isn't registered (e.g., client.alarms without importing it), you'll get undefined. For dashboards, admin tools, or backend scripts where bundle size doesn't matter, use import '@vergeio/tsvergeos/full' to register everything.

Type-Only Imports

Type imports have zero bundle impact regardless of which services are registered:

import type {
  VM,
  Alarm,
  Network,
  Tenant,
  Volume,
} from "@vergeio/tsvergeos/types";

Available Resources

The SDK provides access to 93 services covering the full VergeOS API:

Category	Resources
Compute	VMs, drives, devices, NICs, machine snapshots, stats
Networking	Networks, rules, aliases, addresses, hosts, DNS zones/records/views
VPN	WireGuard interfaces and peers, IPSec connections and phases
Storage	Volumes, volume snapshots, CIFS/NFS shares, syncs, browser, storage tiers
NAS	NAS services, users, files
Tenants	Tenants, nodes, storage, snapshots, Layer 2
Recipes	VM and tenant recipes, instances, catalogs, repositories
Snapshots	Snapshot profiles, periods, cloud snapshots
Sites	API sites service — incoming/outgoing syncs, sync profile periods (distinct from the SDK's SiteManager)
System	System, clusters, nodes, settings, logs, tasks
Monitoring	Alarms, alarm types, webhooks, webhook URLs
Auth	Users, groups, members, permissions, API keys
Tags	Tags, categories, members
Updates	Update settings, sources, packages, branches
Other	Certificates, cloud-init, resource groups

Usage Examples

Managing Virtual Machines

import { VergeClient } from "@vergeio/tsvergeos";
import "@vergeio/tsvergeos/services/vm";

const client = await VergeClient.connect({
  host: "192.168.1.100",
  apiKey: "your-api-key",
});

// List all VMs
const vms = await client.vms.list();
for (const vm of vms) {
  console.log(`${vm.name}: ${vm.ram}MB RAM, ${vm.cpu_cores} cores`);
}

// Get a specific VM
const vm = await client.vms.get(42);
const vmByName = await client.vms.getByName("web-server");

// Create a VM
const newVm = await client.vms.create({
  name: "test-vm",
  machine_type: "q35",
  ram: 2048,
  cpu_cores: 2,
  os_family: "linux",
});

// Power operations
await client.vms.powerOn(newVm.$key);
await client.vms.powerOff(newVm.$key); // graceful ACPI shutdown

// Update a VM
await client.vms.update(newVm.$key, { ram: 4096 });

// Delete a VM
await client.vms.delete(newVm.$key);

Reliable Power State

The powerstate field on a VM resource is often omitted by the API. For authoritative live power state, query the machine status service:

import "@vergeio/tsvergeos/services/machine-status";

const status = await client.machineStatuses.getByMachine(newVm.$key);
console.log(status.running, status.status);

Console Access

getConsoleInfo() returns connection details for opening a direct WebSocket console to a VM. Three auth methods are supported — pick based on where the console is rendered:

// Browser-compatible: token embedded in WebSocket URL
const info = await client.vms.getConsoleInfo(42, {
  username: "admin",
  password: "secret",
});
if (info.isAvailable) {
  const rfb = new RFB(container, info.websocketUrl);
}

// Node / Deno / Bun: API key via Authorization header
const info = await client.vms.getConsoleInfo(42, { apiKey: "..." });
const ws = new WebSocket(info.websocketUrl, {
  headers: { Authorization: `Bearer ${info.apiKey}` },
});

The browser WebSocket API does not support custom headers — use username/password or a pre-existing token in browsers. For a no-API-call shortcut to the web UI console, use client.vms.getConsoleURL(42).

Filtering Resources

The SDK supports multiple filtering approaches:

Fluent Filter Builder

import { Filter } from "@vergeio/tsvergeos";

const filter = new Filter()
  .eq("status", "running")
  .like("name", "web*")
  .gt("cpu_cores", 2)
  .build();

const vms = await client.vms.list({ filter });

Functional Shorthand

import { buildFilter } from "@vergeio/tsvergeos";

const vms = await client.vms.list({
  filter: buildFilter({
    status: "running",
    name: "web*",
    cpu_cores: { gt: 2 },
  }),
});

Pagination and Field Selection

const page = await client.vms.list({
  limit: 10,
  offset: 20,
  sort: "-created",
  fields: ["name", "status", "ram"],
});

// Or iterate all pages automatically (async generator)
for await (const vm of client.vms.listAll()) {
  console.log(vm.name);
}

Multi-Site Management

Manage multiple VergeOS deployments from a single entry point:

import { SiteManager } from "@vergeio/tsvergeos";
import "@vergeio/tsvergeos/services/vm";

const manager = new SiteManager();

await manager.addSite({
  name: "dc-east",
  host: "10.0.1.1",
  apiKey: "key-east",
  tags: ["production"],
});

await manager.addSite({
  name: "dc-west",
  host: "10.0.2.1",
  apiKey: "key-west",
  tags: ["production"],
});

// Query a specific site
const eastVms = await manager.site("dc-east").vms.list();

// Fan out read queries across all sites
const allSiteVms = await manager.all.vms.list();
// → { data: SiteResource<VM>[], errors: SiteError[] }

for (const item of allSiteVms.data) {
  console.log(`${item.site}: ${item.resource.name}`);
}

// Fan out only to sites with a given tag
const prodVms = await manager.tagged("production").vms.list();

// Or register a pre-built VergeClient synchronously (no version check)
const existing = new VergeClient({ host: "10.0.3.1", apiKey: "key-edge" });
manager.addSite("edge-01", existing, ["edge"]);

Multi-Site Queries

The SiteManager fans out read queries across all registered sites in parallel and returns aggregated results along with any per-site errors. Use manager.tagged(tag) to scope the fan-out to a subset of sites. Mutations always go through a named site (manager.site("dc-east").vms.create(...)); the cross-site proxy exposes only list().

Error Handling

All errors extend VergeError with typed subclasses and type guard functions:

import {
  isNotFoundError,
  isAuthError,
  isApiError,
  isValidationError,
} from "@vergeio/tsvergeos";

try {
  const vm = await client.vms.get(999);
} catch (err) {
  if (isNotFoundError(err)) {
    console.log("VM not found");
  } else if (isAuthError(err)) {
    console.log("Authentication failed");
  } else if (isApiError(err)) {
    console.log(`API error ${err.statusCode}: ${err.message}`);
  }
}

Available Error Types

Error Class	Description
VergeError	Base error for all SDK errors
ApiError	Any HTTP error from the API
NotFoundError	Resource not found (404)
AuthError	Authentication failure (401/403)
ConflictError	Resource state conflict (409)
ValidationError	Invalid client-side input
UnsupportedVersionError	Server version too old
TaskError	Async task failed
TaskTimeoutError	Task exceeded wait timeout
SiteError	Multi-site operation failure

Client Configuration

The full set of configuration options:

interface ClientConfig {
  host: string; // Server hostname or URL
  apiKey?: string; // API key for bearer auth
  username?: string; // Username for basic auth
  password?: string; // Password for basic auth
  verifySsl?: boolean; // TLS verification (default: true)
  timeout?: number; // Request timeout in ms (default: 30000)
  retries?: number; // Retry attempts (default: 3)
  retryBackoff?: number; // Backoff between retries in ms (default: 1000)
  fetch?: typeof fetch; // Custom fetch implementation
  signal?: AbortSignal; // Cancellation signal
}

Common Use Cases

• Infrastructure automation: Provision VMs, networks, and storage programmatically
• CI/CD integration: Create and destroy test environments in pipelines
• Monitoring and reporting: Query resource status and generate inventory reports
• Backup automation: Schedule and manage snapshots and cloud backups
• Multi-tenant provisioning: Automate tenant creation and resource allocation
• Multi-site orchestration: Manage and query across multiple VergeOS deployments

Documentation and Resources

For complete documentation, including the full API reference and detailed usage examples, visit the official repository:

• GitHub Repository
• npm Package

Support

If you encounter issues or have feature requests, please open an issue on the GitHub repository:

https://github.com/verge-io/tsvergeos/issues

Additional Resources

• TypeScript Documentation
• VergeOS API Documentation
• Python SDK - Python alternative
• Go SDK - Go alternative
• PowerShell Module - PowerShell alternative
• Terraform Provider - Infrastructure as code