VirtualizorJS

A TypeScript-first SDK for the Virtualizor server management API. Manage VPS instances, users, and plans with a clean, namespaced interface and zero production dependencies.

Installation

npm:

npm install virtualizorjs

bun:

bun add virtualizorjs

Quick Start

Create a Client

import { createVirtualizorClient } from 'virtualizorjs';

const client = createVirtualizorClient({
    host: process.env.VIRTUALIZOR_HOST!,
    apiKey: process.env.VIRTUALIZOR_API_KEY!,
    apiPass: process.env.VIRTUALIZOR_API_PASS!,
    // Optional: port (default 4085), https (default true),
    // rejectUnauthorized (default false), timeout (default 30000ms)
    // Ports: 4085 (HTTPS), 4084 (HTTP)
});

List All VPS

const vpsList = await client.vps.list();

for (const [vpsId, vps] of Object.entries(vpsList)) {
  console.log(`${vpsId}: ${vps.hostname} (${vps.status})`);
}

Start a VPS and Wait for Completion

Many Virtualizor operations are asynchronous. Use client.tasks.wait() to poll for completion:

const result = await client.vps.start('123');
const task = await client.tasks.wait(result.taskid!);

console.log(`VPS started! Task status: ${task.status}`);

Error Handling

All SDK errors are instances of VirtualizorApiError. Catch and inspect them:

import { VirtualizorApiError } from 'virtualizorjs';

try {
  await client.vps.start('invalid-id');
} catch (err) {
  if (err instanceof VirtualizorApiError) {
    console.error(`API Error [${err.code}]: ${err.message}`);
  } else {
    console.error('Unexpected error:', err);
  }
}

API Reference

VPS Management

| Method | Parameters | Returns | Notes | |--------|-----------|---------|-------| | list(filters?) | filters: ListVPSParams | Record<string, VPS> | List all VPS with optional filters | | get(filters) | filters: ListVPSParams | VPS | Get a single VPS with filters | | create(params) | CreateVPSParams | AsyncTaskResult | Async | | delete(vpsId) | vpsId: string | AsyncTaskResult | Async | | start(vpsId) | vpsId: string | AsyncTaskResult | Async | | stop(vpsId) | vpsId: string | AsyncTaskResult | Async | | restart(vpsId) | vpsId: string | AsyncTaskResult | Async | | poweroff(vpsId) | vpsId: string | AsyncTaskResult | Async | | suspend(vpsId) | vpsId: string | AsyncTaskResult | Async | | unsuspend(vpsId) | vpsId: string | AsyncTaskResult | Async | | rebuild(vpsId, params) | vpsId: string, RebuildVPSParams | AsyncTaskResult | Async | | clone(vpsId, params) | vpsId: string, CloneVPSParams | AsyncTaskResult | Async | | migrate(vpsId, params) | vpsId: string, MigrateVPSParams | AsyncTaskResult | Async | | status(vpsId) | vpsId: string | unknown | Current status snapshot | | vnc(vpsId) | vpsId: string | VNCInfo | Get VNC connection details | | stats(vpsId) | vpsId: string | VPSStatsResponse | Get resource usage statistics |

User Management

| Method | Parameters | Returns | Notes | |--------|-----------|---------|-------| | list() | — | Record<string, User> | List all users | | create(params) | CreateUserParams | AsyncTaskResult | Async | | delete(uid) | uid: string | AsyncTaskResult | Async | | suspend(uid) | uid: string | AsyncTaskResult | Async | | unsuspend(uid) | uid: string | AsyncTaskResult | Async |

Plan Management

| Method | Parameters | Returns | Notes | |--------|-----------|---------|-------| | list() | — | Record<string, Plan> | List all plans | | create(params) | CreatePlanParams | AsyncTaskResult | Async | | delete(planId) | planId: string | AsyncTaskResult | Async |

Task Polling

| Method | Parameters | Returns | Notes | |--------|-----------|---------|-------| | get(taskId) | taskId: string | Task \| undefined | Get task status once | | wait(taskId, options?) | taskId: string, { pollIntervalMs?, timeoutMs? }? | Promise<Task> | Poll until complete or timeout |

Task Polling Pattern

Many API calls return AsyncTaskResult with a taskid field. Poll for completion:

// Example: Create a VPS and wait for it to be ready
const createResult = await client.vps.create({
  hostname: 'my-vps.example.com',
  // ... other params
});

const completedTask = await client.tasks.wait(createResult.taskid!, {
  pollIntervalMs: 5000,  // Check every 5 seconds (default: 2000ms)
  timeoutMs: 300000,     // Give up after 5 minutes (default: 120000ms)
});

if (completedTask.status === '1' || completedTask.status === 'done') {
  console.log('VPS creation completed successfully');
}

Configuration

When creating a client, the following options are available:

interface VirtualizorConfig {
  host: string;                      // Virtualizor server hostname or IP
  apiKey: string;                    // API key from Virtualizor panel
  apiPass: string;                   // API password from Virtualizor panel
  port?: number;                     // Server port (default: 4085)
  https?: boolean;                   // Use HTTPS (default: true)
  rejectUnauthorized?: boolean;      // Reject self-signed certs (default: false)
  timeout?: number;                  // Request timeout in ms (default: 30000)
}

Self-Signed SSL Certificates

Virtualizor typically uses self-signed SSL certificates. The SDK handles this by default with rejectUnauthorized: false. If you need to enforce certificate validation, set rejectUnauthorized: true and ensure your Virtualizor instance has a valid certificate.

TypeScript Types

All resources are fully typed. Import types as needed:

import type {
  VPS,
  ListVPSParams,
  CreateVPSParams,
  RebuildVPSParams,
  CloneVPSParams,
  MigrateVPSParams,
  VirtType,
  User,
  CreateUserParams,
  Plan,
  CreatePlanParams,
  Task,
  AsyncTaskResult,
  VirtualizorConfig,
  IpsInput,
} from 'virtualizorjs';

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines on how to help.

Security

Please report security vulnerabilities to the maintainers privately. See SECURITY.md for more details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author: kkMihai
Package: npm/virtualizorjs
Repository: github.com/kkMihai/virtualizorjs