API Quick Start

🚧
Quick navigation
Time to read: 8 minutes, 2 seconds
Jump to: 1. Before you begin | 2. Some Orka API basics | 3. Create a user & get a token | 4. Create and deploy your first VM instance | 5. Experience your VM instance | 6. Update the base image | 7. Time to say goodbye
See also: API Reference

🚧
The ultimate quick start
If you want to skip the detailed explanations, just run through these steps on your own:

Create an Orka user and get a token.

List your nodes and check their state in the response.

List the available VMs and images with the API.

Create your first VM config and deploy an instance from it.

Run Apple Screen Sharing to connect to the VM instance. Use vnc://<VM-IP>:<Screenshare-port> with the IP and port from the deploy response from Step 4. Use the admin/admin credentials.

On the VM, change the login credentials, apply the latest OS updates, and install (or upgrade) the Orka VM Tools.

If you are the sole user of the environment, commit the changes to the base image (use the VM instance ID from Step 4). Otherwise, save the changes to a new base image (use the VM instance ID from Step 4).

Deploy another instance of your VM config.

Run Apple Screen Sharing and connect to the newly deployed VM. Use the connection information returned in Step 8.

Delete your VM instances.

List and images your VMs.

The Orka API provides more freedom and capabilities than the Orka CLI but might be harder to use by inexperienced users. While the Orka CLI provides interactive guidance and completion of commands, the Orka API requires you to configure and execute the requests on your own. In addition to completing everyday tasks, the Orka API lets you create your in-house integration and automation.

The Orka API will be most useful to:

advanced users
users with workflows that require automation

1. Before you begin

Get your IP Plan. You can download it from the MacStadium portal.
Connect to your Orka cluster via VPN.
1. Download and install a VPN client. Note that if you're using a custom Orka domain, you might need to make some additional configuration changes.
2. Use the server address and credentials from the VPN section of your IP Plan.

2. Some Orka API basics

You need to target your Orka endpoint in your API calls.

📘
What's your Orka endpoint?
You can get the IP for your Orka endpoint from your IP Plan:

For clusters deployed before Orka 2.1, it's the .100 address for your Private-1 network (usually, 10.221.188.100).

For clusters deployed with Orka 2.1 or later, it's the .20 address for your Private-1 network (usually 10.221.188.20).
You need to use http with the IP.

To get the Orka domain for your Orka cluster, contact MacStadium. To use an external custom domain, see here.
Note that you can use http://<orka-IP>, https://<orka-domain>, and https://<custom-domain> interchangeably in your workflows.

The Orka API distinguishes between administrative and non-administrative operations. Non-administrative actions require you to pass an authentication token in the header (obtained with an API call). Administrative calls require you to also send the Orka license key in the header (available in your IP Plan).
The Orka API is a RESTful API and conforms to the best practices for calls and responses.
The complete API reference is available here.

📘
IMPORTANT
All sample API calls from this point use generic placeholder values.
Change the Orka API endpoint (10.221.188.100, 10.221.188.20, your Orka domain, or your external custom domain), the token, the license key, and any other placeholders as needed to reflect your environment.
All sample responses went through a JSON formatting service. Your responses might look differently.

3. Create a user & get a token

Orka requires you to create a dedicated Orka user for your cluster. This operation also creates a dedicated namespace in the cluster. You are the owner of this namespace. When you create a VM config and/or deploy a VM instance from it, they become associated with your namespace. Other users will not be able to manage your VM configs and your VMs and vice versa. Administrators will be able to list, delete, and purge your VM configs and instances.

In your preferred command-line tool, run the following command:

curl --location --request POST 'http://<orka-api-ip>/users' \
--header 'Content-Type: application/json' \
--header 'orka-licensekey: myLicenseKey' \
--data-raw '{
	"password": "123456",
	"email": "[email protected]"
}'

{
   "message":"",
   "help":{},
   "errors":[],
   "email":"[email protected]"
}

This call creates a user in the Orka database. However, it does not log you in, and it does not return a token in the response. Tokens are used in almost all Orka operations to identify you with the service.

Get a token for the newly created user.

curl --location --request POST 'http://<orka-api-ip>/token' \
--header 'Content-Type: application/json' \
--data-raw '{
	"email": "[email protected]",
	"password": "123456"
}'

{
   "message":"",
   "help":{},
   "errors":[],
   "token":"eyJh..."
}

Grab the token from the response and use it for operations that require you to pass the Authorization: Bearer <token> header.

4. Create and deploy your first VM instance

Run:

curl --location --request GET 'http://<orka-api-ip>/resources/node/list' \
--header 'Authorization: Bearer eyJh...'

{
   "message":"",
   "help":{
      "check_orka_node_status":"To check orka node status for a single node use endpoint http://<orka-api-ip>/resources/node/status/<NODE_NAME>",
      "create_virtual_machine_configuration":"To create a virtual machine configuration, please use the endpoint http://<orka-api-ip>/resources/vm/create",
      "required_request_data_for_create":{
         "orka_vm_name":"<ORKA_VM_NAME>",
         "orka_base_img":"<ORKA_BASE_IMG>",
         "orka_image":"<ORKA_IMAGE>"
      },
      "deploy_virtual_machine":"To deploy a virtual machine node, make sure you have a configuration created and use the endpoint http://<orka-api-ip>/resources/vm/deploy",
      "required_request_data_for_deploy":{
         "orka_vm_name":"<ORKA_VM_NAME>",
         "orka_node_name":"<ORKA_NODE_NAME>"
      }
   },
   "errors":[
      
   ],
   "nodes":[
      {
         "name":"macpro-4",
         "host_name":"macpro-4",
         "address":"10.221.189.11",
         "hostIP":"10.221.189.11",
         "available_cpu":11,
         "allocatable_cpu":12,
         "available_gpu":"N/A",
         "allocatable_gpu":"N/A",
         "available_memory":"30.63G",
         "total_cpu":12,
         "total_memory":"31.32G",
         "node_type":"WORKER",
         "arch":"amd64",
         "state":"READY",
         "orka_tags":[
            
         ]
      },
      {
         "name":"mini-4",
         "host_name":"mini-4",
         "address":"10.221.189.14",
         "hostIP":"10.221.189.14",
         "available_cpu":9,
         "allocatable_cpu":12,
         "available_gpu":"N/A",
         "allocatable_gpu":"N/A",
         "available_memory":"54.84G",
         "total_cpu":12,
         "total_memory":"62.66G",
         "node_type":"WORKER",
         "arch":"amd64",
         "state":"READY",
         "orka_tags":[
            "myPool"
         ]
      },
      {
         "name":"mini-arm-13",
         "host_name":"mini-arm-13",
         "address":"10.221.189.13",
         "hostIP":"10.221.189.13",
         "available_cpu":5,
         "allocatable_cpu":8,
         "available_gpu":"N/A",
         "allocatable_gpu":"N/A",
         "available_memory":"11.20G",
         "total_cpu":8,
         "total_memory":"16.00G",
         "node_type":"WORKER",
         "arch":"arm",
         "state":"READY",
         "orka_group":"myGroup",
         "orka_tags":[
            
         ]
      },
      {
         "name":"mini-25",
         "host_name":"mini-25",
         "address":"10.221.188.35",
         "hostIP":"10.221.188.35",
         "available_cpu":9,
         "allocatable_cpu":12,
         "available_gpu":"N/A",
         "allocatable_gpu":"N/A",
         "available_memory":"54.84G",
         "total_cpu":12,
         "total_memory":"62.66G",
         "node_type":"WORKER",
         "arch":"amd64",
         "state":"READY",
         "orka_tags":[
            "myPool"
         ]
      }
   ]
}

This API call provides an overview of your nodes. It shows the actual IP, the state, and the available resources on each node.

📘
Glossary: Node
A genuine Apple physical host that provides computational resources (RAM and CPU) for your workloads.
A host OS runs on top and you have no direct access (via VNC, SSH, or Screen Sharing) to it.

Check if there are any VM configs or VMs on your environment.

curl --location --request GET 'http://<orka-api-ip>/resources/vm/list' \
--header 'Authorization: Bearer eyJh...'

If this is the first time you're using Orka, you will get an empty response for `virtual_machine_resources".

{
   "message":"",
   "help":{},
   "errors":[],
   "virtual_machine_resources":[]
}

This API call lists the VM configs and VM instances associated with your user. You will never see the VMs of other users.

👍
Do you want to see all VMs on the environment?
Run:
curl --location --request GET 'http://<orka-api-endpoint>/resources/vm/list/all' \
--header 'Authorization: Bearer eyJh...' \
--header 'orka-licensekey: myLicenseKey'
Note that this is an administrative operation and requires you to pass a valid Orka license key.

List the available base images that you can use to create a VM config.

curl --location --request GET 'http://<orka-api-ip>/resources/image/list' \
--header 'Authorization: Bearer eyJh...'

You will likely see a 90GBVenturaSSH.orkasi item in the response. It is a fully installed and configured macOS Ventura image with a 90GB disk size. It also has an admin user configured and SSH and Apple Screen Sharing access enabled.

📘
Glossary: Image
A disk image that represents VM storage. Base images are bootable disk images that provide the OS, file system, and storage for your VM configs and VMs. Empty images provide added storage or serve as the base image during manual OS installs from ISO.

Create your first VM config:

curl --location --request POST 'http://<orka-api-ip>/resources/vm/create' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJh...' \
--data-raw '{
	"orka_vm_name": "myorkavm",
	"orka_base_image": "90GBVenturaSSH.orkasi",
	"orka_image": "myorkavm",
	"orka_cpu_core": 6,
	"vcpu_count": 6
}'

As a bare minimum, you need to pass the following data in the body of the request:

orka_vm_name: Set any user-friendly name that will help you recognize the VM config and the instances deployed from it.
orka_base_image: Set to 90GBVenturaSSH.orkasi. This is a 90GB image with installed macOS Ventura and enabled SSH and Screensharing.
orka_image: Set to the same name you provided for orka_vm_name.
orka_cpu_core: Set to 6. This is the number of CPUs for the VM.
vcpu_count: Set to 6. Unless CPU is 3, it must be half of or the exact amount of CPUs. This setting indicates if hyperthreading is enabled. If vCPU equals CPU, hyperthreading is on.

📘
VM name limitations
The name you specify under VM Name must meet the following requirements:

Doesn't exceed 38 characters.

Contains only lowercase Latin alphanumeric characters (0-9, a-z) and dashes (-).

Begins and ends with an alphanumeric character.

{
   "message":"Successfully Created",
   "help":{
      "deploy_virtual_machine":"To deploy a VM, make sure you have a configuration created and use the endpoint http://<orka-api-ip>/resources/vm/deploy",
      "required_request_data_for_deploy":{
         "orka_vm_name":"myorkavm",
         "orka_node_name":"<ORKA_NODE_NAME>"
      }
   },
   "errors":[]
}

This call creates a VM config.

📘
Glossary: VM config
A template for an Orka virtual machine. You can deploy multiple VM instances (VMs) from a single VM config.

What happens if you list your VMs again now?

curl --location --request GET 'http://<orka-api-ip>/resources/vm/list' \
--header 'Authorization: Bearer eyJh...'

The API now returns information about your VM config. Note the deployment status.

{
   "message":"",
   "help":{
      
   },
   "errors":[
      
   ],
   "virtual_machine_resources":[
      {
         "virtual_machine_name":"myorkavm1",
         "vm_deployment_status":"Not Deployed",
         "owner":"[email protected]",
         "cpu":6,
         "vcpu":6,
         "base_image":"90GBVenturaSSH.orkasi",
         "image":"myorkavm",
         "io_boost":"N/A",
         "net_boost":"N/A",
         "use_saved_state":"N/A",
         "gpu_passthrough":"N/A",
         "configuration_template":"default"
      }
   ],
   "failed_virtual_machine_resources":[
      
   ]
}

Deploy your first VM instance from the newly created VM config.

curl --location --request POST 'http://<orka-api-ip>/resources/vm/deploy' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJh...' \
--data-raw '{
	"orka_vm_name": "myorkavm"
}'

This call deploys a running VM and lists its system and connection information in the response:

{
   "message":"Successfully deployed VM",
   "help":{
      "start_virtual_machine":"To start a VM send rest request to http://<orka-api-ip>/resources/vm/exec/start",
      "stop_virtual_machine":"To stop a VM send rest request to http://<orka-api-ip>/resources/vm/exec/stop",
      "resume_virtual_machine":"To resume a VM send rest request to http://<orka-api-ip>/resources/vm/exec/resume",
      "suspend_virtual_machine":"To suspend a VM send rest request to http://<orka-api-ip>/resources/vm/exec/suspend",
      "data_for_virtual_machine_exec_tasks":{
         "orka_vm_name":"myorkavm",
         "orka_node_name":"mini-arm-34"
      },
      "virtual_machine_vnc":"Once started and deployed, you can use VNC to access it via 10.221.188.34:6001"
   },
   "errors":[
      
   ],
   "ram":"5.00G",
   "vcpu":"6",
   "host_cpu":"6",
   "ip":"10.221.188.34",
   "ssh_port":"8824",
   "screen_share_port":"5903",
   "vm_id":"ba8b03ee09625",
   "port_warnings":[
      
   ],
   "io_boost":true,
   "use_saved_state":"N/A",
   "gpu_passthrough":"N/A",
   "vnc_port":"6001"
}

📘
Glossary: VM instance (VM)
A deployed instance of a VM config. VMs take up resources from your nodes and require a certain amount of CPU and RAM to run.

Check your nodes to see how many resources are now in use.

curl --location --request GET 'http://<orka-api-ip>/resources/node/list' \
--header 'Authorization: Bearer eyJh...'

List your VMs again.

curl --location --request GET 'http://<orka-api-ip>/resources/vm/list' \
--header 'Authorization: Bearer eyJh...'

Note how the deployment status changed to Deployed. The API now also returns system and connection information for the deployed instance.

{
   "message":"",
   "help":{
      
   },
   "errors":[
      
   ],
   "virtual_machine_resources":[
      {
         "virtual_machine_name":"myorkavm",
         "vm_deployment_status":"Deployed",
         "status":[
            {
               "owner":"[email protected]",
               "virtual_machine_name":"myorkavm",
               "virtual_machine_id":"ba8b03ee09625",
               "node_location":"mini-arm-34",
               "node_status":"UP",
               "virtual_machine_ip":"10.221.188.34",
               "vnc_port":"6001",
               "screen_sharing_port":"5903",
               "ssh_port":"8824",
               "cpu":6,
               "vcpu":6,
               "gpu":"N/A",
               "RAM":"4.80G",
               "base_image":"90GBVenturaSSH.orkasi",
               "image":"myorkavm",
               "configuration_template":"default",
               "vm_status":"running",
               "io_boost":"N/A",
               "net_boost":"N/A",
               "use_saved_state":"N/A",
               "reserved_ports":[
                  {
                     "host_port":8824,
                     "guest_port":22,
                     "protocol":"TCP"
                  },
                  {
                     "host_port":5903,
                     "guest_port":5900,
                     "protocol":"TCP"
                  },
                  {
                     "host_port":6001,
                     "guest_port":6001,
                     "protocol":"TCP"
                  }
               ],
               "creation_timestamp":"2023-02-10T09:31:18Z",
               "tag":"",
               "tag_required":false,
               "replicas":1
            }
         ]
      }
   ],
   "failed_virtual_machine_resources":[
      
   ]
}

Although it might seem so, a VM config doesn't disappear when you deploy an instance. It's just that Orka doesn't distinguish between a VM config and a VM instance. It works in terms of Deployed and Not Deployed deployment status.

The GET /resources/vm/list call is powerful. It shows a lot of system information for the VM, along with the unique identifier of the instance (ID), its IP, and several connection ports. Note that even though Screenshare and SSH are always listed and configured for every VM, you won't be able to use them unless the respective connection type is enabled in the macOS as well. This behavior is a security limitation of the OS.

👍
In a pool of many VMs, are you looking for that special one?
When you have a lot of VMs, the response of GET /resources/vm/list might become too crowded to use efficiently. Run GET /resources/vm/status/<NAME> instead and get the system information for a single VM.
Note that GET /resources/vm/status/<NAME> is also the only way to get detailed information for scaled VMs.

5. Experience your VM instance

Look at the last output of GET /resources/vm/list again. Get that IP and screen_sharing_port port. (10.221.188.34 and 5903, respectively, in the example above.)
Launch Apple Screen Sharing on your local machine. In Connect To:, type vnc://<VM-IP>:<Screenshare-port> (vnc://10.221.188.34:5903 in the example above).

📘
Are you not working on macOS?
This step works only on macOS. If you're working on a Linux or Windows machine instead, launch your preferred VNC client and connect to <VM-IP>:<VNC-port> (10.221.188.34:5903 in the example above).

One more thing to remember is that Screen Sharing needs to be already enabled on the macOS. Most of the time, this is not the case (especially on clean OS installs or after an ISO install), and you will need to enable the setting yourself.

The good news is that 90GBVenturaSSH.orkasi is already preconfigured for you, and you can enjoy out-of-the-box Screen Sharing and SSH connectivity.

📘
Are you not using the 90GBVenturaSSH.orkasi image?
If you're using another image as your starting point or if you are installing your OS from ISO, you will likely not have SSH or Screen Sharing enabled by default (even though the respective ports will be mapped by default). In this case, you need to connect to the VM via VNC. You can then enable SSH and Screen Sharing connectivity in the OS.

When prompted by Apple Screen Sharing, provide the credentials for the VM (admin/admin). You will be prompted for the password one more time - when Apple connects to the VM.
On the VM, launch System Preferences > Users & Groups. Select the Admin user and click Change password. Set the Admin user password to whatever works for you.
(Optional) Inside the VM, launch the Terminal and run the following command.

brew install orka-vm-tools

OR

brew upgrade orka-vm-tools

This action ensures that your VM is running the latest version of the Orka VM Tools. This collection of services lets Orka manage the guest operating system on Apple silicon-based VMs more efficiently and enables key features, such as shared VM storage.

If your cluster is not running the latest Orka version, download and install an Orka VM Tools that matches the version of your cluster.

Apply the latest OS updates and restart the VM.

6. Update the base image

Making changes to the configuration or the file system of a running VM does not affect its base image. As soon as you delete the VM, your changes will be lost, and you will need to recreate them manually on other VMs.

To create changes that stick and appear on future deployments, you can commit your changes to the base image, or you can save the changes as a new image.

📘
Glossary: Commit changes
Commit modifies the original base image of the corresponding VM instance. With this operation, you apply the current state of a VM instance over the base image of its VM config. This way, newly deployed instances will launch in the same state as your current VM.
For commit to work, the base image must not be in use by any other VM instances (regardless if they spun from the same VM config or another VM config).
This operation restarts the VM.

📘
Glossary: Save changes
Save creates a new base image from the current state of the corresponding VM instance. To use it, you need to create a new VM config that references the new base image.
This operation restarts the VM.

If you are sure that you are the only Orka user who's using 90GBVenturaSSH.orkasi, you can commit the changes. Otherwise, save a new image.

This operation will persist the new admin password and the latest OS updates. Note that you might need to share the new admin password with future users who might follow this guide.

Return to the command line on your local machine and run the following command. Note that you need to use the unique ID of the VM for orka_vm_name. You can get the ID from the output of the deploy or the list VMs call.

curl --location --request POST 'http://<orka-api-ip>/resources/image/commit' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJh...' \
--data-raw '{
	"orka_vm_name": "ba8b03ee09625"
}'

{
  "message": "committed",
  "help": {},
  "errors": []
}

See how the changes are preserved for yourself. Deploy a new VM instance from your VM config:

curl --location --request POST 'http://<orka-api-ip>/resources/vm/deploy' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJh...' \
--data-raw '{
	"orka_vm_name": "myorkavm"
}'

Launch Apple Screen Sharing and connect to the newly deployed VM instance. Use the updated admin credentials to log in.

7. Time to say goodbye

This section is optional.

When your VM configs and instances have served their purpose, you can remove them. Orka provides two ways to do that: delete and purge.

📘
Glossary: Delete VM
This operation removes the specified instance(s). You can delete a VM by:

name (deletes all VM instances with that name)

name and node (deletes all VM instances with that name from that node)

ID (deletes the VM instance with that ID)

Delete always preserves the original VM config, and you can deploy new VM instances from it.

📘
Glossary: Purge VM
This operation removes all VM instances and the VM config of that name. You can perform a purge even if there are no VM instances deployed.

Remove all VM instances you created until now:

curl --location --request DELETE 'http://<orka-api-ip>/resources/vm/delete' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJh...' \
--data-raw '{
	"orka_vm_name": "myorkavm"
}'

{
   "message":"Successfully deleted VM(s)",
   "help":{
      "list_orka_nodes":"To list orka nodes send a rest a request to http://<orka-api-ip>/resources/node/list",
      "deploy_virtual_machine":"To deploy a VM, make sure you have a configuration created and use the endpoint http://<orka-api-ip>/resources/vm/deploy",
      "required_request_data_for_deploy":{
         "orka_vm_name":"myorkavm"
      }
   },
   "errors":[]
}

List your VMs again.

curl --location --request GET 'http://<orka-api-ip>/resources/vm/list' \
--header 'Authorization: Bearer eyJh...'

You should see 1 virtual_machine_resource in a Not Deployed deployment state.

What's next

You're ready to explore the Orka API on your own. You might find the following resources helpful:

Explore Orka Docs for more advanced tasks and tutorials.
Seek help from the Orka community in the MacStadium Community Slack.
Get support in the MacStadium portal.
Is a feature missing? Please share your feedback with us.
If you're looking to tap into Kubernetes, see this page.

API Quick Start

🚧
Quick navigation

🚧
The ultimate quick start

1. Before you begin

2. Some Orka API basics

📘
What's your Orka endpoint?

📘
IMPORTANT

3. Create a user & get a token

4. Create and deploy your first VM instance

📘
Glossary: Node

👍
Do you want to see all VMs on the environment?

📘
Glossary: Image

📘
VM name limitations

📘
Glossary: VM config

📘
Glossary: VM instance (VM)

👍
In a pool of many VMs, are you looking for that special one?

5. Experience your VM instance

📘
Are you not working on macOS?

📘
Are you not using the 90GBVenturaSSH.orkasi image?

6. Update the base image

📘
Glossary: Commit changes

📘
Glossary: Save changes

7. Time to say goodbye

📘
Glossary: Delete VM

📘
Glossary: Purge VM

What's next

🚧Quick navigation

🚧The ultimate quick start

1. Before you begin

2. Some Orka API basics

📘What's your Orka endpoint?

📘IMPORTANT

3. Create a user & get a token

4. Create and deploy your first VM instance

📘Glossary: Node

👍Do you want to see all VMs on the environment?

📘Glossary: Image

📘VM name limitations

📘Glossary: VM config

📘Glossary: VM instance (VM)

👍In a pool of many VMs, are you looking for that special one?

5. Experience your VM instance

📘Are you not working on macOS?

📘Are you not using the 90GBVenturaSSH.orkasi image?

6. Update the base image

📘Glossary: Commit changes

📘Glossary: Save changes

7. Time to say goodbye

📘Glossary: Delete VM

📘Glossary: Purge VM

What's next

🚧
Quick navigation

🚧
The ultimate quick start

📘
What's your Orka endpoint?

📘
IMPORTANT

📘
Glossary: Node

👍
Do you want to see all VMs on the environment?

📘
Glossary: Image

📘
VM name limitations

📘
Glossary: VM config

📘
Glossary: VM instance (VM)

👍
In a pool of many VMs, are you looking for that special one?

📘
Are you not working on macOS?

📘
Are you not using the 90GBVenturaSSH.orkasi image?

📘
Glossary: Commit changes

📘
Glossary: Save changes

📘
Glossary: Delete VM

📘
Glossary: Purge VM