> ## 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. # How Orka manages VMs > How Orka VMs work end to end: VM configs, deployment and node placement, networking and ports, what you can do to a running VM in Orka 4.0, and keeping changes. In Orka, you deploy a macOS VM from an image, usually through a VM config that holds your default settings. Orka places the VM on a node, gives it ports for SSH and Screen Sharing, and runs it until you delete it. To keep changes you make inside a VM, you push it to an image. This page explains how those pieces fit together. Each section links to the reference page with the commands and flags. This page describes Orka 4.0 and the `orka` CLI. On Orka 3.x clusters, the CLI is `orka3`, and Intel nodes support more operations. The notes on this page call out where 3.x differs. ## What is a VM config, and do you need one? A VM config is a template for deploying VMs. It holds the image, CPU, memory, and placement and display settings that a VM starts with. You don't need one: you can deploy straight from an image and set everything with flags. A VM config saves you from repeating the same flags on every deploy. Things to know about VM configs: * **They're shared.** Every VM config lives in the `orka-default` namespace, so anyone with access to `orka-default` can deploy from it. * **You can't edit them.** To change a VM config, delete it and create it again. Flags you pass at deploy time override its values for that one VM. * **Names can be up to 50 characters.** They must use lowercase letters, numbers, and dashes, and start with a letter. The web UI allows only 38 characters. See [VM configuration templates](https://docs.macstadium.com/orka/orka-cli-reference/vm-deployment-and-configuration.md#vm-configuration-templates) for the commands and options. ## What happens when you deploy a VM? When you run `orka vm deploy`, Orka creates the VM from a VM config, an image, or both, with any flags you pass taking priority. The image can be an OCI image from a registry or an image stored in the cluster. Orka then picks a node, pulls the image to that node if it isn't already there, and boots the VM. The first deploy of an image on a node waits for the image to download. Later deploys on that node start from the cached copy. VM names can be up to 63 characters, use lowercase letters, numbers, and dashes, and must start with a letter and end with a letter or number. Use `--generate-name` to have Orka add a unique suffix, which helps when a pipeline deploys many VMs from the same command. See [Deploying VMs](https://docs.macstadium.com/orka/orka-cli-reference/vm-deployment-and-configuration.md#deploying-vms) for the full set of deploy options, including user data and custom metadata. ## Where does a VM run, and how many fit on a node? Each node runs at most two macOS VMs, the limit in Apple's macOS license, or one VM on nodes with a shared VM disk enabled. The Orka scheduler won't place more VMs than that on a node. Orka chooses the node for you. You can steer the choice: * **Scheduler:** each cluster has a default scheduler. The `default` scheduler balances VMs across nodes, and the `most-allocated` scheduler fills one node before moving to the next. Pass `--scheduler`, or set it in the VM config, to choose one. * **Tags:** tag nodes, then deploy with `--tag` to prefer them, or add `--tag-required` to use only them. * **A specific node:** deploy with `--node` to place the VM on one node. ## How do you reach a running VM? Orka assigns each VM ports on its node for SSH, VNC, and Screen Sharing. You connect to the node's IP address on those ports. `orka vm list` shows the ports for each VM. To forward other ports, deploy with `--ports`. How a VM connects to the network depends on how the node is set up, not on the VM. Nodes use NAT by default, where VMs share the node's address and you reach them through the assigned ports. Nodes set up for bridge networking give each VM its own address on the network. See [VM access ports](https://docs.macstadium.com/orka/orka-resources/vm-access-ports.md) for the port ranges to allow in your firewall, and [Bridge networking](https://docs.macstadium.com/orka/orka-on-aws-and-on-prem/using-bridge-networking-with-orka-350.md) for when to use it. ## What can you do to a running VM in Orka 4.0? The following table lists the VM operations in Orka 4.0. | Operation | Command | What it does | | - | - | - | | Deploy | `orka vm deploy` | Creates and starts a VM | | List | `orka vm list` | Shows VMs, their nodes, IP addresses, and ports | | Push | `orka vm push` | Saves the VM to an image in an OCI registry | | Resize | `orka vm resize` | Grows the VM's disk | | Delete | `orka vm delete` | Stops the VM and frees its node resources and ports | There's no command to stop, start, suspend, resume, or revert a VM in Orka 4.0. To start over from a clean image, delete the VM and deploy it again. > [!NOTE] > > On Orka 3.6 and earlier, Intel nodes also support start, stop, suspend, resume, and revert. Orka 4.0 removed them along with Intel support. See [Save, commit, and push Orka VM images with the CLI](https://docs.macstadium.com/orka/orka-cli-reference/vm-lifecycle-management.md). ## How do you keep changes you make inside a VM? Push the VM to an image. Changes you make inside a VM live only on that VM's disk, and they're gone when you delete it. `orka vm push ` saves the VM to an OCI registry, where you can version it and deploy new VMs from it. The push runs in the background, so check it with `orka vm get-push-status`. The VM's namespace needs registry credentials for the registry you push to. Orka copies the VM's disk while the VM keeps running, without pausing it. Finish or stop work inside the VM before you push, so the image doesn't capture a half-written state. > [!NOTE] > > `orka vm save` and `orka vm commit` save a VM to the cluster's own image storage instead of a registry. They're deprecated in Orka 4.0, and they work only on clusters that use cluster (NFS) image storage. Use `orka vm push`. See [Pushing to OCI registries](https://docs.macstadium.com/orka/orka-cli-reference/vm-lifecycle-management.md#pushing-to-oci-registries) for the commands, and [Manage registry credentials](https://docs.macstadium.com/orka/oci-images/oci-images-manage-registry-credentials.md) to set up the registry. ## Can you give a VM more disk, CPU, or memory? It depends on the resource: * **Disk:** `orka vm resize` grows a running VM's disk, in GB. You can't shrink it. The VM needs guest tools installed, and the resize restarts the VM twice: once after growing the disk and once after repartitioning it. * **CPU and memory:** these are set when you deploy, from the VM config or the `--cpu` and `--memory` flags. To change them, deploy a new VM with the values you want. See [Resizing VM disks](https://docs.macstadium.com/orka/orka-cli-reference/vm-lifecycle-management.md#resizing-vm-disks). ## What happens when you delete a VM? Orka stops the VM, frees its CPU, memory, and ports on the node, and removes its disk. Anything you didn't push to an image is lost. Deleting a VM doesn't delete the VM config or the image it came from. ## What happens if a node goes down? It depends on how long the node is down: * **Under 5 minutes,** for example during a reboot, the VM stays assigned to its node. When the node comes back, the VM boots again on its existing disk, so changes inside the VM survive. * **After 5 minutes,** Orka moves the VM off the node. A VM that isn't pinned to a node is deployed again on another node from its original image: its disk is gone, and it gets that node's IP address and new ports. A VM deployed with `--node` waits for its node to come back. Treat a VM's disk as temporary, and push anything you need to keep to an image. ## Where does image caching fit? Image caching downloads an image to nodes ahead of time, so the first deploy on each node doesn't wait for the download. It helps most when many VMs deploy from the same image, such as CI runners. See [Orka image caching for faster VM deployments](https://docs.macstadium.com/orka/orka-resources/image-caching.md). ## Related pages * [Orka CLI VM config templates and deployment](https://docs.macstadium.com/orka/orka-cli-reference/vm-deployment-and-configuration.md) * [Save, commit, and push Orka VM images with the CLI](https://docs.macstadium.com/orka/orka-cli-reference/vm-lifecycle-management.md) * [Deploy Orka VMs from an OCI image registry](https://docs.macstadium.com/orka/oci-images/oci-images-deploy-vms.md) * [VM access ports](https://docs.macstadium.com/orka/orka-resources/vm-access-ports.md) * [Orka image caching for faster VM deployments](https://docs.macstadium.com/orka/orka-resources/image-caching.md) ## Related topics - [Deploy Orka VMs from an OCI image registry](https://docs.macstadium.com/orka/oci-images/oci-images-deploy-vms.md) - [Azure DevOps agents on Orka](https://docs.macstadium.com/orka/orka-devops-integrations/azure-devops.md) - [Orka CLI VM config templates and deployment](https://docs.macstadium.com/orka/orka-cli-reference/vm-deployment-and-configuration.md) - [Save, commit, and push Orka VM images with the CLI](https://docs.macstadium.com/orka/orka-cli-reference/vm-lifecycle-management.md) - [Orka image caching for faster VM deployments](https://docs.macstadium.com/orka/orka-resources/image-caching.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.