Skip to content

VergeOS TypeScript SDK (tsvergeos)#

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#

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:

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:

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

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

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

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:

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#