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

# Deploy your first VM with the Orka3 CLI

> Get started with the Orka3 CLI: configure your API URL, log in, list nodes and images, deploy VMs, commit changes to a new base image, and clean up.

Working with the Orka3 CLI is straightforward and friendly. 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. `orka3 config set --api-url <ORKA_API_URL>`
2. `orka3 completion {bash|fish|powershell|zsh}`
3. `orka3 login`
4. `orka3 node list`
5. `orka3 vm list` (you should see 0 results)
6. `orka3 vm deploy --image ghcr.io/macstadium/orka-images/sequoia:latest`
7. `orka3 image list` (this will return the list of locally stored images)
8. `orka3 vm list <VM_NAME>` and `orka3 vm list <VM_NAME> -o wide`
9. Run Apple Screen Sharing to connect to the VM instance. Use `vnc://<VM-IP>:<Screenshare-port>` with the IP and port from Step 8. Use the `admin/admin` credentials.
10. On the VM, change the login credentials, apply the latest OS updates, and install (or upgrade) the Orka VM Tools for added security and functionality.
11. `orka3 vm push <VM_NAME> <IMAGE:TAG>` (Apple silicon, recommended) or `orka3 vm commit <VM_NAME>` / `orka3 vm save <VM_NAME>` (writes to NFS local storage)
12. `orka3 vm deploy --image <IMAGE_NAME> -y` (use the name of the newly saved image or the original image, if you committed the changes to it).
13. Run Apple Screen Sharing and connect to the newly deployed VM. Use the connection information printed by `orka3 vm deploy`. Verify that your changes are there.
14. `orka3 vm delete <VM_NAME>`
15. `orka3 vm list`

The Orka3 CLI is the most immersive way to get started with Orka. It provides easy-to-use commands, command autocompletion, and comprehensive built-in help.

The Orka3 CLI will be helpful to:

* Beginner and advanced users.
* Users with manual workflows.
* Users with workflows that require automation.

## 1. Before You Begin

1. Ensure you can access your cluster account in the MacStadium Customer Portal. See [Cluster Access Management: Overview](/orka/orka-cluster-access/cluster-access-management-overview).
2. Get your VPN connection information from your IP Plan. You can [download](/macstadium/macstadium-overview/ip-plan) it from the [MacStadium portal](https://portal.macstadium.com/).
3. Connect to your Orka cluster via VPN.
   * [Download and install a VPN client](/orka/networking-with-orka-at-macstadium/vpn-connection). Note that if you're using a custom Orka domain, you might need to make some additional configuration changes.
   * Use the server address and credentials from the VPN section at the top of your IP Plan.

## 2. Download and Configure the Orka3 CLI

1. Download and install the latest [Orka3 CLI](/orka/orka-overview/tools-integrations) that matches your environment version.
   * On macOS, run the `pkg` executable.
   * On Linux, unpack the archive and move the executable to `/usr/local/bin`.
   * On Windows, add the directory of the executable to your `PATH`.

**TIP**: Using Homebrew?

Try `brew install orka3`.

2. Launch your preferred command-line tool (e.g., the Terminal on macOS) and run the following command:

```bash theme={null}
orka3 config set --api-url <ORKA_API_URL>
```

This operation is a one-time effort. With it, you set the Orka service endpoint for your cluster.

#### **What's Your Orka API URL?**

You can get your Orka API URL from your [IP Plan](/macstadium/macstadium-overview/ip-plan):

* 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](/orka/networking-with-orka-at-macstadium/external-custom-domains) for your Orka cluster, [contact MacStadium support](https://portal.macstadium.com/login). To use an external custom domain, see [here](/orka/networking-with-orka-at-macstadium/external-custom-domains).

Note that you can use `http://<orka-IP>`, `https://<orka-domain>`, and `https://<custom-domain>` interchangeably in your workflows.

<Note>
  When connecting via HTTPS with a custom domain, the Orka3 CLI requires a valid TLS certificate from a trusted certificate authority. Self-signed certificates are not supported.
</Note>

3. Enable command autocompletion for the Orka3 CLI

```bash theme={null}
orka3 completion {bash|fish|powershell|zsh}
```

The Orka3 CLI prints detailed instructions for the selected shell type.

## 3. Authenticate with Your 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.

```bash theme={null}
orka3 login
```

Orka will launch a new browser tab (or window) and let you log in via the provided 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](/orka/quick-start-guides/cicd-integrations-quick-start) for details.

## 4. Create and Deploy Your First VM Instance

1. Open a new command-line prompt and run:

```bash theme={null}
orka3 node list
```

This command shows basic information about the nodes in the `orka-default` namespace. Re-run this command as you deploy VM instances later on to keep track of the available resources on your nodes.

2. Run:

```bash theme={null}
orka3 vm list
```

This command lists all VM instances in the `orka-default` namespace. If nothing prints, no one has created any VM instances yet.

3. List any images already stored locally in your cluster:

```bash theme={null}
orka3 image list
```

MacStadium maintains a public OCI registry at `ghcr.io/macstadium/orka-images` with pre-built macOS images. You don't need to pull images manually; you can deploy directly from the registry in the next step.

4. Deploy a VM:

```bash theme={null}
orka3 vm deploy --image ghcr.io/macstadium/orka-images/sequoia:latest
```

Orka creates a VM with the specified image and 3 CPUs and assigns a randomly generated name.

5. Check your nodes and VMs.

* Re-run `orka3 node list`. Did the number of available resources change?
* List your VMs:

```bash theme={null}
orka3 vm list
```

You should now see your VM in the list.

For more detailed output, run `orka3 vm list --output wide`, which shows architecture, base image, CPU, memory, and connection ports. Note that `Screenshare` and `SSH` ports are always listed, but you won't be able to use them unless the respective connection type is enabled in macOS. To filter by name, use `orka3 vm list <VM_NAME>`.

## 5. Experience Your VM Instance

1. Look at the last output of `orka3 vm list` again. Get that IP and `Screenshare` port.
2. Launch Apple Screen Sharing on your local machine (`Cmd+K` in Finder). Type `vnc://<VM-IP>:<Screenshare-port>`.

One more thing to remember is that Screen Sharing must already be enabled on the macOS. This is usually 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 `ghcr.io/macstadium/orka-images/sequoia:latest` is already preconfigured for you, and you can enjoy out-of-the-box Screen Sharing and SSH connectivity.

3. 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.
4. 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.
5. (Optional) Launch the Terminal and run the following command.

If Orka VM Tools is not yet installed:

```bash theme={null}
brew install orka-vm-tools
```

If Orka VM Tools is already installed and you need to update it:

```bash theme={null}
brew upgrade orka-vm-tools
```

This action ensures that your VM is running the latest version of the [Orka VM Tools](/orka/orka-resources/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](/orka/orka-resources/shared-vm-storage).

If your cluster and CLI are not running the latest Orka version, download and install an [Orka VM Tools](/orka/orka-resources/vm-tools) that matches the versions of your cluster and Orka3 CLI.

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

## 6. Preserve the Image Changes

Changing a running VM's configuration or file system 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 make changes permanent, push your image to an OCI-compatible registry. This is the recommended approach for Apple silicon clusters on Orka 3.5 or later. See [Using Harbor OCI Storage with the Orka CLI](/orka/oci-images/using-harbor-oci-storage-with-the-orka-cli).

1. Push the image to your OCI-compatible registry. This retains the updated admin password and OS updates on future deployments.

Return to the command line on your local machine and run:

```bash theme={null}
orka3 regcred <SERVER> --username <USER> --password <PASSWORD> [--allow-insecure]
orka3 vm push <VM_NAME> <IMAGE[:TAG]>
```

You can get the `<VM_NAME>` from `orka3 vm list`. Registry credentials are required; run `orka3 regcred --help` for more information.

<Note>
  If you are on Intel or need to write to NFS local cluster storage instead of an OCI registry, use `vm commit` (overwrites the original base image) or `vm save` (creates a new image). NFS local storage is being phased out in favor of OCI. Run `orka3 vm commit --help` or `orka3 vm save --help` for details.
</Note>

2. See how the changes are preserved for yourself. Deploy a new VM instance:

```bash theme={null}
orka3 vm deploy --image <IMAGE_NAME>
```

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

## 7. Delete VMs

*This section is optional.*

When your VM instances have served their purpose, you can `delete` them.

1. Remove all VM instances you created until now:

```bash theme={null}
orka3 vm delete <VM_NAME>
```

2. List your VMs again.

```bash theme={null}
orka3 vm list
```

## Next Steps

Now that you've deployed and managed your first VM, you're ready to integrate Orka with your CI/CD pipeline:

* [CI/CD Integrations Quick Start](/orka/quick-start-guides/cicd-integrations-quick-start): set up a service account, create a VM template, and connect Orka to your build system
* [Orka VM Tools](/orka/orka-resources/vm-tools): install Orka VM Tools on Apple silicon VMs to enable shared storage and other features
* [Tools and Integrations](/orka/orka-overview/tools-integrations): browse all available Orka CLI versions and CI/CD integrations