Orka3 Cli

Orka3 CLI — Quick Reference

Current Version: 3.5.2 | Support: support@macstadium.com

Essential Context

Orka virtualizes macOS on physical Mac hardware. The CLI (orka3) manages VMs, images, nodes, namespaces, and access control.

Architecture split — Intel (amd64: Mac Pro, Intel Mac mini) and Apple Silicon (arm64: M1–M4 Mac mini, Mac Studio) have different command sets. Intel has power operations (start/stop/suspend/resume/revert), GPU passthrough, and ISO installs. ARM has OCI registry push (vm push), image caching (imagecache), and automatic disk resize.

Auth lifecycle — orka3 login opens a browser and stores a token in ~/.kube/config. User tokens expire in 1 hour. For anything automated (CI/CD, scripts, pipelines), use service accounts: orka3 sa create then orka3 sa token (default: 1 year, or --no-expiration).

Execution contexts — In CI/CD pipelines, use service accounts only (user tokens expire in 1 hour) and pass credentials via CI settings, not export. In Claude Code, the CLI is available — probe the cluster with orka3 node list.

Async operations — vm save, vm commit, vm push, image copy, imagecache add are all async. Check status with orka3 image list , orka3 ic info , or orka3 vm get-push-status.

Shared disk (v3.5.2+) — Attaches a shared disk to VMs on a host. Apple Silicon: 1 VM per node when enabled. Requires Ansible config + per-host first-time formatting (see shared-disk-workflows.md).

Namespace resolution (v3.5.2+) — Priority: --namespace flag > ORKA_DEFAULT_NAMESPACE env var > kubeconfig context > orka-default.

Kubernetes upgrade resilience (v3.6+) — Most orka3 commands continue working during k8s control-plane upgrades. Only login and vm push require the API server; expect failures for those two until the upgrade completes.

Quick CLI Guide

Setup

orka3 config set --api-url 
orka3 login                                    # Browser-based auth
orka3 node list                                # Verify connectivity

Deploy VMs

orka3 vm deploy --image ghcr.io/macstadium/orka-images/sonoma:latest
orka3 vm deploy my-vm --image  --cpu 4 --memory 8
orka3 vm deploy --image  --generate-name           # Unique suffix
orka3 vm deploy --image  --node               # Target node
orka3 vm deploy --image  --tag  --tag-required # Node affinity
orka3 vm deploy --config                         # From VM config
orka3 vm deploy --config  --cpu 6 --memory 16    # Override template

List, Connect & Delete

orka3 vm list                       # All VMs
orka3 vm list my-vm                 # Filter by name
orka3 vm list -o wide               # Extended details (IP, ports, node)
orka3 vm delete 
orka3 vm delete           # Multiple
# Connect: vnc://: (default creds: admin / admin)

Save Work

orka3 vm save        # New image, preserves original
orka3 vm commit                 # Overwrites source image
orka3 vm push  registry/img:tag # Push to OCI registry (ARM only)
# All three are async. Check: orka3 image list 

Images

orka3 image list                    # Local images
orka3 image list              # Filter by name
orka3 image copy          # Async
orka3 image delete 

Image Caching (ARM only)

orka3 ic add  --all                     # All nodes in namespace
orka3 ic add  --nodes ,         # Specific nodes
orka3 ic add  --tags               # Tagged nodes
orka3 ic info                           # Check status

VM Configs (Templates)

orka3 vmc create  --image  --cpu 4 --memory 8
orka3 vmc create  --image  --tag  --tag-required
orka3 vmc list                      # All configs
orka3 vmc list                # Filter by name
orka3 vmc delete 

Disk Resize

orka3 vm resize                                    # ARM: automatic
orka3 vm resize   --user admin --password admin    # Intel: needs SSH

Power Operations (Intel only)

orka3 vm start|stop|suspend|resume|revert 

Nodes

orka3 node list                     # All nodes
orka3 node list               # Filter by name
orka3 node list -o wide             # CPU, memory, tags, VMs
orka3 node tag           # Admin: set affinity tag
orka3 node untag         # Admin: remove tag
orka3 node namespace      # Admin: move node to namespace

Namespaces & Access Control (Admin)

orka3 namespace create orka-
orka3 namespace list
orka3 namespace delete orka-                       # Must be empty first

orka3 rb add-subject --namespace  --user 
orka3 rb add-subject --namespace  --serviceaccount :
orka3 rb list-subjects --namespace 
orka3 rb remove-subject --namespace  --user 

Service Accounts

orka3 sa create                           # In current namespace
orka3 sa create  -n                   # In specific namespace
orka3 sa token                            # 1-year token (default)
orka3 sa token  --duration 24h            # Custom duration
orka3 sa token  --no-expiration           # Never expires
orka3 sa list
orka3 sa delete 

OCI Registry Credentials (Admin)

orka3 regcred add  --username "$USER" --password "$TOKEN"
orka3 regcred list                  # Also: regcred remove 

Output & Flags

-o wide|json|table    # Output format (table is default)
-n         # Override namespace
--generate-name       # Auto-suffix for unique VM names
--timeout    # Deployment timeout (default: 10)

Aliases: vm-config = vmc, serviceaccount = sa, rolebinding = rb, registrycredential = regcred, imagecache = ic

Reference Files

Quick command syntax is above. Load references for complete workflows, detailed troubleshooting, or full flag documentation.

| Query type | File | |------------|------| | VM flags, Intel-only deploy options | references/commands/vm-commands.md | | Image & imagecache flags | references/commands/image-commands.md | | Node management flags | references/commands/node-commands.md | | Namespace, SA, rolebinding flags | references/commands/admin-commands.md | | Config, login, API URLs | references/commands/config-commands.md | | VM config template flags | references/commands/vm-config-commands.md | | Registry credential management | references/commands/registry-commands.md | | CI/CD pipeline setup | references/workflows/cicd-workflows.md | | Golden images, OCI workflows | references/workflows/image-workflows.md | | Multi-namespace, tagging, RBAC | references/workflows/admin-workflows.md | | Batch deployments, optimization | references/workflows/scaling-workflows.md | | Intel → ARM migration, backup | references/workflows/migration-workflows.md | | Shared disk setup, first-time init | references/workflows/shared-disk-workflows.md | | Any auth error or permission issue | references/troubleshooting/auth-issues.md | | Any deployment failure or VM issue | references/troubleshooting/deployment-issues.md | | Async ops stuck, cache issues | references/troubleshooting/image-issues.md | | Screen Sharing, SSH, ports | references/troubleshooting/network-issues.md | | GitLab Custom/Shell executor | references/integrations/gitlab.md | | Packer plugin (image builds) | references/integrations/packer.md | | GitHub Actions (ephemeral runners) | references/integrations/github-actions.md | | Buildkite (ephemeral/permanent agents) | references/integrations/buildkite.md | | TeamCity cloud agent plugin | references/integrations/teamcity.md |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: macstadium
• Source: macstadium/orka3-cli-agent-skill
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.