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:

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