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

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.macstadium.com/feedback

```json
{
  "path": "/orka/quick-start-guides/orka3-api-quick-start",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Orka3 API Quick Start

> Get started with the Orka3 REST API: authenticate with a CLI token, deploy VMs, manage images, and build custom integrations with your Orka cluster.

Getting started with the Orka3 API. Learn the basic operations and how to get help.

The ultimate quick start

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

1. Get an authentication token from the Orka3 CLI.
2. [List your nodes](https://macstadium.github.io/orka-api-docs/#tag/Nodes/operation/listNodes) and check their state in the response.
3. List the available [VMs](https://macstadium.github.io/orka-api-docs/#tag/VMs/operation/listVMs) with the API.
4. [Deploy your first VM instance](https://macstadium.github.io/orka-api-docs/#tag/VMs/operation/vmDeploy).
5. Run Apple Screen Sharing to connect to the VM instance. Use `vnc://<VM-IP>:<Screenshare-port>` with the IP and port from the deploy response from Step 4. Use the `admin/admin` credentials.
6. 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.
7. [Commit](https://macstadium.github.io/orka-api-docs/#tag/VMs/operation/imageCommit) or [save the changes](https://macstadium.github.io/orka-api-docs/#tag/VMs/operation/imageSave) to a new base image (use the VM name from Step 4).
8. [Deploy another VM instance](https://macstadium.github.io/orka-api-docs/#tag/VMs/operation/vmDeploy).
9. Run Apple Screen Sharing and connect to the newly deployed VM. Use the connection information returned in Step 8.
10. [Delete](https://macstadium.github.io/orka-api-docs/#tag/VMs/operation/deleteVM) your VM instances.
11. [List](https://macstadium.github.io/orka-api-docs/#tag/VMs/operation/listVMs) your VMs.

The Orka3 API requires you to configure and execute the requests on your own. In addition to completing everyday tasks, the Orka3 API lets you create your in-house integration and automation.

The Orka3 API will be most useful to:

* Advanced users
* Users with workflows that require automation

## Before You Begin

1. Make sure you can access the account for your cluster 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.

## Some Orka3 API Basics

* You need to target your Orka API URL in your API calls.
* You need to provide the `Authorization: Bearer <TOKEN>` header in your API calls.

### What's Your Orka API URL?

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

* 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/built-in-orka-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).

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

* The Orka3 API is a RESTful API and conforms to enterprise industry standards.

<Tip>
  The full API reference, including all endpoints, request bodies, and response schemas, is at [macstadium.github.io/orka-api-docs](https://macstadium.github.io/orka-api-docs/). Use it alongside this quick start to explore operations not covered here.
</Tip>

<Warning>All sample API calls from this point use generic placeholder values. Replace the Orka API URL, token, and any other placeholders with values from your environment. Sample responses are piped through a JSON formatter — yours may look different.</Warning>

## Get a Token from the Orka3 CLI

For all API calls, you need to provide the `Authorization: Bearer <TOKEN>` header. The Orka3 API currently does not let you log in from it directly and obtain a token. You will need to obtain your token from the Orka3 CLI.

Orka lets you log in with your MacStadium Customer Portal credentials. Based on the role configured in the Customer Portal, you will have administrative or regular user privileges. By default, you will have access to the `orka-default` namespace. If you have been added to additional role bindings, you might be able to access additional namespaces.

```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 more `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.

You now need to get your Orka authentication token from your `~/.kube/config`:

```bash theme={null}
orka3 user get-token
```

## Deploy Your First VM Instance

You can use the built-in Swagger UI to execute API calls directly against your cluster.

In your browser, navigate to `<ORKA_API_URL>/api/v1/swagger`, click **Authorize** , and type `Bearer <TOKEN>`. For every call that you want to run, just click **Try it out** and fill the required details.

1. Check the available resources in your cluster:

**cURL**

```bash theme={null}
curl -X 'GET' \
'<ORKA_API_URL>/api/v1/namespaces/orka-default/nodes' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <TOKEN>'
```

**Response**

```json theme={null}
{
  "items": [
    {
      "name": "macpro-4",
      "namespace": "orka-default",
      "nodeIP": "10.221.189.11",
      "availableCpu": 12,
      "availableMemory": "31.23G",
      "availableGpu": 0,
      "allocatableCpu": 12,
      "allocatableMemory": "31.23G",
      "allocatableGpu": 0,
      "nodeType": "WORKER",
      "phase": "READY",
      "orkaTags": []
    },
    {
      "name": "mini-arm-13",
      "namespace": "orka-default",
      "nodeIP": "10.221.189.13",
      "availableCpu": 5,
      "availableMemory": "11.20G",
      "availableGpu": 0,
      "allocatableCpu": 8,
      "allocatableMemory": "16.00G",
      "allocatableGpu": 0,
      "nodeType": "WORKER",
      "phase": "READY",
      "orkaTags": []
    }
  ]
}
```

This API call provides an overview of your nodes. It shows the actual IP, the state, and the available resources on each node.

<Note>
  **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).

  **Namespace:** A way to isolate and dedicate resources to users and teams within the cluster. The resources within a namespace are completely isolated from one another and cannot be shared between namespaces. By default, users and service accounts limited to a specific namespace cannot access the resources in other namespaces, unless added to the respective role bindings.
</Note>

2. Check if there are any VMs on your environment.

**cURL**

```bash theme={null}
curl -X 'GET' \
'<ORKA_API_URL>/api/v1/namespaces/orka-default/vms' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <TOKEN>'
```

**Response**

```json theme={null}
{
  "items": []
}
```

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

3. List the available base images that you can use to deploy a VM.

```bash theme={null}
curl -X 'GET' \
'<ORKA_API_URL>/api/v1/namespaces/orka-default/images' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <TOKEN>'
```

You will likely see a `sonoma-90gb-orka3-arm` item in the response. It is a fully installed and configured macOS Sonoma image with a 90GB disk size. It also has an admin user configured and SSH and Apple Screen Sharing access enabled.

<Note>
  **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. (Intel-only) Empty images provide added storage or serve as the base image during manual OS installs from ISO.
</Note>

4. Deploying a VM is as simple as just specifying a base image. Run:

**cURL**

```bash theme={null}
curl -X 'POST' \
'<ORKA_API_URL>/api/v1/namespaces/orka-default/vms' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
  "image": "sonoma-90gb-orka3-arm"
}'
```

**Response**

```json theme={null}
{
  "name": "vm-cznfv",
  "node": "mini-arm-13",
  "memory": "4.80Gi",
  "ip": "10.221.189.13",
  "ssh": 8822,
  "vnc": 5999,
  "screenshare": 5901,
  "status": "Running"
}
```

The bare minimum required argument is `image`.

Orka creates a simple VM with the specified image and 3 CPU, and assigns a randomly generated name to it.

You can also deploy VMs using images from OCI-compatible registries.

You can also deploy directly from MacStadium's public OCI registry.

**cURL**

```bash theme={null}
curl -X 'POST' \
'<ORKA_API_URL>/api/v1/namespaces/orka-default/vms' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"image": "ghcr.io/macstadium/orka-images/sequoia:latest"
}'
```

**Response**

```json theme={null}
{
  "name": "vm-cznfv",
  "node": "mini-arm-13",
  "memory": "4.80Gi",
  "ip": "10.221.189.13",
  "ssh": 8822,
  "vnc": 5999,
  "screenshare": 5901,
  "status": "Running"
}
```

5. What happens if you list your VMs again now?

**cURL**

```bash theme={null}
curl -X 'GET' \
'<ORKA_API_URL>/api/v1/namespaces/orka-default/vms' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <TOKEN>'
```

**Response**

```json theme={null}
{
  "items": [
    {
      "name": "vm-l4qgb",
      "ip": "10.221.189.13",
      "cpu": 3,
      "deployDate": "2023-10-10T19:56:21Z",
      "image": "sonoma-90gb-orka3-arm",
      "gpuPassthrough": false,
      "memory": "4.80Gi",
      "node": "mini-arm-13",
      "screenshare": 5901,
      "ssh": 8822,
      "status": "Running",
      "vnc": 5999
    }
  ]
}
```

The API now returns information about your running VM.

The `GET /api/v1/namespaces/orka-default/vms` call shows system information for your VMs, including IP and connection ports. Note that even though `screenshare` and `ssh` ports are always listed, you won't be able to use them unless the respective connection type is enabled in macOS. This is a security limitation of the OS.

<Note>
  When you have a lot of VMs, the response of `GET /resources/vm/list` can become too crowded to use efficiently. Run `GET /namespaces/orka-default/vms/<VM_NAME>` instead to get system information for a single VM.
</Note>

6. Check your nodes to see how many resources are now in use.

**cURL**

```bash theme={null}
curl -X 'GET' \
'<ORKA_API_URL>/api/v1/namespaces/orka-default/nodes' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <TOKEN>'
```

## Experience Your VM Instance

1. Look at the last output of `GET /namespaces/orka-default/vms` again. Get that IP and `screenshare` port.
2. Launch Apple Screen Sharing on your local machine. In **Connect To:** , type `vnc://<VM-IP>:<Screenshare-port>`.

**Are you 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>`.

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 (Intel Workloads Only)), and you will need to enable the setting yourself.

The good news is that `sonoma-90gb-orka3-arm` is already preconfigured for you, and you can enjoy out-of-the-box Screen Sharing and SSH connectivity.

**Are you not using the official Sonoma images?**

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.

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

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) Inside the VM, launch the Terminal application and run the following command.

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

# If already installed
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 vital features, such as [shared VM storage](/orka/orka-resources/shared-vm-storage).

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

6. Always apply the latest OS updates and restart the VM.

## 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 create changes that stick and appear on future deployments, you can commit your changes to the base image, save the changes as a new image, or push your changes to an OCI-compatible registry.

<Note>
  **Commit:** Modifies the original base image of the respective VM instance. With this operation, you apply the current state of a VM instance over the base image of its VM config. Newly deployed instances will launch in the same state as your current VM. This operation restarts the VM.

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

  **Push:** Pushes your changes to the specified OCI-compatible registry, image, and image tag. Registry credentials are required to push an image.
</Note>

Return to the command line on your local machine and run the following command. You can get the `<VM_NAME>` from the `GET /namespaces/orka-default/vms` output you ran earlier.

**cURL**

```bash theme={null}
curl -X 'POST' \
'<ORKA_API_URL>/api/v1/namespaces/orka-default/vms/<VM_NAME>/commit' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"description": "Committed from <VM_NAME>"
}'

OR

curl -X 'POST' \
'<ORKA_API_URL>/api/v1/namespaces/orka-default/vms/<VM_NAME>/save' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"description": "Saved from <VM_NAME>",
"imageName": "<NEW_IMAGE_NAME>"
}'

OR

curl -X 'POST' \
'<ORKA_API_URL>/api/v1/namespaces/orka-default/vms/<VM_NAME>/push' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"imageReference": "<REGISTRY>/<IMAGE>:<TAG>"
}'
```

**Response** (commit or save)

```json theme={null}
{
  "statusUrl": "/api/v1/namespaces/orka-default/images/sonoma-90gb-orka3-arm"
}
```

**Response** (push)

```json theme={null}
{
  "jobName": "<PUSH_JOB_ID>"
}
```

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

**cURL**

```bash theme={null}
curl -X 'POST' \
'<ORKA_API_URL>/api/v1/namespaces/orka-default/vms' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"image": "<IMAGE_NAME>"
}'
```

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

## Time to Say Goodbye

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

1. Remove the VM instances you created until now:

**cURL**

```bash theme={null}
curl -X 'DELETE' \
'<ORKA_API_URL>/api/v1/namespaces/orka-default/vms/<VM_NAME>' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <TOKEN>'
```

2. List your VMs again.

**cURL**

```bash theme={null}
curl -X 'GET' \
'<ORKA_API_URL>/api/v1/namespaces/orka-default/vms' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <TOKEN>'
```

## Next Steps

* [CLI Quick Start](/orka/quick-start-guides/orka3-cli-quick-start): manage VMs interactively with the Orka3 CLI
* [CI/CD Integrations Quick Start](/orka/quick-start-guides/cicd-integrations-quick-start): automate VM deployment in your build pipeline
* [Tools and Integrations](/orka/orka-overview/tools-integrations): browse available integrations