Skip to main content
Complete these steps in order. VMs must be deployed with bridged networking, have Citrix VDA installed, and be registered in a Machine Catalog before you assign users to a Delivery Group. Doing these out of order prevents sessions from launching.

​
Before you begin

You need:
  • An active Citrix DaaS subscription (Standard tier or above)
  • Admin access to Citrix Cloud Console
  • Your Citrix Cloud customer ID (visible in the Cloud Console)
  • At least one Orka VM deployed with bridged networking (network_interface=en0). See Getting Started: MSDC-Hosted or Getting Started: Self-Hosted if you haven’t done this yet.
  • sshpass installed on your Ansible runner (required by the VDA playbooks)

​
Step 1: Create a Machine Catalog

Machine Catalogs are logical groupings of VMs in Citrix. Because Apple’s licensing requirements mean Citrix treats each Mac as a physical device, use the Remote PC Access catalog type.
  1. In Citrix Cloud Console, go to Web Studio → Machine Catalogs.
  2. Click Create Machine Catalog.
  3. Select Remote PC Access.
  4. Under machine power management, select Machines that are not power managed. Orka manages the VM lifecycle.
  5. Set the session type to Single-session.
  6. For user assignment, choose based on your use case:
    • Random (pooled): users get any available desktop (non-persistent)
    • Static (dedicated): users get the same desktop each session (persistent)
  7. For non-domain-joined Macs, select No, do not add to Active Directory.
  8. Name the catalog using a pattern that reflects the OS version, hardware profile, and purpose. For example: Orka-macOS-Sequoia-Standard-Engineering.
  9. Skip adding machines for now. VMs register automatically using the enrollment token after VDA is installed.

​
Step 2: Generate an enrollment token

The enrollment token authenticates VDA registration and associates each VM with your Machine Catalog.
  1. In Web Studio, go to Machine Catalogs and select the catalog you just created.
  2. Click Enable Enrollment Token.
  3. Give the token a descriptive name (for example, Orka-Finance-2026-Q2).
  4. Set an expiration that covers your deployment window.
  5. Copy the token immediately. It’s shown only once. If you lose it, generate a new one.
Store the token in your Ansible Vault: 
vault_citrix_enrollment_token: "your-token-here"
vault_citrix_customer_id: "YOUR_CUSTOMER_ID"

​
Step 3: Install Citrix VDA

VMs must be running with bridged networking before you install VDA. VMs on NAT networking can’t be reached directly by Citrix Cloud or end users. You can’t change the network mode after a VM is deployed.
We recommend hosting the Citrix VDA .dmg in an S3 bucket with a presigned URL. The playbook downloads it directly to the VM. From the management UI, run the VDI | Install Citrix VDA template. Or run from the CLI: 
ansible-playbook -i inventory install_citrix_vda.yml -e "vm_name=<vm_name>" -e "vm_username=<admin_username>" -e "vm_password=<admin_password>" -e "citrix_installer_url=<citrix_dmg_url>" -e "hostname_suffix=<domain_suffix>"
VariableDescription
vm_nameExact name of the running VM. Also used as the VM hostname.
citrix_installer_urlDownload URL for the Citrix VDA .dmg.
hostname_suffixDomain suffix appended to vm_name to form the full hostname (for example, corp.example.com). Leave blank to use the VM name alone.
The playbook installs .NET runtime prerequisites, sets the VM hostname, downloads and installs the VDA package, grants required TCC permissions, and reboots the VM. Wait for the reboot to complete before continuing to Step 4.

​
Building VDA into a golden image

For fleet deployments, build VDA into your golden image instead of installing it per VM. Add your VDA install script to the /scripts directory and run create_image.yml. VMs deployed from that image have VDA pre-installed and only need to be registered. See Image management for the full build workflow.

​
Step 4: Register the VDA

After the VM reboots, register it with Citrix Cloud using the enrollment token. From the management UI, run the VDI | Register Citrix VDA template. Or run from the CLI: 
ansible-playbook -i inventory register_citrix_vda.yml -e "vm_name=<vm_name>" -e "vm_username=<admin_username>" -e "vm_password=<admin_password>" -e "enrollment_token=<enrollment_token>"

​
Step 5: Verify registration

After registration, the VM should appear in your Machine Catalog within a few minutes.
  1. In Web Studio, go to Machine Catalogs and select your catalog.
  2. Confirm the VM appears with Registration state: Registered and Power state: On.
If the VM doesn’t appear, check the VDA logs on the VM: 
/Library/Application Support/Citrix/VDA/Logs/

​
Step 6: Configure a Delivery Group

Delivery Groups control which users can access which machines and define session policies.
Complete Steps 3-5 for all VMs before assigning users. Users assigned to a Delivery Group with no registered machines can’t launch sessions.
  1. In Web Studio, go to Delivery Groups and click Create Delivery Group.
  2. Select the Machine Catalog from Step 1 and specify how many machines to include.
  3. Name the group descriptively, for example: Finance-macOS-VDI.
  4. Set the display name users see in Citrix Workspace.
  5. Select Published Desktop as the delivery type.
  6. Configure session policies: timeout, idle behavior, and reconnection rules.
  7. Once your VMs show as Registered in Step 5, add the users or groups who should have access.
Authentication options:
  • Active Directory users or groups (domain-joined environments)
  • Azure AD, Okta, or other SAML providers
  • Individual user accounts
Multiple Delivery Groups from one catalog: You can create multiple groups from the same catalog to manage access granularly. For example, a standard group and a power-user group with different session policies, both drawing from the same pool of Mac hosts.

​
Rendezvous protocol

Rendezvous enables HDX connections from non-domain-joined VDAs to Citrix Cloud without an on-premises StoreFront or NetScaler Gateway. The VDA opens an outbound WebSocket connection to Citrix Gateway Service, so no inbound ports are required on the VM. Rendezvous is enabled by default in Citrix DaaS environments with non-domain-joined machines. To verify or configure it:
  1. In Web Studio, go to Configuration → Policies.
  2. Edit or create a policy for your Delivery Group.
  3. Under ICA/HDX settings, confirm:
    • Rendezvous Protocol: enabled
    • HDX Adaptive Transport: Preferred
    • WebSocket connections: allowed
Network requirement: VMs need outbound access to *.*.nssvc.net on TCP/UDP 443. No inbound ports are required on the VM.

​
Troubleshooting

​
VM doesn’t appear in the Machine Catalog

  • Check that the enrollment token hasn’t expired and was copied without truncation.
  • Confirm outbound HTTPS (TCP 443) is allowed from the VM to *.xendesktop.net and *.*.nssvc.net.
  • Confirm the token is associated with the correct Machine Catalog.
  • Check VDA logs at /Library/Application Support/Citrix/VDA/Logs/.

​
VDA service not running

Check the service status: 
ansible -i inventory all -m shell -a "sudo launchctl list | grep citrix"
Restart the service: 
ansible -i inventory all -m shell -a "sudo launchctl kickstart -k system/com.citrix.vda"

​
Rendezvous connections failing

  • Confirm outbound access to *.*.nssvc.net:443 from the VM.
  • Check whether an HTTP proxy is blocking WebSocket traffic.
  • Review VDA logs for Rendezvous registration errors.
  • Verify the Citrix Workspace app version is 2402 or later on client machines.

​
Token errors

  • Expired token: generate a new token in Web Studio, update your Vault, and re-run register_citrix_vda.yml.
  • Wrong Machine Catalog: verify the token is associated with the correct catalog in Web Studio.
  • Customer ID mismatch: confirm the customer ID matches your Citrix Cloud tenant.