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, you pass the token as the enrollment_token variable when you register each VM in Step 4. The VDI | Register Citrix VDA template in the management UI prompts for it each time you run it, and on the CLI you pass it at run time with -e. The playbooks don’t read the token or your customer ID from any stored file, so keep the token in your password manager until you’ve registered every machine. If you’re on bare metal Mac, store the token in your password manager and enter it in the VDA installer in Step 4.

​
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 Orka Engine doesn’t save the network interface with the VM, so pass network_interface every time you deploy or start a VM.
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:
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:

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

​
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

The VDA runs inside the macOS VM (or on the bare metal Mac), not on the Orka host, so check it on the machine itself. For an Orka VM, find its IP with ansible-playbook -i dev/inventory list.yml -e "vm_name=<VM_NAME>", then SSH into the VM. On a bare metal Mac, SSH into the Mac directly. Check the service status:
Restart it with:
Don’t run these through ansible -i dev/inventory all. The inventory lists only the Mac hosts, so the commands would run on the hosts, where the VDA isn’t installed.

​
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 and re-register. On Orka VM, re-run register_citrix_vda.yml (management UI: VDI | Register Citrix VDA) with the new enrollment_token; you don’t need to redeploy the VM. On bare metal Mac, see Step 4.
  • 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.