SDKsJSON-RPC Protocol

JSON-RPC Protocol

Both SDKs are thin wrappers around a JSON-RPC API served over HTTP on port 9473.

You can call the API directly with curl or any HTTP client — useful for languages without an official SDK, debugging, or quick scripting.

Request format

All requests are HTTP POST to:

http://<host>:9473/rpc/<MethodName>

With a JSON body containing authentication and method-specific parameters.

With API token

{
  "apiToken": "csk_your_token",
  "vmID": "abc-123-...",
  "other_params": "..."
}

With node ID

{
  "callerNodeID": "your-node-uuid",
  "vmID": "abc-123-...",
  "other_params": "..."
}

Response format

Success (data-returning):

{
  "vms": [...],
  "someField": "value"
}

Success (mutation):

{
  "success": true,
  "message": "Operation completed"
}

Error:

{
  "success": false,
  "error": "VM not found"
}

Complete endpoint table

#EndpointMutatingDescription
1GetNodeInfoNoNode hardware/software info
2GetNodeStatsNoReal-time resource statistics
3GetTasksNoBackground task list
4ListVMsNoList all VMs
5StartVMYesStart a VM
6StopVMYesStop a VM
7SuspendVMYesSuspend (pause) a VM
8StartVMRecoveryYesBoot into macOS Recovery Mode
9ListSnapshotsNoList VM snapshots
10CreateSnapshotYesCreate a snapshot
11RestoreSnapshotYesRestore a snapshot
12DeleteSnapshotYesDelete a snapshot
13CloneVMYesClone a VM
14RenameVMYesRename a VM
15DeleteVMYesDelete a VM
16GetVMSettingsNoGet VM configuration
17UpdateVMSettingsYesUpdate VM configuration
18PushImageYesPush VM as OCI image
19GetRemoteResourcesNoNode resource availability
20ListRemoteIPSWsNoList IPSW files
21DownloadIPSWOnNodeYesDownload an IPSW
22ListRemoteOCIImagesNoList cached OCI images
23PullOCIImageOnNodeYesPull an OCI image
24CreateVMOnNodeYesCreate a VM
25ExecCommandYesExecute command via SSH
26GetFleetOverviewNoAggregated fleet status
27GetFleetEventsNoFleet activity log
28GenerateAPITokenYesCreate an API token
29RevokeAPITokenYesRevoke an API token
30ListAPITokensNoList API tokens (redacted)
31ListTemplatesNoList VM templates
32GetTemplateNoGet a template by ID or name
33CreateTemplateFromVMYesCreate template from VM
34DeleteTemplateYesDelete a template
35ListSharedFoldersNoList VM shared folders
36AddSharedFolderYesAdd a shared folder
37RemoveSharedFolderYesRemove a shared folder
38SetSharedFolderEnabledYesToggle shared folder
39UnpairYesRemove a trusted node
40CleanupVMsYesClean up expired VMs
41GetIPSWInfoNoGet IPSW file metadata
42RequestPairing—Initiate pairing (no auth needed)
43CompletePairing—Complete pairing (no auth needed)

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

Internal endpoints

These are used for node-to-node VM migration and are not exposed in the SDKs:

EndpointDescription
PrepareMigrationPrepare source VM for migration
GetMigrationChunkRead a chunk of VM data
CompleteMigrationFinalize source after migration
CancelMigrationCancel an in-progress migration
PrepareReceivePrepare target for incoming migration
ReceiveChunkWrite a chunk of VM data
FinalizeMigrationFinalize target after migration

curl examples

List VMs

curl -s -X POST http://192.168.1.100:9473/rpc/ListVMs \
  -H "Content-Type: application/json" \
  -d '{"apiToken": "csk_your_token"}' | jq

Start a VM

curl -s -X POST http://192.168.1.100:9473/rpc/StartVM \
  -H "Content-Type: application/json" \
  -d '{"apiToken": "csk_your_token", "vmID": "abc-123-..."}' | jq

Stop a VM

curl -s -X POST http://192.168.1.100:9473/rpc/StopVM \
  -H "Content-Type: application/json" \
  -d '{"apiToken": "csk_your_token", "vmID": "abc-123-..."}' | jq

Suspend a VM

curl -s -X POST http://192.168.1.100:9473/rpc/SuspendVM \
  -H "Content-Type: application/json" \
  -d '{"apiToken": "csk_your_token", "vmID": "abc-123-..."}' | jq

Execute a command

curl -s -X POST http://192.168.1.100:9473/rpc/ExecCommand \
  -H "Content-Type: application/json" \
  -d '{
    "apiToken": "csk_your_token",
    "vmID": "abc-123-...",
    "command": "uname -a",
    "sshUser": "admin",
    "sshPassword": "password",
    "timeout": 30
  }' | jq

Update VM settings

curl -s -X POST http://192.168.1.100:9473/rpc/UpdateVMSettings \
  -H "Content-Type: application/json" \
  -d '{
    "apiToken": "csk_your_token",
    "vmID": "abc-123-...",
    "cpuCount": 8,
    "memorySize": 16384,
    "intent": "ci",
    "ttlSeconds": 3600
  }' | jq

Create a snapshot

curl -s -X POST http://192.168.1.100:9473/rpc/CreateSnapshot \
  -H "Content-Type: application/json" \
  -d '{
    "apiToken": "csk_your_token",
    "vmID": "abc-123-...",
    "name": "before-test",
    "description": "Clean state before integration tests"
  }' | jq

List templates

curl -s -X POST http://192.168.1.100:9473/rpc/ListTemplates \
  -H "Content-Type: application/json" \
  -d '{"apiToken": "csk_your_token"}' | jq

Create template from VM

curl -s -X POST http://192.168.1.100:9473/rpc/CreateTemplateFromVM \
  -H "Content-Type: application/json" \
  -d '{
    "apiToken": "csk_your_token",
    "vmID": "abc-123-...",
    "name": "CI Runner Base",
    "description": "macOS with Xcode 16",
    "category": "cicd"
  }' | jq

Get fleet overview

curl -s -X POST http://192.168.1.100:9473/rpc/GetFleetOverview \
  -H "Content-Type: application/json" \
  -d '{"apiToken": "csk_your_token"}' | jq

Get fleet events

curl -s -X POST http://192.168.1.100:9473/rpc/GetFleetEvents \
  -H "Content-Type: application/json" \
  -d '{"apiToken": "csk_your_token", "limit": 20}' | jq

Get node info

curl -s -X POST http://192.168.1.100:9473/rpc/GetNodeInfo \
  -H "Content-Type: application/json" \
  -d '{"apiToken": "csk_your_token"}' | jq

Get node stats

curl -s -X POST http://192.168.1.100:9473/rpc/GetNodeStats \
  -H "Content-Type: application/json" \
  -d '{"apiToken": "csk_your_token"}' | jq

Pull an OCI image

curl -s -X POST http://192.168.1.100:9473/rpc/PullOCIImageOnNode \
  -H "Content-Type: application/json" \
  -d '{
    "apiToken": "csk_your_token",
    "imageReference": "ghcr.io/myorg/macos-base:latest"
  }' | jq

Pull with credentials (private registry)

curl -s -X POST http://192.168.1.100:9473/rpc/PullOCIImageOnNode \
  -H "Content-Type: application/json" \
  -d '{
    "apiToken": "csk_your_token",
    "imageReference": "ghcr.io/myorg/private:v1",
    "credentials": {
      "username": "user",
      "password": "ghp_token..."
    }
  }' | jq

Create a VM

curl -s -X POST http://192.168.1.100:9473/rpc/CreateVMOnNode \
  -H "Content-Type: application/json" \
  -d '{
    "apiToken": "csk_your_token",
    "name": "ci-runner",
    "cpuCount": 4,
    "memoryMB": 8192,
    "diskGB": 64,
    "ociImage": "ghcr.io/myorg/macos-base:latest"
  }' | jq

Cleanup expired VMs

curl -s -X POST http://192.168.1.100:9473/rpc/CleanupVMs \
  -H "Content-Type: application/json" \
  -d '{"apiToken": "csk_your_token", "force": false}' | jq

Add a shared folder

curl -s -X POST http://192.168.1.100:9473/rpc/AddSharedFolder \
  -H "Content-Type: application/json" \
  -d '{
    "apiToken": "csk_your_token",
    "vmID": "abc-123-...",
    "name": "project-src",
    "hostPath": "/Users/dev/project",
    "readOnly": false
  }' | jq

See also

Examples & Workflows