API Reference

Complete reference documentation for the Noid TypeScript SDK.

NoidClient

The main client class for interacting with Noid server.

Constructor

new NoidClient(options: NoidClientOptions)

Parameters:

Parameter	Type	Description
`options`	`NoidClientOptions`	Client configuration options

NoidClientOptions:

Property	Type	Required	Default	Description
`serverUrl`	`string`	Yes	-	Noid server URL
`token`	`string`	Yes	-	API authentication token
`timeout`	`number`	No	`30000`	Request timeout in milliseconds
`retries`	`number`	No	`3`	Number of retry attempts
`retryDelay`	`number`	No	`1000`	Delay between retries in ms

Example:

const client = new NoidClient({
  serverUrl: 'http://localhost:7654',
  token: 'your-api-token',
  timeout: 60000,
});

VM Operations

createVM()

Create a new microVM.

client.createVM(options: CreateVMOptions): Promise<VM>

Parameters:

Property	Type	Required	Default	Description
`name`	`string`	Yes	-	VM name (must be unique)
`vcpus`	`number`	No	`1`	Number of virtual CPUs
`memory`	`number`	No	`2048`	Memory in MB

Returns: Promise<VM>

Example:

const vm = await client.createVM({
  name: 'my-vm',
  vcpus: 2,
  memory: 4096,
});

listVMs()

List all VMs.

client.listVMs(): Promise<VM[]>

Returns: Promise<VM[]>

Example:

const vms = await client.listVMs();
console.log(`Total VMs: ${vms.length}`);

getVM()

Get details about a specific VM.

client.getVM(name: string): Promise<VM>

Parameters:

Parameter	Type	Description
`name`	`string`	VM name

Returns: Promise<VM>

Example:

const vm = await client.getVM('my-vm');
console.log(`Status: ${vm.status}`);

destroyVM()

Destroy a VM and release its resources.

client.destroyVM(name: string): Promise<void>

Parameters:

Parameter	Type	Description
`name`	`string`	VM name

Returns: Promise<void>

Example:

await client.destroyVM('my-vm');

Command Execution

exec()

Execute a command in a VM.

client.exec(vmName: string, command: string, options?: ExecOptions): Promise<ExecResult>

Parameters:

Parameter	Type	Required	Description
`vmName`	`string`	Yes	VM name
`command`	`string`	Yes	Command to execute
`options`	`ExecOptions`	No	Execution options

ExecOptions:

Property	Type	Description
`env`	`Record<string, string>`	Environment variables
`timeout`	`number`	Command timeout in ms

ExecResult:

Property	Type	Description
`stdout`	`string`	Standard output
`stderr`	`string`	Standard error
`exitCode`	`number`	Exit code

Example:

const result = await client.exec('my-vm', 'ls -la', {
  env: { PATH: '/usr/local/bin:/usr/bin' },
});
console.log(result.stdout);

Checkpoint Operations

createCheckpoint()

Create a VM checkpoint (snapshot).

client.createCheckpoint(
  vmName: string,
  checkpointName: string,
  options?: CheckpointOptions
): Promise<Checkpoint>

Parameters:

Parameter	Type	Required	Description
`vmName`	`string`	Yes	VM name
`checkpointName`	`string`	Yes	Checkpoint name
`options`	`CheckpointOptions`	No	Checkpoint options

CheckpointOptions:

Property	Type	Description
`label`	`string`	Descriptive label

Returns: Promise<Checkpoint>

Example:

const checkpoint = await client.createCheckpoint('my-vm', 'stable-v1', {
  label: 'Production-ready state',
});

listCheckpoints()

List all checkpoints for a VM.

client.listCheckpoints(vmName: string): Promise<Checkpoint[]>

Parameters:

Parameter	Type	Description
`vmName`	`string`	VM name

Returns: Promise<Checkpoint[]>

Example:

const checkpoints = await client.listCheckpoints('my-vm');
for (const cp of checkpoints) {
  console.log(`${cp.name}: ${cp.label}`);
}

restore()

Restore a VM from a checkpoint.

client.restore(
  vmName: string,
  checkpointId: string,
  options?: RestoreOptions
): Promise<VM>

Parameters:

Parameter	Type	Required	Description
`vmName`	`string`	Yes	VM name
`checkpointId`	`string`	Yes	Checkpoint ID
`options`	`RestoreOptions`	No	Restore options

RestoreOptions:

Property	Type	Description
`as`	`string`	Clone to new VM with this name

Returns: Promise<VM>

Examples:

// Restore in-place
await client.restore('my-vm', 'stable-v1');

// Clone to new VM
await client.restore('my-vm', 'stable-v1', {
  as: 'test-instance',
});

Type Definitions

VM

interface VM {
  name: string;
  status: 'running' | 'stopped' | 'paused';
  vcpus: number;
  memory: number;
  ip?: string;
  createdAt: Date;
  updatedAt: Date;
}

Checkpoint

interface Checkpoint {
  id: string;
  name: string;
  label?: string;
  vmName: string;
  createdAt: Date;
  size: number;
}

NoidError

class NoidError extends Error {
  statusCode: number;
  details?: any;
}

Error Handling

All methods can throw NoidError when operations fail:

import { NoidError } from '@noid/sdk';

try {
  await client.createVM({ name: 'my-vm' });
} catch (error) {
  if (error instanceof NoidError) {
    console.error(`Error ${error.statusCode}: ${error.message}`);
  }
}

Common Error Codes:

Code	Description
`400`	Bad request (invalid parameters)
`401`	Unauthorized (invalid token)
`404`	Resource not found
`409`	Conflict (VM already exists)
`500`	Internal server error

Next Steps

Quickstart Guide - Get started quickly
Examples - Code examples
CLI Reference - CLI command reference