Access Orka on AWS in a private VPC with SSM

By default, the Orka API on AWS runs inside your VPC and is not accessible from the internet. If your cluster is configured this way, you won’t be able to run orka login or connect to VMs directly from your local machine. Instead, you’ll route that traffic through a bastion (jumpbox) host using AWS Systems Manager (SSM) port forwarding. This guide covers:

Logging in with orka login from a jumpbox
Connecting to a VM via SSH
Connecting to a VM via Screen Share or VNC

This guide applies to Orka on AWS deployments where the Orka API is restricted to private VPC access. If your Orka API is exposed via a public load balancer, you can run orka login directly from your local machine and do not need this guide.

Hybrid clusters

In a hybrid cluster, the Orka control plane runs on Amazon EKS in your AWS account and the Mac nodes run outside AWS, in a MacStadium data center or your own. For Mac nodes at MacStadium, a cloud peering router in each data center connects it to your VPC, and the nodes pull images from a Harbor OCI registry in the same data center. An OCI registry in AWS, such as Amazon ECR, is optional: Harbor can act as a pass-through cache for it, or you can use Harbor as your only registry. Logging in works the same way as in a cluster with EC2 Mac nodes. Connecting to VMs doesn’t use SSM: you connect over the network connection to the data center where the Mac nodes run.

Hybrid Orka cluster. The Orka API server and Orka operator run on Amazon EKS in your AWS account, next to an optional OCI registry such as Amazon ECR and a bastion host for SSM access when the Orka API is private. A cloud peering router connects your VPC to a MacStadium data center, where Apple silicon Mac nodes run the Orka virtual kubelet and Orka Engine to host macOS VMs and Android emulators, and pull images from a Harbor OCI registry, which can cache images from the optional registry. Your team connects to VMs over the private connection.

Prerequisites

Before you start, confirm the following:

Your bastion host has the AmazonSSMManagedInstanceCore IAM policy attached. See IAM Policies in the getting started guide.
The AWS CLI is installed and configured on your local machine.
The AWS Session Manager plugin is installed on your local machine.
The orka CLI is installed on your bastion host.
You have the SSM-managed instance ID of your bastion host.

When the Orka API is private, orka login must run on the jumpbox, not your local machine. The browser-based auth flow still completes in a browser on your local machine, with the two sides connected by an SSM tunnel. Step 1: Open an SSM port forwarding session from your local machine.

aws ssm start-session \
  --target <BASTION_INSTANCE_ID> \
  --document-name AWS-StartPortForwardingSession \
  --parameters '{"portNumber":["51234"],"localPortNumber":["51234"]}'

Replace <BASTION_INSTANCE_ID> with the instance ID of your bastion host (for example, i-0abc123def456789). Leave this terminal session running. Step 2: On your bastion host, run orka login.

orka login

The command outputs a browser URL for the authentication flow. Step 3: Copy that URL and open it in a browser on your local machine. Complete the login in the browser. Once you finish, the orka login session on the jumpbox will confirm authentication.

Connect to a VM via SSH

This section applies only when your Mac nodes are EC2 instances inside the AWS VPC. In a hybrid cluster, VM connections go over the network connection to your Mac nodes, not SSM.

To SSH into a running VM, you need the private IP of the Mac EC2 node running the VM. You can retrieve this from orka vm list. Orka VMs use NAT by default, so you target the node IP, not the VM’s internal IP. Step 1: On your local machine, open an SSM port forwarding session that targets the VM’s private IP.

aws ssm start-session \
  --target <BASTION_INSTANCE_ID> \
  --document-name AWS-StartPortForwardingSessionToRemoteHost \
  --parameters '{"host":["<NODE_PRIVATE_IP>"],"portNumber":["8822"],"localPortNumber":["8822"]}'

Replace <BASTION_INSTANCE_ID> with your bastion instance ID and <NODE_PRIVATE_IP> with the private IP of the Mac EC2 node (for example, 10.0.1.50). The SSH port range for Orka VMs starts at 8822. Step 2: SSH to localhost on the forwarded port.

ssh -p 8822 admin@localhost

The default username for MacStadium base images is admin. If your image uses a different user, substitute accordingly. The process mirrors SSH, using the appropriate port instead. Screen Share (port 5900 and above):

aws ssm start-session \
  --target <BASTION_INSTANCE_ID> \
  --document-name AWS-StartPortForwardingSessionToRemoteHost \
  --parameters '{"host":["<NODE_PRIVATE_IP>"],"portNumber":["5900"],"localPortNumber":["5900"]}'

VNC (port 5999 and above):

aws ssm start-session \
  --target <BASTION_INSTANCE_ID> \
  --document-name AWS-StartPortForwardingSessionToRemoteHost \
  --parameters '{"host":["<NODE_PRIVATE_IP>"],"portNumber":["5999"],"localPortNumber":["5999"]}'

Once the tunnel is open, connect your Screen Share or VNC client to localhost on the forwarded port.

To use Screen Share (port 5900), macOS Screen Sharing must be enabled in the guest VM (System Settings > Sharing > Screen Sharing). For VNC connections on port 5999, the VNC server runs on the host; no guest configuration is required.

Port reference

Service	Default starting port
SSH	8822
Screen Share	5900
VNC	5999

Each port range covers all VMs across a single Mac EC2 node. See Networking and VPC Considerations for the full port ranges.

MacStadium

Orka

MacStadium VDI

IaaS

Access Orka on AWS in a private VPC with SSM

Hybrid clusters

Prerequisites

Connect to a VM via SSH

Port reference

Hybrid clusters

Prerequisites

Log in with orka login

Connect to a VM via SSH

Connect to a VM via Screen Share or VNC

Port reference

Log in with `orka login`