Using Orka, at a Glance

What is the typical user journey with Orka? Orka provides a consistent user journey across use cases and requirements.


Time to read: 5 minutes, 22 seconds

Every Orka user has a unique use case and requirements. Whether you're looking to run single Xcode builds or create an automated CI/CD pipeline with daily and nightly builds, your Orka journey will go through the following simple steps.

1. Get ready

  1. Get an Orka subscription.
    Contact MacStadium to discuss your requirements. Based on your use case, the team will recommend and provide the best hardware option for your business.


Not ready to commit yet?

Go to and try the Orka demo.

  1. Choose your tools.

    • The Orka Web UI provides a quick and user-friendly way to manage your Orka cluster. The Web UI is currently in Beta and provides limited functionality compared to the Orka CLI and the Orka API.
    • The Orka CLI is the easiest way to get started with Orka. It's perfect for manual use and one-time tasks that don't require a lot of automation.
    • If you're looking to build an automated CI/CD system, look into the available Orka integrations - from Jenkins to Drone, the Orka team is continuously adding to the list of supported solutions.
    • The Orka API gives you the freedom to be tool-agnostic or develop an in-house solution. It's ideal for advanced users or more complex use cases that require more control and automation.
  2. Learn to speak Orka.

Also: environment
A group of nodes that represents your Orka environment. The number of nodes is usually divisible by 3.
A cluster is hosted in a MacStadium data center and sits behind a Cisco firewall. To reach it, you need an active VPN connection.
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.
VM config
Also: VM template
A template for an Orka virtual machine. You can deploy multiple VM instances (VMs) from a single VM config.
Also: VM instance
A deployed instance of a VM config. VMs take up resources from your nodes and require a certain amount of CPU and memory to run.
Related: base image, empty 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.
ISOA disk image used exclusively for the installation of macOS on a virtual machine.

2. Get set

  1. Connect to your cluster via VPN. Make sure that you have an up and running VPN connection every time you work with Orka.

    1. Get your IP Plan.
    2. Get a VPN client.
    3. Keep the VPN connection to your cluster live.
  2. Configure your environment. This step is a one-time effort.

    • In the Orka CLI, run orka config. Provide your Orka API endpoint (or custom domain) and your Orka license key (available in your IP Plan).
    • For Orka API calls, target your Orka API endpoint (or custom domain).
    • For CI/CD integrations, configure your Orka API endpoint (or custom domain) as prompted during the setup.


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 http://<orka-IP> and https://<orka-custom-domain> (if enabled) interchangeably in your workflows.

  1. Create a user and obtain a token. Keep your license key handy. Your token authenticates you uniquely with Orka. It's required for non-administrative operations.
    • In the Orka CLI, run orka user create and choose to log in immediately. This operation caches your token locally.
    • With the Orka API, send a POST request to /users with an email and password in the body. This operation creates a user, but you still need to get a token. Next, send a POST request to /token with the email and password for your user. Grab the token from the response and pass it with your Authorization: Bearer <token> headers from now on.
    • For CI/CD integrations, use the CLI or the API to create a user. Most Orka integrations will let you provide the user credentials, and will take care of getting and caching the token.

3. Go

  1. Create a VM config. For CI/CD, you might need to create an SSH-enabled VM config.

To create a VM config, you need an image. Check what images are available. If nothing looks good, check out the remote and pull an image from there. The images available out-of-the-box provide a pre-configured disk size and a pre-installed OS.

If you want to use a different disk size or a different OS that you install yourself, you can go the ISO way. Create an empty image of sufficient size and attach an ISO to your config.

  1. Deploy instances from the config. Deploy as many or as few as you need.

You can connect to your VMs via VNC, SSH, or Apple Screen Sharing. Once connected, you can make changes to the VM, such as installing extra software, enabling OS features, and others. For more information, see VNC, SSH, and Screen Sharing for Orka VMs.

You can preserve the changes from one VM and deploy new VMs with these exact changes on them. Save or commit your changes to preserve them and make them available for future configs and deployments. If you used commit, you can keep using your original VM config to deploy new VMs. If you used save, you need to create a new VM config.

  1. (Optional) Destroy unused instances and configs.

Delete instances you no longer need and, if your workload demands it, deploy fresh instances from your config. If you no longer need a config, you can purge it.

What's next

Choose how you want to get started with Orka.

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