SDKs

CiderStack Fleet provides official SDKs for JavaScript/TypeScript and Python to manage macOS virtual machines programmatically.

Both SDKs wrap the Fleet JSON-RPC API with idiomatic interfaces, giving you full control over VMs, snapshots, templates, shared folders, images, and fleet-wide operations from your own scripts and applications.

At a glance

	JavaScript / TypeScript	Python
Package	`@ciderstack/fleet-sdk`	`ciderstack`
Version	0.1.0	0.1.0
Runtime	Node.js 18+, Bun, Deno	Python 3.8+
Async model	`async/await` (Promises)	Synchronous
HTTP client	Native `fetch`	`requests`
License	Apache-2.0	MIT
Methods	44	44

Both SDKs have 1-to-1 feature parity with each other and with the CLI (cider) for all VM, snapshot, template, shared folder, and fleet operations.

Installation

JavaScript / TypeScript

npm install @ciderstack/fleet-sdk

Or with other package managers:

yarn add @ciderstack/fleet-sdk
bun add @ciderstack/fleet-sdk

Requires Node.js 18+ (uses native fetch, crypto.randomUUID, crypto.subtle).

Python

pip install ciderstack

If you need pairing support (not required for API token auth):

pip install ciderstack[pairing]

Requires Python 3.8+ and requests >= 2.28.0.

Quick start

JavaScript

import { FleetClient } from "@ciderstack/fleet-sdk";
 
const client = new FleetClient({
  host: "192.168.1.100",
  apiToken: "csk_your_token_here",
});
 
// List VMs
const vms = await client.listVMs();
for (const vm of vms) {
  console.log(`${vm.name}: ${vm.state}`);
}
 
// Start a VM
await client.startVM(vms[0].id);
 
// Execute a command
const result = await client.execCommand(vms[0].id, "uname -a", {
  sshUser: "admin",
  sshPassword: "password",
});
console.log(result.stdout);

Python

from ciderstack import FleetClient
 
client = FleetClient("192.168.1.100", api_token="csk_your_token_here")
 
# List VMs
vms = client.list_vms()
for vm in vms:
    print(f"{vm.name}: {vm.state}")
 
# Start a VM
client.start_vm(vms[0].id)
 
# Execute a command
result = client.exec_command(
    vms[0].id, "uname -a",
    ssh_user="admin", ssh_password="password",
)
print(result.stdout)

Key differences between SDKs

Aspect	JavaScript	Python
Async model	`async/await` (Promises)	Synchronous calls
Timeout units	Milliseconds	Seconds
VM state enum	`VMState.Running`	`VMState.RUNNING`
Naming convention	camelCase	snake_case
Fleet overview return	Typed `FleetOverview` object	Raw `dict`
Shared folders return	Typed `SharedFolder[]`	`List[dict]`
Pairing return	`PairingCredentials` object	`dict`
Pairing crypto	Built-in Web Crypto API	`cryptography` package
Null values	`null`	`None`

SDKs

At a glance

Installation

JavaScript / TypeScript

Python

Quick start

JavaScript

Python

Key differences between SDKs

See also