Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.macstadium.com/llms.txt

Use this file to discover all available pages before exploring further.

Getting started with the Orka UI is quick, simple, and straightforward. Learn how to quickly get set up for the first time, basic operations, and how to get help. If you want to skip the detailed explanations, just run through these steps on your own:
  1. Obtain an authentication token.
  2. Launch the Orka UI in your browser at <ORKA_API_URL>.
  3. Go to Nodes.
  4. Go to Images.
  5. Go to VM Configs and click Create config (select an available macOS image, 3 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. Use Apple Screen Sharing to connect to the VM instance. Example: vnc://<VM-IP>:<Screenshare-port> with the IP and port from Step 7. Use the admin/admin credentials.
  9. Once you login be sure to change the login credentials, apply the latest OS updates, and install (or upgrade) the Orka VM Tools for added security and functionality.
  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 beneficial to:
  • Beginner users.
  • Users with predominantly manual workflows.

​
1. Before You Begin

  1. Ensure you can access your cluster account in the MacStadium Customer Portal. See Cluster Access Management: Overview.
  2. Get your VPN connection information from your IP Plan. You can download it from the MacStadium portal.
  3. Connect to your Orka cluster via VPN.
    1. Download and install a VPN client. Note that you might need to make additional configuration changes if you’re using a custom Orka domain.
    2. Use the server address and credentials from the VPN section at the top of your IP Plan.

​
2. Authenticate with the Cluster

Orka lets you log in with your MacStadium Customer Portal credentials. Your access privileges are based on the role configured by your account admin in the Customer Portal. By default, you will have access to the orka-default namespace. You can access additional namespaces if you have been added to additional role bindings. 
orka3 login
Orka will launch a new browser tab (or window) and let you log in via the SSO-enabled form. After you log in, you can return to the command line and run additional orka3 commands. Your token is stored locally in the ~/.kube/config file. Personal tokens (SSO login) are valid for one hour. Afterward, you must log in again to obtain a new token. For CI/CD automation, use a service account token instead. Service account tokens are valid for one year by default and don’t require browser-based login. See CI/CD Integrations Quick Start for details. You now need to get your Orka authentication token from your ~/.kube/config: 
orka3 user get-token

​
3. Launch the Orka UI

  • In your browser, navigate to your Orka API URL.
What’s your Orka API URL?You can get your Orka API URL 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), prefixed with http. For example: http://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), prefixed with http. For example: http://10.221.188.20.
  • You can also use https://<orka-domain> and https://<custom-domain> (if configured). To get the Orka domain for your Orka cluster, contact MacStadium support. 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.
Orka UI login page in browser

​
4. Create and Deploy Your First VM Instance

Known limitationsThe Orka Web UI works only in the orka-default namespace.The Orka Web UI does not let you deploy VM instances without a VM configuration.The Orka Web UI works only with images stored locally in the cluster or stored in the remote repository. You cannot deploy VMs using images from OCI-compatible registries.
  1. In the sidebar, click Nodes. This page provides information about the current state of your nodes, including the available resources.
Orka UI Nodes page showing available resources
  1. In the sidebar, click Images.
You will likely see one or more macOS images listed. MacStadium pre-built images come with an admin user configured and SSH and Apple Screen Sharing access enabled.
  1. In the sidebar, click VM Configs.
If this is your first time using Orka, you will get a blank screen.
  1. On the VM Configs page, click Create config and fill in the form:
  • Name: Set any user-friendly name that will help you recognize the VM.
  • Base image: Select an available macOS image from the list. (Note that the settings in the dialog change based on the selected image type.)
  • CPU: Set to 3. This is the number of CPUs for the VM.
  • vCPU: Set to 3. Unless the CPU is 3, it must be half of or the exact number of CPUs. This denotes if hyperthreading is enabled. For example, if the vCPU equals CPU, hyperthreading is enabled.
  • Memory (G): Leave blank. Orka automatically assigns memory when this field is empty. If you provide a value, it overrides the default and allocates the specified amount.
VM name requirements: The name must not exceed 38 characters, must contain only lowercase alphanumeric characters (0-9, a-z) and dashes (-), and must begin and end with an alphanumeric character.
Create VM config form with name, image, CPU, and vCPU fields This creates a VM config.
  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 loading UI at the bottom of the dialog to complete. A success message should pop up at the top of the screen. This deploys a VM instance from your template.
  1. Go to the VMs page. Now that you have deployed your first VM instance, you will see it in the list.
Orka UI VMs page listing deployed VM instances with connection info This screen shows essential connection information about your VM.
  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.
VM connection popup showing VNC URL and port
  1. Launch Apple Screen Sharing on your local machine (In Finder, press Cmd+K). In the Connect to Server dialog, paste the information from the pop-up. (vnc://10.221.189.13:5903 in the example above).
This step works only on macOS. On Linux or Windows, launch your preferred VNC client and connect to <VM-IP>:<VNC-port>.
One more thing to remember is that Screen Sharing must already be enabled within your macOS VM. This is usually not the case (especially on clean OS installs or after an ISO install (Intel only)), and you must enable the setting yourself. This also applies to SSH connectivity. The good news is that MacStadium pre-built images are already preconfigured for you, and you can enjoy out-of-the-box Screen Sharing and SSH connectivity.
If you’re using a custom image or installing from ISO (Intel only), SSH and Screen Sharing are not enabled by default. Connect via VNC first, then enable them 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 again when Apple connects to the VM.
  2. On the VM, launch System Settings > Users & Groups. Select the Admin user and click Change password. Set the Admin user password to whatever works for you.
  3. (Optional) Launch the Terminal application and run the following command.
If Orka VM Tools is not yet installed: 
brew install orka-vm-tools
If Orka VM Tools is already installed and needs updating: 
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 vital 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.
  1. Always apply the latest OS updates and restart the VM.

​
6. Create a New Base Image

Changing 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. You can save the changes as a new image to create changes that stick and appear on future deployments.
This operation restarts the VM. After it completes, you need to create a new VM config that references the new image before you can deploy from it.
  1. Return to the Web UI. On the VMs page, select your VM. Select More > Save as new image.
VM More menu with Save as new image option highlighted
  1. Provide a name for the new image and click Save.
Save as new image dialog with name input field Wait for the operation to complete. It might take a while. There is no progress indicator, but the operation runs in the background. When the operation completes, the dialog closes, and a success notification appears.
  1. After the operation completes, go to the Images page. Did your new image appear there?
To use your newly created image, you need to create a new VM config that references it.

​
7. Delete VMs

This section is optional. When your VM configs and instances have served their purpose, you can remove them. Deleting a VM instance always preserves the original VM config, and you can deploy new instances from it at any time.
  • On the VMs page, select your VM. Select More > Delete. When prompted, confirm that you want to delete the VM.
VM More menu with Delete option highlighted 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.

​
Next Steps