> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/automate-protect-and-extend/de/integrationen-und-apis/typescript-sdk.md).

# VergeOS TypeScript SDK (tsvergeos)

## Übersicht

tsvergeos ist ein TypeScript-SDK zur Verwaltung der VergeOS-Infrastruktur über die REST-API. Es bietet eine Zero-Dependency-, tree-shakebare, vollständig typisierte Schnittstelle zur Automatisierung von VM-Lebenszyklus, Netzwerken, Speicher, Multi-Tenant-Operationen und Multi-Site-Verwaltung und ist damit ideal für Automatisierungsskripte, Tool-Entwicklung und Integrationen.

## Hauptmerkmale

* **Keine Abhängigkeiten**: Nichts zu prüfen, nichts zu brechen
* **Tree-Shakebar**: Importiere nur die Dienste, die du verwendest; ungenutzte Dienste werden als Dead Code entfernt
* **Vollständige Typabdeckung**: Jede Ressource, jeder Parameter und jede Antwort ist mit TSDoc-Dokumentation typisiert
* **93 Dienste**: Vollständige Abdeckung jedes VergeOS-API-Endpunkts
* **Multi-Site integriert**: Abfrage und Verwaltung mehrerer VergeOS-Deployments von einer einzigen `SiteManager`
* **Plattformübergreifend**: Funktioniert in Node.js 20+, Deno, Bun und modernen Browsern
* **Filterung**: OData-Filterunterstützung mit sowohl einem fließenden `Filter` Builder als auch einer funktionalen `buildFilter` Kurzschreibweise

## Anforderungen

* Node.js 20+ (unterstützt auch Deno und Bun)
* VergeOS 6.x (API v4)

## Installation

### Über npm (empfohlen)

```bash
npm install @vergeio/tsvergeos
```

### Mit pnpm / yarn / bun

```bash
pnpm add @vergeio/tsvergeos
# oder
yarn add @vergeio/tsvergeos
# oder
bun add @vergeio/tsvergeos
```

## Authentifizierung

Das SDK unterstützt mehrere Authentifizierungsmethoden:

### API-Schlüssel (empfohlen)

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

const client = await VergeClient.connect({
  host: "192.168.1.100",
  apiKey: "your-api-key",
  verifySsl: false, // für selbstsignierte Zertifikate
});
```

{% hint style="info" %}
**SSL-Zertifikatsprüfung**
{% endhint %}

Setzen Sie `verifySsl: false` nur für Umgebungen mit selbstsignierten Zertifikaten. In Produktionsumgebungen mit gültigen Zertifikaten lassen Sie diesen Parameter weg oder setzen Sie ihn auf `true`.

### Benutzername / Passwort

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

### Umgebungsvariablen

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

```typescript
const client = await VergeClient.connectFromEnv();
```

{% hint style="success" %}
**Empfohlen für die Produktion**
{% endhint %}

Die Verwendung von Umgebungsvariablen hält Anmeldedaten aus Ihrem Quellcode heraus und erleichtert die Verwendung unterschiedlicher Anmeldedaten in verschiedenen Umgebungen.

## Dienstregistrierung

Das SDK verwendet tree-shakebare Imports — Dienste werden über Side-Effect-Imports registriert, sodass ungenutzte Dienste aus deinem Bundle als Dead Code entfernt werden.

### Drei Import-Ebenen

```typescript
// 1. Standard: ~48 am häufigsten genutzte Dienste (VMs, Netzwerke, Mandanten, Speicher usw.)
import { VergeClient } from "@vergeio/tsvergeos";

// 2. Vollständig: alle 93 Dienste (Alarme, Update-Einstellungen, Speicherstufen usw.)
import { VergeClient } from "@vergeio/tsvergeos";
import "@vergeio/tsvergeos/full";

// 3. Einzelne: genau die auswählen, die du brauchst
import { VergeClient } from "@vergeio/tsvergeos";
import "@vergeio/tsvergeos/services/alarm";
import "@vergeio/tsvergeos/services/storage-tier";
```

{% hint style="warning" %}
**Nicht registrierte Dienste**
{% endhint %}

Der Standard-Import enthält nicht jeden Dienst. Wenn du auf einen Dienst zugreifst, der nicht registriert ist (z. B., `client.alarms` ohne ihn zu importieren), erhältst du `undefined`. Für Dashboards, Admin-Tools oder Backend-Skripte, bei denen die Bundle-Größe keine Rolle spielt, verwende `import '@vergeio/tsvergeos/full'` um alles zu registrieren.

### Nur Typ-Importe

Typ-Imports haben unabhängig davon, welche Dienste registriert sind, keinen Einfluss auf die Bundle-Größe:

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

## Verfügbare Ressourcen

Das SDK bietet Zugriff auf 93 Dienste, die die gesamte VergeOS-API abdecken:

| Kategorie       | Ressourcen                                                                                                                              |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Compute**     | VMs, Laufwerke, Geräte, NICs, Maschinen-Snapshots, Statistiken                                                                          |
| **Netzwerk**    | Netzwerke, Regeln, Aliase, Adressen, Hosts, DNS-Zonen/-Einträge/-Ansichten                                                              |
| **VPN**         | WireGuard-Schnittstellen und Peers, IPSec-Verbindungen und -Phasen                                                                      |
| **Speicher**    | Volumes, Volume-Snapshots, CIFS/NFS-Freigaben, Synchronisierungen, Browser, Speicherstufen                                              |
| **NAS**         | NAS-Dienste, Benutzer, Dateien                                                                                                          |
| **Mandanten**   | Mandanten, Knoten, Speicher, Snapshots, Layer 2                                                                                         |
| **Rezepte**     | VM- und Mandanten-Rezepte, Instanzen, Kataloge, Repositories                                                                            |
| **Snapshots**   | Snapshot-Profile, Zeiträume, Cloud-Snapshots                                                                                            |
| **Sites**       | API `sites` Dienst — eingehende/ausgehende Synchronisierungen, Zeiträume des Synchronisierungsprofils (getrennt vom SDKs `SiteManager`) |
| **System**      | System, Cluster, Knoten, Einstellungen, Protokolle, Aufgaben                                                                            |
| **Überwachung** | Alarme, Alarmtypen, Webhooks, Webhook-URLs                                                                                              |
| **Auth**        | Benutzer, Gruppen, Mitglieder, Berechtigungen, API-Schlüssel                                                                            |
| **Tags**        | Tags, Kategorien, Mitglieder                                                                                                            |
| **Updates**     | Update-Einstellungen, Quellen, Pakete, Branches                                                                                         |
| **Andere**      | Zertifikate, cloud-init, Ressourcengruppen                                                                                              |

## Anwendungsbeispiele

### Virtuelle Maschinen verwalten

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

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

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

// Eine bestimmte VM abrufen
const vm = await client.vms.get(42);
const vmByName = await client.vms.getByName("web-server");

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

// Power-Operationen
await client.vms.powerOn(newVm.$key);
await client.vms.powerOff(newVm.$key); // geordnetes ACPI-Herunterfahren

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

// Eine VM löschen
await client.vms.delete(newVm.$key);
```

{% hint style="info" %}
**Zuverlässiger Energiezustand**
{% endhint %}

Die `powerstate` Feld einer VM-Ressource wird von der API oft weggelassen. Für den maßgeblichen Live-Energiezustand frage den Machine-Status-Dienst ab:

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

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

### Konsolenzugriff

`getConsoleInfo()` gibt Verbindungsdetails zum Öffnen einer direkten WebSocket-Konsole zu einer VM zurück. Es werden drei Authentifizierungsmethoden unterstützt — wähle je nachdem, wo die Konsole dargestellt wird:

```typescript
// Browser-kompatibel: Token in WebSocket-URL eingebettet
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-Schlüssel über Authorization-Header
const info = await client.vms.getConsoleInfo(42, { apiKey: "..." });
const ws = new WebSocket(info.websocketUrl, {
  headers: { Authorization: `Bearer ${info.apiKey}` },
});
```

Der Browser `WebSocket` Die API unterstützt keine benutzerdefinierten Header — verwende in Browsern Benutzername/Passwort oder ein bereits vorhandenes Token. Für eine Abkürzung ohne API-Aufruf zur Web-UI-Konsole verwende `client.vms.getConsoleURL(42)`.

### Ressourcen filtern

Das SDK unterstützt mehrere Filteransätze:

{% tabs %}
{% tab title="Fließender Filter-Builder" %}

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

{% endtab %}

{% tab title="Funktionale Kurzschreibweise" %}

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

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

{% endtab %}

{% tab title="Seitenauswahl und Feldauswahl" %}

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

// Oder alle Seiten automatisch durchlaufen (asynchroner Generator)
for await (const vm of client.vms.listAll()) {
  console.log(vm.name);
}
```

{% endtab %}
{% endtabs %}

### Multi-Site-Verwaltung

Verwalte mehrere VergeOS-Deployments über einen einzigen Einstiegspunkt:

```typescript
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"],
});

// Eine bestimmte Site abfragen
const eastVms = await manager.site("dc-east").vms.list();

// Leseabfragen über alle Sites verteilen
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}`);
}

// Nur an Sites mit einem bestimmten Tag verteilen
const prodVms = await manager.tagged("production").vms.list();

// Oder einen vorab erstellten VergeClient synchron registrieren (keine Versionsprüfung)
const existing = new VergeClient({ host: "10.0.3.1", apiKey: "key-edge" });
manager.addSite("edge-01", existing, ["edge"]);
```

{% hint style="success" %}
**Multi-Site-Abfragen**
{% endhint %}

Die `SiteManager` verteilt Leseabfragen parallel über alle registrierten Sites und gibt aggregierte Ergebnisse zusammen mit etwaigen Site-spezifischen Fehlern zurück. Verwende `manager.tagged(tag)` um die Verteilung auf eine Teilmenge von Sites zu beschränken. Änderungen laufen immer über eine benannte Site (`manager.site("dc-east").vms.create(...)`); der standortübergreifende Proxy stellt nur `list()`.

## Fehlerbehandlung

Alle Fehler erben von `VergeError` mit typisierten Unterklassen und Type-Guard-Funktionen:

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

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

{% hint style="info" %}
**Verfügbare Fehlertypen**
{% endhint %}

| Fehlerklasse              | Beschreibung                       |
| ------------------------- | ---------------------------------- |
| `VergeError`              | Basiserror für alle SDK-Fehler     |
| `ApiError`                | Jeder HTTP-Fehler der API          |
| `NotFoundError`           | Ressource nicht gefunden (404)     |
| `AuthError`               | Authentifizierungsfehler (401/403) |
| `ConflictError`           | Ressourcenzustandskonflikt (409)   |
| `ValidationError`         | Ungültige Eingabe auf Client-Seite |
| `UnsupportedVersionError` | Serverversion zu alt               |
| `TaskError`               | Asynchrone Aufgabe fehlgeschlagen  |
| `TaskTimeoutError`        | Aufgabe überschritt die Wartezeit  |
| `SiteError`               | Fehler bei Multi-Site-Operation    |

## Client-Konfiguration

Der vollständige Satz an Konfigurationsoptionen:

```typescript
interface ClientConfig {
  host: string; // Server-Hostname oder URL
  apiKey?: string; // API-Schlüssel für Bearer-Authentifizierung
  username?: string; // Benutzername für die Basic-Authentifizierung
  password?: string; // Passwort für die Basic-Authentifizierung
  verifySsl?: boolean; // TLS-Prüfung (Standard: true)
  timeout?: number; // Anforderungs-Timeout in ms (Standard: 30000)
  retries?: number; // Wiederholungsversuche (Standard: 3)
  retryBackoff?: number; // Wartezeit zwischen Wiederholungen in ms (Standard: 1000)
  fetch?: typeof fetch; // Benutzerdefinierte fetch-Implementierung
  signal?: AbortSignal; // Abbruchsignal
}
```

## Häufige Anwendungsfälle

* **Infrastrukturautomatisierung**: VMs, Netzwerke und Speicher programmatisch bereitstellen
* **CI/CD-Integration**: Testumgebungen in Pipelines erstellen und zerstören
* **Überwachung und Berichterstellung**: Ressourcenstatus abfragen und Bestandsberichte erstellen
* **Backup-Automatisierung**: Snapshots und Cloud-Backups planen und verwalten
* **Multi-Tenant-Bereitstellung**: Mandantenerstellung und Ressourcenzuweisung automatisieren
* **Multi-Site-Orchestrierung**: Verwaltung und Abfrage über mehrere VergeOS-Deployments hinweg

## Dokumentation und Ressourcen

Für die vollständige Dokumentation, einschließlich der kompletten API-Referenz und detaillierter Anwendungsbeispiele, besuche das offizielle Repository:

* [GitHub-Repository](https://github.com/verge-io/tsvergeos)
* [npm-Paket](https://www.npmjs.com/package/@vergeio/tsvergeos)

## Support

Wenn Sie auf Probleme stoßen oder Funktionswünsche haben, eröffnen Sie bitte ein Issue im GitHub-Repository:

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

## Weitere Ressourcen

* [TypeScript-Dokumentation](https://www.typescriptlang.org/docs/)
* [VergeOS-API-Dokumentation](/knowledge-base/de/automation-api/verge-api-guide.md)
* [Python SDK](/automate-protect-and-extend/de/integrationen-und-apis/python-sdk.md) - Python-Alternative
* [Go-SDK](/automate-protect-and-extend/de/integrationen-und-apis/go-sdk.md) - Go-Alternative
* [PowerShell-Modul](/automate-protect-and-extend/de/integrationen-und-apis/powershell-module.md) - PowerShell-Alternative
* [Terraform-Provider](/automate-protect-and-extend/de/integrationen-und-apis/terraform-provider.md) - Infrastruktur als Code


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verge.io/automate-protect-and-extend/de/integrationen-und-apis/typescript-sdk.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.