CiderStack Fleet SDK for JavaScript/TypeScript

A TypeScript client for managing macOS VMs across CiderStack Fleet nodes.

Installation

npm install @ciderstack/fleet-sdk

Or install from source:

cd sdk/javascript
bun install   # or npm install
bun run build # or npm run build

Authentication

All API calls require authentication. Two methods are available:

API Tokens (recommended)

The simplest way to authenticate. Generate a token from the CiderStack CLI or app, then pass it to the client:

import { FleetClient } from "@ciderstack/fleet-sdk";

const client = new FleetClient({ host: "192.168.1.100", apiToken: "csk_abc123..." });

Tokens can be read-only (can only list/get data) or full-access (can also start/stop/delete VMs, etc.).

Node ID (via pairing)

For advanced use cases, you can pair the SDK as a fleet node using a 6-digit code from the CiderStack UI:

import { FleetClient } from "@ciderstack/fleet-sdk";

// One-time pairing
const creds = await FleetClient.pair("192.168.1.100", "123456", "my-ci-script");
console.log(`Save this node ID: ${creds.nodeId}`);

// Use the node ID for all future connections
const client = new FleetClient({ host: "192.168.1.100", nodeId: creds.nodeId });

Quick Start

import { FleetClient } from "@ciderstack/fleet-sdk";

const client = new FleetClient({ host: "192.168.1.100", apiToken: "csk_abc123..." });

// List VMs
const vms = await client.listVMs();
for (const vm of vms) {
  console.log(`${vm.name}: ${vm.state}`);
}

// Start a VM
await client.startVM("vm-uuid");

// Execute a command
const result = await client.execCommand("vm-uuid", "uname -a", {
  sshUser: "admin",
  sshPassword: "password",
});
console.log(result.stdout);

Examples

VM Management

// Clone a VM
const newVM = await client.cloneVM("vm-uuid", "my-clone");

// Update VM settings
await client.updateVMSettings("vm-uuid", {
  cpuCount: 8,
  memorySize: 16384, // 16 GB
});

// Delete a VM
await client.deleteVM("vm-uuid");

Snapshots

// Create a snapshot
const snapshot = await client.createSnapshot(
  "vm-uuid",
  "pre-update",
  "Before system update"
);

// List snapshots
const snapshots = await client.listSnapshots("vm-uuid");

// Restore snapshot
await client.restoreSnapshot("vm-uuid", snapshot.id);

Fleet Overview

// Get cluster-wide status
const overview = await client.getFleetOverview();
console.log(`Total nodes: ${overview.stats.totalNodes}`);
console.log(`Running VMs: ${overview.stats.runningVMs}`);

// Get node stats
const stats = await client.getNodeStats();
console.log(`CPU: ${stats.cpuUsagePercent}%`);
console.log(`Memory: ${stats.memoryUsedGB}/${stats.memoryTotalGB} GB`);

Image Management

// Pull an OCI image
await client.pullOCIImage("ghcr.io/myorg/macos-base:latest");

// Create a VM from image
const vmId = await client.createVM({
  name: "ci-runner",
  cpuCount: 4,
  memoryMB: 8192,
  diskGB: 64,
  ociImage: "ghcr.io/myorg/macos-base:latest",
});

Error Handling

import { FleetClient, FleetError } from "@ciderstack/fleet-sdk";

const client = new FleetClient({ host: "192.168.1.100", apiToken: "csk_abc123..." });

try {
  await client.startVM("vm-uuid");
} catch (error) {
  if (error instanceof FleetError) {
    console.error(`Fleet API error: ${error.message}`);
    console.error("Response:", error.response);
  }
}

API Reference

FleetClient

new FleetClient({ host, nodeId?, apiToken?, port?, timeout? })

| Option | Type | Default | Description | | ---------- | -------- | ------- | ---------------------------------------- | | host | string | — | IP address or hostname | | nodeId | string | — | Trusted node ID (from pairing) | | apiToken | string | — | API token (from CiderStack CLI/UI) | | port | number | 9473 | Port number | | timeout | number | 30000 | Request timeout in ms |

Provide exactly one of nodeId or apiToken.

Node Info

• getNodeInfo() -> Promise<NodeInfo>
• getNodeStats() -> Promise<NodeStats>

VM Management

• listVMs() -> Promise<VM[]>
• getVM(vmId) -> Promise<VM | null>
• startVM(vmId) -> Promise<boolean>
• stopVM(vmId) -> Promise<boolean>
• startVMRecovery(vmId) -> Promise<boolean>
• cloneVM(vmId, newName) -> Promise<VM>
• renameVM(vmId, newName) -> Promise<boolean>
• deleteVM(vmId) -> Promise<boolean>
• getVMSettings(vmId) -> Promise<Record<string, unknown>>
• updateVMSettings(vmId, settings) -> Promise<boolean>

Snapshots

• listSnapshots(vmId) -> Promise<Snapshot[]>
• createSnapshot(vmId, name, description?) -> Promise<Snapshot>
• restoreSnapshot(vmId, snapshotId) -> Promise<boolean>
• deleteSnapshot(vmId, snapshotId) -> Promise<boolean>

Command Execution

• execCommand(vmId, command, options?) -> Promise<ExecResult>

Tasks

• getTasks(includeCompleted?) -> Promise<Task[]>

Images

• pushImage(vmId, imageName, insecure?) -> Promise<string>
• listIPSWs() -> Promise<Record<string, unknown>[]>
• listOCIImages() -> Promise<Record<string, unknown>[]>
• downloadIPSW(url, name, version) -> Promise<boolean>
• pullOCIImage(imageReference, credentials?) -> Promise<boolean>
• createVM(options) -> Promise<string>

Fleet

• getFleetOverview() -> Promise<FleetOverview>
• getFleetEvents(limit?, eventType?) -> Promise<FleetEvent[]>
• getRemoteResources() -> Promise<Record<string, unknown>>

Pairing (static method)

• FleetClient.pair(host, code, name?, port?) -> Promise<PairingCredentials>

Types

The SDK exports the following types and enums:

Enums: VMState, TaskStatus, NodeRole

Interfaces: NodeInfo, NodeStats, VM, Snapshot, Task, ExecResult, VMSettings, CreateVMOptions, FleetOverview, FleetStats, FleetNodeSummary, FleetVMSummary, FleetEvent, ClientOptions, PairingCredentials

Requirements

• Node.js >= 18.0.0 or Bun (uses native fetch, crypto.randomUUID, crypto.subtle)

License

MIT