Skip to main content

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.

​
Setup Commands

​
Test Connectivity

ansible hosts -i /inventory -m ping

​
Check Orka Engine Version

ansible hosts -i /inventory -m shell -a "orka-engine --version"

​
Verify Python Version

ansible hosts -i /inventory -m shell -a "python3 --version"

​
One-Liner Examples

​
Install/Upgrade Orka Engine

ansible-playbook -i /inventory install_engine.yml \
  -e "orka_license_key=YOUR_KEY" \
  -e "engine_url=https://download.url/orka-engine"

​
Plan Deployment (Dry Run)

ansible-playbook -i /inventory deploy.yml \
  -e "vm_name=my-vm" \
  --tags plan

​
Deploy VM

ansible-playbook -i /inventory deploy.yml \
  -e "vm_name=my-vm" \
  -e "vm_image=ghcr.io/macstadium/orka-images/sonoma:latest"

​
Plan Deletion (Dry Run)

ansible-playbook -i /inventory delete.yml \
  -e "vm_name=my-vm" \
  --tags plan

​
Delete VM

ansible-playbook -i /inventory delete.yml \
  -e "vm_name=my-vm"

​
Stop VM

ansible-playbook -i /inventory vm.yml \
  -e "vm_name=my-vm" \
  -e "desired_state=stopped"

​
Start VM

ansible-playbook -i /inventory vm.yml \
  -e "vm_name=my-vm" \
  -e "desired_state=running"

​
Delete Single VM

ansible-playbook -i /inventory vm.yml \
  -e "vm_name=my-vm" \
  -e "desired_state=absent"

​
List All VMs

ansible-playbook -i /inventory list.yml

​
List VMs by Name

ansible-playbook -i /inventory list.yml -e "vm_name=my-vm"

​
Pull Image to All Hosts

ansible-playbook -i /inventory pull_image.yml \
  -e "remote_image_name=ghcr.io/macstadium/orka-images/sonoma:latest"

​
Create and Push Custom Image

ansible-playbook -i /inventory create_image.yml \
  -e "vm_image=ghcr.io/macstadium/orka-images/sonoma:latest" \
  -e "remote_image_name=registry.example.com/custom:v1.0"

​
Create Image with OS Upgrade

ansible-playbook -i /inventory create_image.yml \
  -e "vm_image=base:latest" \
  -e "remote_image_name=registry.example.com/custom:v1.0" \
  -e "upgrade_os=true"

​
Android Virtual Devices

​
Install Android SDK on Hosts

ansible-playbook -i /inventory install_android_sdk.yml
To force reinstallation on hosts where the SDK is already present: 
ansible-playbook -i /inventory install_android_sdk.yml \
  -e "install_android_sdk_force=true"

​
Install SDK Platforms and System Images

ansible-playbook -i /inventory sdkmanager_install.yml
With a specific platform and image types: 
ansible-playbook -i /inventory sdkmanager_install.yml \
  -e "platform=android-34" \
  -e "image_types=default,google_apis,google_apis_playstore"

​
Create an AVD (Plan First)

ansible-playbook -i /inventory deploy_avd.yml \
  -e "vm_name=my-vm" \
  --tags plan

​
Create an AVD

ansible-playbook -i /inventory deploy_avd.yml \
  -e "vm_name=my-vm"
With custom platform, image type, and resources: 
ansible-playbook -i /inventory deploy_avd.yml \
  -e "vm_name=my-vm" \
  -e "platform=android-34" \
  -e "image_type=google_apis" \
  -e "cpu=4" \
  -e "memory=2048"

​
Manage AVD State

# Start AVD
ansible-playbook -i /inventory avd.yml \
  -e "vm_name=my-vm" \
  -e "desired_state=running"

# Stop AVD
ansible-playbook -i /inventory avd.yml \
  -e "vm_name=my-vm" \
  -e "desired_state=stopped"

# Delete AVD (specify index if multiple exist)
ansible-playbook -i /inventory avd.yml \
  -e "vm_name=my-vm" \
  -e "desired_state=absent" \
  -e "avd_index=0"

​
List AVDs

# All AVDs across all hosts
ansible-playbook -i /inventory list_avds.yml

# Filter by VM
ansible-playbook -i /inventory list_avds.yml -e "vm_name=my-vm"

​
Delete AVD by Index

ansible-playbook -i /inventory delete_avd.yml \
  -e "vm_name=my-vm" \
  -e "avd_index=0"

​
Uninstall SDK Platform

ansible-playbook -i /inventory sdkmanager_uninstall.yml

# Target a specific platform
ansible-playbook -i /inventory sdkmanager_uninstall.yml \
  -e "platform=android-34"

​
Common Variable Combinations

​
Deploy with Custom CPU and Memory

ansible-playbook -i inventory deploy.yml \
  -e "vm_name=dev-desktop" \
  -e "vm_image=ghcr.io/macstadium/orka-images/sonoma:latest" \
  -e "cpu=4" \
  -e "memory=8192"

​
Deploy with Network Interface

ansible-playbook -i inventory deploy.yml \
  -e "vm_name=prod-desktop" \
  -e "vm_image=ghcr.io/macstadium/orka-images/sonoma:latest" \
  -e "network_interface=en0"

​
Deploy to Specific Host

ansible-playbook -i inventory deploy.yml \
  -e "vm_name=build-01" \
  -e "vm_image=ghcr.io/macstadium/orka-images/sonoma:latest" \
  --limit mac-node-1

​
Image Creation with Auth

ansible-playbook -i inventory create_image.yml \
  -e "vm_image=base:latest" \
  -e "remote_image_name=registry.company.com/app:v2.0" \
  -e "registry_username=deploy" \
  -e "registry_password=secret" \
  -e "insecure_push=false"

​
Insecure Registry

ansible-playbook -i inventory pull_image.yml \
  -e "remote_image_name=insecure-registry:5000/image:latest" \
  -e "insecure_pull=true"

​
Image Naming Patterns

​
MacStadium Public Images

  • Sonoma: ghcr.io/macstadium/orka-images/sonoma:latest
  • Ventura: ghcr.io/macstadium/orka-images/ventura:latest
  • Monterey: ghcr.io/macstadium/orka-images/monterey:latest

​
Private Registry Format

  • Full path: registry.example.com/organization/repository:tag
  • With port: registry.example.com:5000/orka/image:v1.0

​
VM Naming Convention

VMs are identified individually by name. Use clear, descriptive names:
  • dev-desktop-01, dev-desktop-02
  • prod-build-runner, prod-build-runner-2
  • ci-macOS-sonoma
AVDs are named automatically based on the VM: {vm_name}-avd-0, {vm_name}-avd-1, etc.

​
Ansible Shortcuts

​
Run on Single Host

ansible-playbook -i /inventory <playbook.yml> --limit mac-node-1

​
Dry Run (Check Mode)

ansible-playbook -i /inventory <playbook.yml> --check

​
Verbose Output

# Verbose output
ansible-playbook -i /inventory <playbook.yml> -v

# More verbose output
ansible-playbook -i /inventory <playbook.yml> -vv

# Debug level output
ansible-playbook -i /inventory <playbook.yml> -vvv

​
Run Specific Tags

# Run only tasks tagged with 'configure'
ansible-playbook -i /inventory create_image.yml --tags configure

# Run only tasks tagged with 'push'
ansible-playbook -i /inventory create_image.yml --tags push

​
Skip Tags

ansible-playbook -i /inventory create_image.yml --skip-tags delete

​
Step Through Tasks

ansible-playbook -i /inventory <playbook.yml> --step

​
Best Practices Checklist

​
Planning and Safety

  • Always use --tags plan before production deployments
  • Test playbooks on single host first with --limit
  • Review deployment plan output before executing
  • Verify capacity before large deployments

​
Naming and Organization

  • Use clear, descriptive VM names (e.g., prod-desktop-01, build-runner-sonoma)
  • Version your images with tags (:v1.0, :v2.0, not :latest in prod)
  • Document VM purposes in inventory comments

​
Capacity Management

  • Set appropriate max_vms_per_host limits
  • Monitor disk space on hosts regularly
  • Keep Orka Engine updated across all hosts
  • Track VM distribution across hosts

​
Image Management

  • Place custom configuration scripts in /scripts directory
  • Test image builds in dev before production
  • Keep base images cached on all hosts
  • Implement regular image rebuild schedule

​
Security and Operations

  • Store credentials securely (Ansible Vault)
  • Maintain inventory file accuracy
  • Use SSH keys (not passwords) for host access
  • Rotate credentials regularly
  • Review deployment logs for errors

​
State and Tracking

  • Let Ansible manage VMs (use playbooks, not manual creation)
  • Use list.yml to verify state before changes
  • Keep group vars consistent across environments

​
Support Resources

  • Documentation : MacStadium
  • Support Portal : support@macstadium.com
  • CLI Reference: orka-engine --help
  • VM Commands: orka-engine vm --help
  • Image Commands: orka-engine image --help
  • Project README : Check your repository’s README.md for architecture details