JavaScript / TypeScript SDK

npm install @ciderstack/fleet-sdk

import { FleetClient } from "@ciderstack/fleet-sdk";
 
const client = new FleetClient({
  host: "192.168.1.100",        // Required — IP or hostname
  apiToken: "csk_abc123...",    // Auth: API token (or use nodeId)
  port: 9473,                   // Optional — default 9473
  timeout: 30000,               // Optional — request timeout in ms
});

const creds = await FleetClient.pair(host, code, name?, port?);
// Returns PairingCredentials

// Get node hardware and software info
const info = await client.getNodeInfo();
console.log(`${info.name} (${info.machineModel})`);
console.log(`macOS ${info.osVersion}, Fleet v${info.fleetVersion}`);
console.log(`${info.cpuCores} cores, ${info.totalMemoryGB} GB RAM`);
 
// Get real-time resource stats
const stats = await client.getNodeStats();
console.log(`CPU: ${stats.cpuUsagePercent.toFixed(1)}%`);
console.log(`Memory: ${stats.memoryUsedGB.toFixed(1)}/${stats.memoryTotalGB} GB`);
console.log(`Disk: ${stats.diskUsedGB.toFixed(1)}/${stats.diskTotalGB} GB`);
console.log(`VMs: ${stats.runningVMCount}/${stats.totalVMCount}`);

// List and find VMs
const vms = await client.listVMs();
const vm = await client.getVM("vm-uuid");  // null if not found
 
// Lifecycle
await client.startVM(vm.id);
await client.suspendVM(vm.id);      // Pause (stays in memory)
await client.startVM(vm.id);        // Resume from suspend
await client.stopVM(vm.id);
await client.startVMRecovery(vm.id); // Boot into macOS Recovery
 
// Clone, rename, delete
const clone = await client.cloneVM(vm.id, "my-clone");
await client.renameVM(clone.id, "new-name");
await client.deleteVM(clone.id);
 
// Create a new VM from an OCI image
const vmId = await client.createVM({
  name: "ci-runner-01",
  cpuCount: 4,
  memoryMB: 8192,
  diskGB: 64,
  ociImage: "ghcr.io/myorg/macos-base:latest",
});

// Get current settings
const settings = await client.getVMSettings(vmId);
 
// Update settings (only provided fields are changed)
await client.updateVMSettings(vmId, {
  cpuCount: 8,
  memorySize: 16384,
});
 
// Set display resolution
await client.updateVMSettings(vmId, {
  displayWidth: 1920,
  displayHeight: 1080,
});
 
// Mark as disposable with 1-hour TTL
await client.updateVMSettings(vmId, {
  intent: "disposable",
  ttlSeconds: 3600,
});
 
// Clear the TTL
await client.updateVMSettings(vmId, { ttlSeconds: -1 });

// Create a snapshot
const snapshot = await client.createSnapshot(vmId, "pre-update", "Before system update");
 
// List snapshots
const snapshots = await client.listSnapshots(vmId);
for (const s of snapshots) {
  console.log(`${s.name}: ${s.createdAt.toISOString()} (${s.sizeBytes} bytes)`);
}
 
// Restore (VM must be stopped)
await client.restoreSnapshot(vmId, snapshot.id);
 
// Delete
await client.deleteSnapshot(vmId, snapshot.id);

const result = await client.execCommand(vmId, "uname -a", {
  sshUser: "admin",
  sshPassword: "password",
});
 
if (result.success) {
  console.log(result.stdout);
  console.log(`Completed in ${result.duration}s`);
} else {
  console.error(`Exit ${result.exitCode}: ${result.stderr}`);
}
 
// Long-running command with extended timeout
const build = await client.execCommand(
  vmId,
  "xcodebuild -scheme MyApp build",
  { sshUser: "admin", sshPassword: "password", timeout: 600 }
);

// List templates
const templates = await client.listTemplates();
for (const t of templates) {
  console.log(`${t.name} (${t.category}) — ${t.sourceType}`);
  console.log(`  Defaults: ${t.defaultCPU} CPU, ${t.defaultMemoryMB} MB, ${t.defaultDiskGB} GB`);
}
 
// Look up by ID or name
const template = await client.getTemplate("template-uuid");
const byName = await client.getTemplateByName("CI Runner Base");
 
// Create from a stopped VM
const newTemplate = await client.createTemplateFromVM({
  vmId: "abc-123-...",
  name: "Clean macOS 15 Base",
  description: "Fresh macOS Sequoia with Xcode CLI tools",
  category: "base",
  keepOriginalVM: true,
});
 
// Delete
await client.deleteTemplate(newTemplate.id);

// List shared folders
const folders = await client.listSharedFolders(vmId);
for (const f of folders) {
  const mode = f.readOnly ? "ro" : "rw";
  const status = f.isEnabled ? "enabled" : "disabled";
  console.log(`${f.name}: ${f.hostPath} (${mode}, ${status})`);
}
 
// Add a shared folder
await client.addSharedFolder({
  vmId: vmId,
  name: "project-src",
  hostPath: "/Users/dev/project",
  readOnly: false,
});
 
// Toggle on/off
await client.setSharedFolderEnabled(vmId, "project-src", false);
await client.setSharedFolderEnabled(vmId, "project-src", true);
 
// Remove
await client.removeSharedFolder(vmId, "project-src");

// List available IPSWs and OCI images
const ipsws = await client.listIPSWs();
const images = await client.listOCIImages();
 
// Download an IPSW to the node
await client.downloadIPSW("https://updates.cdn-apple.com/.../restore.ipsw", "macOS 15.1", "15.1");
 
// Get IPSW metadata
const info = await client.getIPSWInfo("/path/to/restore.ipsw");
 
// Pull an OCI image (public)
await client.pullOCIImage("ghcr.io/myorg/macos-base:latest");
 
// Pull an OCI image (private registry)
await client.pullOCIImage("ghcr.io/myorg/private:v1", {
  username: "user",
  password: "ghp_token...",
});
 
// Push a VM as an OCI image (returns task ID)
const taskId = await client.pushImage(vmId, "ghcr.io/myorg/my-vm:latest");

const tasks = await client.getTasks();
for (const task of tasks) {
  const pct = (task.progress * 100).toFixed(0);
  console.log(`[${task.status}] ${task.title}: ${pct}%`);
  if (task.progressText) console.log(`  ${task.progressText}`);
  if (task.errorMessage) console.log(`  ERROR: ${task.errorMessage}`);
}
 
// Include completed tasks
const all = await client.getTasks(true);

const overview = await client.getFleetOverview();
 
// Fleet-wide stats
const s = overview.stats;
console.log(`Nodes: ${s.connectedNodes}/${s.totalNodes}`);
console.log(`VMs: ${s.runningVMs}/${s.totalVMs} running`);
console.log(`CPU: ${s.aggregatedCPUUsage.toFixed(1)}%`);
 
// Per-node breakdown
const allNodes = [overview.managerNode, ...overview.workerNodes];
for (const node of allNodes) {
  console.log(`${node.name} (${node.connectionState}): ${node.runningVMCount} VMs`);
}
 
// All VMs across the fleet
for (const vm of overview.vms) {
  console.log(`${vm.name} on ${vm.hostName}: ${vm.state}`);
}
 
// Activity log
const events = await client.getFleetEvents(50);
for (const e of events) {
  console.log(`[${e.eventType}] ${e.nodeName}: ${e.message}`);
}
 
// Filter by event type
const startEvents = await client.getFleetEvents(20, "vm_started");
 
// Node resource availability
const resources = await client.getRemoteResources();

// Unpair a node
await client.unpair("node-uuid");
 
// Clean up VMs with expired TTL
const cleaned = await client.cleanupVMs();
console.log(`Cleaned ${cleaned} VMs`);
 
// Force cleanup (includes persistent VMs)
const forceClean = await client.cleanupVMs(true);

import { FleetClient, FleetError } from "@ciderstack/fleet-sdk";
 
try {
  await client.startVM("non-existent-id");
} catch (error) {
  if (error instanceof FleetError) {
    console.error(`Fleet error: ${error.message}`);
    console.error("Response:", error.response);
  }
}

enum VMState {
  Stopped = "stopped",
  Starting = "starting",
  Running = "running",
  Paused = "paused",
  Stopping = "stopping",
  Error = "error",
}
 
enum TaskStatus {
  Pending = "pending",
  Running = "running",
  Completed = "completed",
  Failed = "failed",
  Cancelled = "cancelled",
}
 
enum NodeRole {
  Worker = "worker",
  Manager = "manager",
  Operator = "operator",
}
 
type APITokenPermissions = "readOnly" | "fullAccess";

interface NodeInfo {
  nodeId: string;
  name: string;
  hostname: string;
  ipAddress: string;
  port: number;
  machineModel: string;
  osVersion: string;
  cpuCores: number;
  totalMemoryGB: number;
  fleetVersion: string;
}
 
interface NodeStats {
  nodeId: string;
  timestamp: Date;
  cpuUsagePercent: number;
  memoryUsedGB: number;
  memoryTotalGB: number;
  diskUsedGB: number;
  diskTotalGB: number;
  runningVMCount: number;
  totalVMCount: number;
}
 
interface VM {
  id: string;
  nodeID?: string;
  nodeName?: string;
  isLocal?: boolean;
  name: string;
  state: VMState;
  cpuCount: number;
  memoryMB: number;
  diskSizeGB?: number;
  osVersion?: string;
  ipAddress?: string;
}
 
interface VMSettings {
  cpuCount?: number;
  memorySize?: number;
  displayWidth?: number;
  displayHeight?: number;
  intent?: string;
  ttlSeconds?: number;
}
 
interface CreateVMOptions {
  name: string;
  cpuCount?: number;
  memoryMB?: number;
  diskGB?: number;
  ipswPath?: string;
  ociImage?: string;
}
 
interface Snapshot {
  id: string;
  name: string;
  description?: string;
  createdAt: Date;
  sizeBytes: number;
}
 
interface ExecResult {
  success: boolean;
  exitCode: number;
  stdout: string;
  stderr: string;
  duration: number;
}
 
interface Template {
  id: string;
  name: string;
  description?: string;
  macOSVersion?: string;
  iconName: string;
  category: string;
  sourceType: string;
  createdAt: Date;
  modifiedAt: Date;
  diskSizeBytes?: number;
  defaultCPU: number;
  defaultMemoryMB: number;
  defaultDiskGB: number;
}
 
interface CreateTemplateOptions {
  vmId: string;
  name: string;
  description?: string;
  category?: string;
  keepOriginalVM?: boolean;
}
 
interface SharedFolder {
  name: string;
  hostPath: string;
  readOnly: boolean;
  isEnabled: boolean;
  mountTag: string;
}
 
interface AddSharedFolderOptions {
  vmId: string;
  name: string;
  hostPath: string;
  readOnly?: boolean;
  mountTag?: string;
}
 
interface APIToken {
  id: string;
  name: string;
  permissions: APITokenPermissions;
  token?: string;
  createdAt: number;
  lastUsed?: number;
}
 
interface APITokenSummary {
  id: string;
  name: string;
  permissions: APITokenPermissions;
  tokenPrefix: string;
  createdAt: number;
  lastUsed?: number;
}
 
interface Task {
  id: string;
  type: string;
  title: string;
  status: TaskStatus;
  progress: number;
  progressText?: string;
  startedAt: Date;
  completedAt?: Date;
  vmId?: string;
  vmName?: string;
  errorMessage?: string;
}
 
interface FleetOverview {
  managerNode: FleetNodeSummary;
  workerNodes: FleetNodeSummary[];
  vms: FleetVMSummary[];
  stats: FleetStats;
}
 
interface FleetNodeSummary {
  nodeID: string;
  name: string;
  hostname: string;
  ipAddress: string;
  port: number;
  isLocal: boolean;
  connectionState: string;
  stats: object | null;
  vmCount: number;
  runningVMCount: number;
}
 
interface FleetVMSummary {
  id: string;
  name: string;
  state: string;
  hostNodeID: string;
  hostName: string;
  cpuCount: number;
  memoryMB: number;
  diskGB?: number;
}
 
interface FleetStats {
  totalNodes: number;
  connectedNodes: number;
  totalVMs: number;
  runningVMs: number;
  maxRunningVMs: number;
  aggregatedCPUUsage: number;
  aggregatedMemoryUsage: number;
  aggregatedStorageUsage: number;
}
 
interface FleetEvent {
  id: string;
  timestamp: string;
  eventType: string;
  vmID?: string;
  vmName?: string;
  nodeName: string;
  initiatedBy: string;
  message: string;
}
 
interface PairingCredentials {
  nodeId: string;
  privateKeyHex: string;
  publicKeyHex: string;
  responderNodeId: string;
  responderName: string;
}
 
interface ClientOptions {
  host: string;
  port?: number;
  timeout?: number;
  nodeId?: string;
  apiToken?: string;
}