Web UI Quick Start

How to get started with the Orka UI. Learn how to set it up for the first time, the basic operations, and how to get help.



The Orka Web UI is currently in beta. Some advanced features might not be available.


Quick navigation

Time to read: 8 minutes, 38 seconds

Jump to: 1. Before you begin | 2. Launch the Orka UI | 3. Create a user | 4. Create and deploy your first VM instance | 5. Experience your VM instance | 6. Create a new base image | 7. Time to say goodbye


The ultimate quick start

If you want to skip the detailed explanations, just run through these steps on your own:

  1. Launch the Orka UI in your browser at http://<Orka-API-endpoint> or https://<Orka-custom-domain>.
  2. Create a user.
  3. Go to Nodes.
  4. Go to Images.
  5. Go to VM Configs and click Create config (90GCatalinaSSH.img for image, 6 for CPU and vCPU, leave VNC enabled).
  6. Click Deploy Config and wait for the confirmation.
  7. Go to VMs and check the connection information for the instance.
  8. Run Apple Screen Sharing to connect to the VM instance. Use vnc://<VM-IP>:<Screenshare-port> with the IP and port from Step 7. Use the admin/admin credentials.
  9. On the VM, change the login credentials and apply the latest OS updates.
  10. Return to the UI. On the VMs page, select your VM instance and click More > Save as new image at the top.
  11. Return to the UI. Go to the Images page and make sure that your new image appears in the list.
  12. On the VMs page, select your VM instance and click More > Delete at the top.
  13. Make sure that the list of VMs is empty.
  14. Go to VM configs and verify that your template is preserved.

The Orka UI is a user-friendly way to get started with Orka. It provides basic capabilities and a clean UI.

The Orka UI will be most useful to:

  • beginner users
  • users with predominantly manual workflows

1. Before you begin

  1. Get your IP Plan. You can download it from the MacStadium portal.
  2. 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. Launch the Orka UI

  • In your browser, navigate to your Orka endpoint.


What's your Orka endpoint?

You can get the IP for your Orka endpoint from your IP Plan. For clusters initially deployed before Orka 2.1 it's the .100 address for your Private-1 network (usually, For clusters initially deployed with Orka 2.1+ it's the .20 address for your Private-1 network (usually . You need to use http with the IP.

To get the custom domain for your Orka cluster, if enabled:

  1. Log into your MacStadium account.
  2. Go to Subscriptions (from the top right corner) and select your Orka cluster.
  3. In the Subscription & Plan details, find your custom domain at the bottom. If you don't see a custom domain field, it's not enabled for your environment yet.
    You need to use https with your custom domain.

Note that you can use both http://<orka-IP> and https://<orka-custom-domain> (if enabled) in your workflows.


3. Create a user

Orka requires you to create a dedicated Orka user for your cluster. This 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.

  • Click Create and fill in the form.

The license key is required for administrative operations. You can get it from your IP Plan.

After you hit Create, the Orka UI logs you in. This also creates and caches a token in your profile. The token is required for most Orka operations and the UI takes care of passing it along, when needed.


Need the token for your user?

If you need to use your token outside of the web UI, click your initials in the top right corner and select Profile. Just copy your token and start using it.

4. Create and deploy your first VM instance

  1. In the sidebar, click Nodes. This page provides information about the current state of you nodes, including the available resources.


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.

  1. In the sidebar, click Images.

You will likely see a 90GCatalinaSSH.img item. This is a fully installed and configured macOS Catalina image with a 90G 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.

  1. In the sidebar, click VM Configs.

If this is the first time you're using Orka, you will get a blank screen.

  1. On the VM Configs page, click Create and fill in the form:
  • Name: Set any user-friendly name that will help you recognize the VM.
  • Base image: Set to 90GCatalinaSSH.img.
  • CPU: Set to 6. This is the number of CPUs for the VM.
  • vCPU: Set to 6. Unless CPU is 3, must be half of or the exact number of CPUs. Basically, this indicates if hyperthreading is enabled. If vCPU equals CPU, hyperthreading is enabled.
  • Enable VNC: Skip. By default, selected. This controls the VNC connectivity of the VM.


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.

This 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.
To list all VM configs associated with your user, run orka vm configs.

  1. On the VM Configs page, select your newly created template and click Deploy Config. Make sure that your template is selected and click Deploy.

Wait for the spinner at the bottom of the screen to complete. A success message should pop up at the bottom of the screen.

This deploys a VM instance from your template.


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.
To deploy more instances of the same config, run orka vm deploy.

  1. Go to the VMs page. Because you haven't deployed any VM instances yet, you will see a blank page.

Now that you have deployed your first VM instance, you will see it in the list.


Note how this screen shows essential information about your VM, including its unique ID (required for some advanced operations) and detailed connection information.


Want to see more details?

If you're looking for more information about your VM, select it from the list and click the eye button at the top.

  1. Go to the Nodes page again. Did the number of available resources change?

5. Experience your VM instance

  1. Return to the VMs page and click the Connection button for your VM.
  1. Launch Apple Screen Sharing on your local machine. In Connect To:, paste the information from the pop-up. (vnc:// in the example above).


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> ( 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. This is the case for SSH as well.

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


Are you not using the 90GCatalinaSSH.img 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.

  1. 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.

  2. 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.

  3. Apply the latest OS updates and restart the VM.

6. Create a new 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 save the changes as a new image.


Glossary: Save changes

Save creates a new base image from the current state of the respective VM instance. To use it, you need to create a new VM config that references the new base image.

This operation restarts the VM.

  1. Return to the Web UI. On the VMs page, select your VM. Select More > Save as new image.
  1. Provide a name for the new image and click Save.

Wait for the operation to complete. It might take a while.

  1. After the operation completes, go to the Images page. Does your new image appear there?



To use your newly created image, you need to create a new VM config.

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.

  • On the VMs page, select your VM. Select More > Delete. When prompted, confirm that you want to delete the VM.

When the page refreshes, you should not see any more VM instances. Your VM config is still available on the VM Configs page and you can deploy new instances from it.

Note that the changes you made to your deleted VM instance will not be present on newly deployed instances.

What's next

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

Β© 2019-2023 Copyright MacStadium, Inc. – Documentation built with readme.com. Orka is a registered trademark of MacStadium, Inc.