Skip to main content
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 orka3 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 orka3 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 orka3 login directly from your local machine and do not need this guide.

​
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 orka3 CLI is installed on your bastion host.
  • You have the SSM-managed instance ID of your bastion host.

​
Log in with orka3 login

When the Orka API is private, orka3 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 orka3 login. 
orka3 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 orka3 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. For hybrid deployments (EKS on AWS + on-premises Mac nodes), VM connections go through your on-premises network, 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 orka3 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.

​
Connect to a VM via Screen Share or VNC

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

ServiceDefault starting port
SSH8822
Screen Share5900
VNC5999
Each port range covers all VMs across a single Mac EC2 node. See Networking and VPC Considerations for the full port ranges.