API Reference

Side-by-side method reference for the JavaScript and Python SDKs. Every method maps to an RPC endpoint on the Fleet server.

Mutating methods require a fullAccess API token. Read-only tokens can only call non-mutating methods.

Node information

JavaScript	Python	RPC	Mutating
`getNodeInfo()` → `Promise<NodeInfo>`	`get_node_info()` → `NodeInfo`	`GetNodeInfo`	No
`getNodeStats()` → `Promise<NodeStats>`	`get_node_stats()` → `NodeStats`	`GetNodeStats`	No

// JavaScript
const info = await client.getNodeInfo();
console.log(`${info.name} — ${info.machineModel}, macOS ${info.osVersion}`);
console.log(`${info.cpuCores} cores, ${info.totalMemoryGB} GB RAM`);
 
const stats = await client.getNodeStats();
console.log(`CPU: ${stats.cpuUsagePercent.toFixed(1)}%`);
console.log(`VMs: ${stats.runningVMCount}/${stats.totalVMCount}`);

# Python
info = client.get_node_info()
print(f"{info.name} — {info.machine_model}, macOS {info.os_version}")
print(f"{info.cpu_cores} cores, {info.total_memory_gb} GB RAM")
 
stats = client.get_node_stats()
print(f"CPU: {stats.cpu_usage_percent:.1f}%")
print(f"VMs: {stats.running_vm_count}/{stats.total_vm_count}")

VM management

JavaScript	Python	RPC	Mutating
`listVMs()` → `Promise<VM[]>`	`list_vms()` → `List[VM]`	`ListVMs`	No
`getVM(vmId)` → `Promise<VM \| null>`	`get_vm(vm_id)` → `Optional[VM]`	—	No
`startVM(vmId)` → `Promise<boolean>`	`start_vm(vm_id)` → `bool`	`StartVM`	Yes
`stopVM(vmId)` → `Promise<boolean>`	`stop_vm(vm_id)` → `bool`	`StopVM`	Yes
`suspendVM(vmId)` → `Promise<boolean>`	`suspend_vm(vm_id)` → `bool`	`SuspendVM`	Yes
`startVMRecovery(vmId)` → `Promise<boolean>`	`start_vm_recovery(vm_id)` → `bool`	`StartVMRecovery`	Yes
`cloneVM(vmId, newName)` → `Promise<VM>`	`clone_vm(vm_id, new_name)` → `VM`	`CloneVM`	Yes
`renameVM(vmId, newName)` → `Promise<boolean>`	`rename_vm(vm_id, new_name)` → `bool`	`RenameVM`	Yes
`deleteVM(vmId)` → `Promise<boolean>`	`delete_vm(vm_id)` → `bool`	`DeleteVM`	Yes
`createVM(options)` → `Promise<string>`	`create_vm(name, ...)` → `str`	`CreateVMOnNode`	Yes

createVM / create_vm parameters:

JS Option	Python Parameter	Type	Default
`name`	`name`	string	required
`cpuCount`	`cpu_count`	number	`4`
`memoryMB`	`memory_mb`	number	`8192`
`diskGB`	`disk_gb`	number	`64`
`ipswPath`	`ipsw_path`	string	—
`ociImage`	`oci_image`	string	—

VM settings

JavaScript	Python	RPC	Mutating
`getVMSettings(vmId)` → `Promise<Record>`	`get_vm_settings(vm_id)` → `dict`	`GetVMSettings`	No
`updateVMSettings(vmId, settings)` → `Promise<boolean>`	`update_vm_settings(vm_id, ...)` → `bool`	`UpdateVMSettings`	Yes

Updatable fields:

JS Field	Python Parameter	Type	Description
`cpuCount`	`cpu_count`	number	Virtual CPUs
`memorySize`	`memory_size`	number	Memory in MB
`displayWidth`	`display_width`	number	Display width (px)
`displayHeight`	`display_height`	number	Display height (px)
`intent`	`intent`	string	`"disposable"`, `"persistent"`, `"interactive"`, `"ci"`
`ttlSeconds`	`ttl_seconds`	number	TTL in seconds. `-1` to clear.

// JavaScript
await client.updateVMSettings(vmId, { intent: "ci", ttlSeconds: 3600 });

# Python
client.update_vm_settings(vm_id, intent="ci", ttl_seconds=3600)

Snapshots

JavaScript	Python	RPC	Mutating
`listSnapshots(vmId)` → `Promise<Snapshot[]>`	`list_snapshots(vm_id)` → `List[Snapshot]`	`ListSnapshots`	No
`createSnapshot(vmId, name, desc?)` → `Promise<Snapshot>`	`create_snapshot(vm_id, name, desc?)` → `Snapshot`	`CreateSnapshot`	Yes
`restoreSnapshot(vmId, snapId)` → `Promise<boolean>`	`restore_snapshot(vm_id, snap_id)` → `bool`	`RestoreSnapshot`	Yes
`deleteSnapshot(vmId, snapId)` → `Promise<boolean>`	`delete_snapshot(vm_id, snap_id)` → `bool`	`DeleteSnapshot`	Yes

// JavaScript
const snap = await client.createSnapshot(vmId, "clean", "Before tests");
await client.restoreSnapshot(vmId, snap.id);

# Python
snap = client.create_snapshot(vm_id, "clean", "Before tests")
client.restore_snapshot(vm_id, snap.id)

Command execution

JavaScript	Python	RPC	Mutating
`execCommand(vmId, cmd, opts?)` → `Promise<ExecResult>`	`exec_command(vm_id, cmd, ...)` → `ExecResult`	`ExecCommand`	Yes

Parameters:

JS Option	Python Parameter	Type	Default	Description
`options.sshUser`	`ssh_user`	string	`"cideradmin"`	SSH username
`options.sshPassword`	`ssh_password`	string	—	SSH password
`options.timeout`	`timeout`	number	`300`	Timeout in seconds

The HTTP request timeout is automatically extended to timeout + 60 seconds to prevent premature disconnection.

// JavaScript
const result = await client.execCommand(vmId, "uname -a", {
  sshUser: "admin", sshPassword: "password", timeout: 600,
});
console.log(`${result.success ? "OK" : "FAIL"}: ${result.stdout}`);

# Python
result = client.exec_command(vm_id, "uname -a",
    ssh_user="admin", ssh_password="password", timeout=600)
print(f"{'OK' if result.success else 'FAIL'}: {result.stdout}")

Templates

JavaScript	Python	RPC	Mutating
`listTemplates()` → `Promise<Template[]>`	`list_templates()` → `List[Template]`	`ListTemplates`	No
`getTemplate(id)` → `Promise<Template \| null>`	`get_template(id)` → `Optional[Template]`	`GetTemplate`	No
`getTemplateByName(name)` → `Promise<Template \| null>`	`get_template_by_name(name)` → `Optional[Template]`	`GetTemplate`	No
`createTemplateFromVM(opts)` → `Promise<Template>`	`create_template_from_vm(...)` → `Template`	`CreateTemplateFromVM`	Yes
`deleteTemplate(id)` → `Promise<boolean>`	`delete_template(id)` → `bool`	`DeleteTemplate`	Yes

createTemplateFromVM / create_template_from_vm parameters:

JS Option	Python Parameter	Type	Default
`vmId`	`vm_id`	string	required
`name`	`name`	string	required
`description`	`description`	string	—
`category`	`category`	string	`"custom"`
`keepOriginalVM`	`keep_original_vm`	boolean	`true`

Shared folders

JavaScript	Python	RPC	Mutating
`listSharedFolders(vmId)` → `Promise<SharedFolder[]>`	`list_shared_folders(vm_id)` → `List[dict]`	`ListSharedFolders`	No
`addSharedFolder(opts)` → `Promise<boolean>`	`add_shared_folder(...)` → `bool`	`AddSharedFolder`	Yes
`removeSharedFolder(vmId, name)` → `Promise<boolean>`	`remove_shared_folder(vm_id, name)` → `bool`	`RemoveSharedFolder`	Yes
`setSharedFolderEnabled(vmId, name, on)` → `Promise<boolean>`	`set_shared_folder_enabled(vm_id, name, on)` → `bool`	`SetSharedFolderEnabled`	Yes

addSharedFolder / add_shared_folder parameters:

JS Option	Python Parameter	Type	Default
`vmId`	`vm_id`	string	required
`name`	`name`	string	required
`hostPath`	`host_path`	string	required
`readOnly`	`read_only`	boolean	`false`
`mountTag`	`mount_tag`	string	`"CiderStackShare"`

Image management

JavaScript	Python	RPC	Mutating
`listIPSWs()`	`list_ipsws()`	`ListRemoteIPSWs`	No
`listOCIImages()`	`list_oci_images()`	`ListRemoteOCIImages`	No
`downloadIPSW(url, name, ver)`	`download_ipsw(url, name, ver)`	`DownloadIPSWOnNode`	Yes
`getIPSWInfo(path)`	`get_ipsw_info(path)`	`GetIPSWInfo`	No
`pullOCIImage(ref, creds?)`	`pull_oci_image(ref, user?, pass?)`	`PullOCIImageOnNode`	Yes
`pushImage(vmId, name, insecure?)`	`push_image(vm_id, name, insecure?)`	`PushImage`	Yes

// JavaScript — pull and create
await client.pullOCIImage("ghcr.io/myorg/base:latest");
const vmId = await client.createVM({
  name: "from-image", ociImage: "ghcr.io/myorg/base:latest",
});

# Python — pull and create
client.pull_oci_image("ghcr.io/myorg/base:latest")
vm_id = client.create_vm(name="from-image", oci_image="ghcr.io/myorg/base:latest")

Tasks

JavaScript	Python	RPC
`getTasks(includeCompleted?)` → `Promise<Task[]>`	`get_tasks(include_completed?)` → `List[Task]`	`GetTasks`

Fleet overview

JavaScript	Python	RPC
`getFleetOverview()` → `Promise<FleetOverview>`	`get_fleet_overview()` → `dict`	`GetFleetOverview`
`getFleetEvents(limit?, type?)` → `Promise<FleetEvent[]>`	`get_fleet_events(limit?, type?)` → `List[dict]`	`GetFleetEvents`
`getRemoteResources()` → `Promise<Record>`	`get_remote_resources()` → `dict`	`GetRemoteResources`

Note: The JavaScript SDK returns typed objects for fleet data. The Python SDK returns raw dicts — access nested data like overview["overview"]["stats"].

API token management

JavaScript	Python	RPC	Mutating
`generateAPIToken(name, perms?)` → `Promise<APIToken>`	`generate_api_token(name, perms?)` → `APIToken`	`GenerateAPIToken`	Yes
`revokeAPIToken(id)` → `Promise<boolean>`	`revoke_api_token(id)` → `bool`	`RevokeAPIToken`	Yes
`listAPITokens()` → `Promise<APITokenSummary[]>`	`list_api_tokens()` → `List[APITokenSummary]`	`ListAPITokens`	No

Note: Token management requires node ID authentication (not API token auth). See Authentication.

Fleet utilities

JavaScript	Python	RPC	Mutating
`unpair(nodeId)` → `Promise<boolean>`	`unpair(node_id)` → `bool`	`Unpair`	Yes
`cleanupVMs(force?)` → `Promise<number>`	`cleanup_vms(force?)` → `int`	`CleanupVMs`	Yes
`getIPSWInfo(path)` → `Promise<Record>`	`get_ipsw_info(path)` → `dict`	`GetIPSWInfo`	No

cleanupVMs destroys VMs whose TTL has expired. By default, only disposable VMs are cleaned up. Pass force=true to include persistent VMs.

Error handling

Both SDKs throw/raise FleetError on API failures.

// JavaScript
import { FleetError } from "@ciderstack/fleet-sdk";
 
try {
  await client.startVM("bad-id");
} catch (error) {
  if (error instanceof FleetError) {
    console.error(error.message);
    console.error(error.response);
  }
}

# Python
from ciderstack import FleetError
 
try:
    client.start_vm("bad-id")
except FleetError as e:
    print(e)
    print(e.response)

Common errors

Scenario	Error	Cause
Missing auth	`Authentication required`	No token or node ID provided
Invalid token	`Authentication required`	Token revoked or doesn’t exist
Read-only violation	`Permission denied`	`readOnly` token used on mutating method
Bad VM ID	`VM not found`	VM doesn’t exist or was deleted
Wrong VM state	`VM must be stopped`	Operation requires stopped VM
Already running	`VM is already running`	Tried to start a running VM
Not running	`VM must be running`	Tried to exec/suspend on stopped VM
Network	`Request failed`	Fleet server unreachable