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