Skip to main content
Complete these steps in order. Machines must 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)
  • One of the following, depending on your deployment:

​
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, and bare metal Mac hosts aren’t power managed by Citrix either.
  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 and bare metal hosts 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.
If you’re on Orka VM, store the token in your Ansible Vault: 
vault_citrix_enrollment_token: "your-token-here"
vault_citrix_customer_id: "YOUR_CUSTOMER_ID"
If you’re on bare metal Mac, there’s no Ansible Vault. Store the token in your password manager instead.

​
Step 3: Install Citrix VDA

Machines must be reachable over the network before you install VDA. Orka VMs on NAT networking can’t be reached directly by Citrix Cloud or end users, and 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 machine 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 machine appears with Registration state: Registered and Power state: On.
If it doesn’t appear, check the VDA logs: 
/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 through 5 for all machines 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 machines 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. 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: machines need outbound access to *.*.nssvc.net on TCP/UDP 443. No inbound ports are required.

​
SSO authentication

By default, users authenticate through Citrix Workspace and then see a macOS login screen. With SSO enabled on the VDA, Workspace credentials pass through to macOS automatically and the user lands directly in their desktop. A few things to know before enabling it:
  • Username and password only. FAS, smart cards, and passwordless providers are not supported.
  • The macOS account credentials must match the user’s Workspace credentials exactly.
  • SSO conflicts with Jamf Pro/Connect and other tools that customize the macOS login process. If your machines are managed that way, SSO won’t work.
  • The Allow users not in Active Directory to use this delivery group checkbox must be unchecked on the Delivery Group.
For setup steps, see SSO Authentication in the Citrix VDA for macOS documentation.

​
Troubleshooting

​
Machine 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 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

On Orka VM, check the service status through Ansible: 
ansible -i inventory all -m shell -a "sudo launchctl list | grep citrix"
Restart it with: 
ansible -i inventory all -m shell -a "sudo launchctl kickstart -k system/com.citrix.vda"
On bare metal Mac, run the same launchctl commands directly on the host over SSH; there’s no Ansible layer in between.

​
Rendezvous connections failing

  • Confirm outbound access to *.*.nssvc.net:443 from the machine.
  • 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 (Orka VM) or password manager (bare metal Mac), and re-register.
  • 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.