Cypress 7 EHR Validator Notes

Russell Bateman
October 2023
last update:

Cypress is a repeatable testing tool of Electronic Health Records (EHR) and EHR modules in calculating eCQMs used by CMS's Quality Reporting Programs. The Cypress validator is open source and freely available for use by software development and IT communities including vendors and testing labs. Cypress serves as an official testing tool for EHR Certification program. It is an alternative to the difficult-to-obtain (and costly) validator used by the more government-controlled National Committee for Quality Assurance (NCQA).

Eschewing the older notes I have on Cypress (for versions 5 and 6), I'm starting over for version 7 which I need to validate QRDA for 2023/4. As of 21 September 2023, the latest version is


Important note: When searching for Cypress Validator-related content in your search engine, be aware that there is a community,, related to software testing and unrelated to what we're discussing here. The first three links below (plus my old guide here) is where I base the instructions on this page.


This can be done on Windows, Macintosh OSX and Linux. I'm only concerned with the latter here. I'm using Linux Mint, an Ubuntu, Debian derivative. I have Sun (Oracle) Virtual Box already installed and working. If you're not reading these instructions on the machine you intend the installation on, switch there now.

  1. Begin by reading the page at Cypress 7 VM Install Instructions. You're going to use Virtual Box in this installation.
  2. Download the VM image to use in Virtual Box from Cypress.cypress_7.1.1_Public_VM.ova. I suggest dropping it in your ~/Downloads subdirectory.
  3. I would suggest downloading and installing all the update your machine's OS needs:
    # apt-get update && apt-get upgrade -y && apt-get autoremove && apt-get autoclean
    # apt-get --with-new-pkgs upgrade -y      (if necessary)
    If the Linux kernel was updated, reboot.
  4. Launch VirtualBox and create a new VM. Once launched, click on File → Import Appliance..., then navigate to where you saved the recent download. Follow these instructions:
    1. Launch VirtualBox.
    2. Click Import.
    3. Browse to Cypress.cypress_7.1.1_Public_VM.ova, select it and click Open.
    4. Click Next.
    5. Accept everything except Networking as already configured, click Import and wait for a minute or so.
    6. When control comes back you'll be looking at the summary. You need to change Networking. Be certain to choose Bridged Adapter. When you do, you'll see it find the adapter name the same as you'd see if, in the host OS, you issued the command, ifconfig.
    7. Power on (Start) the new VM.
    8. If you get an error to the effect that you cannot start it, it's probably because your BIOS doesn't have VT-x enabled. Fix that. (See Tirion: VT-x.)
    9. Once your VM is installed, up and running, you can get into it via its very console or, if more convenient, you can ssh into it using these credentials:
      • Username: ubuntu
      • Password: CypressPwd
    10. Once in, obtain and copy the IP address (you'll need it later) of the VM by
      $ ifconfig
      You will probably be prompted that this command doesn't exist. Follow the instructions given in the console to install the missing utility, then try ifconfig again.
    11. vagrant is the host name, but you can make an entry such as this in your development host's /etc/hosts/:	vagrant	crypress

  5. Here end the instructions tried for Cypress 7. I have reached this point successfully.

  6. You can leave your new VM running. Go sign up, by following the link in (either) the Cypress 5 or 6 instructions, with the National Library of Medicine's Unified Medical Language System (UMLS). (You do not need a company's help to do this.)
    1. Click on the Sign Up button.
    2. I clicked Google and used my personal, Google identity.
    3. Follow the instructions.
    4. Eventually, you will be able to Generate an API Key; at that point you'll see a Username and an API Key. Copy down both so that you can enter them later in a sign-in dialog.

  7. Now, return to the Cypress 5 Install Instructions and follow the instruction to install the bundle and setup your application. This reveals a long page of instructions.
    1. Download the bundle of your choice. Click on the link provided, It's here that you'll need that username and API key you copied in an earlier step. (Even though you'd be tempted to use your e-mail address and a password.)
    2. The rest of the instructions for this step appear vague and muddled from this point, so I'll explain differently.
    3. The Cypress VM installed and running is a web server. Launch it from your browser by typing in a new tab its IP address and pressing return. You should see a pleasant photo of cypresses and a sign-in box.
    4. Create a sign-up by clicking the Sign up link, entering an e-mail address, a password and clicking I agree to the above Terms and Conditions. Remember the e-mail address (can be bogus) and password.
    5. Now, turn to the VM console or the ssh session you still have in progress and type:
      $ sudo cypress run rake cypress:add_admin[e-mail]
      [sudo] password for ubuntu: CypressPwd
      where e-mail is the e-mail address you just used (might have been bogus, that's okay). Successful completion of this step will give that (bogus?) e-mail address/user you signed up with administrator privileges.
    6. If you are using the Cypress validator as I am, for de-identified documents in testing, you do not need TLS/SSL or need to change the file /etc/nginx/sites-enabled/default. And, you do not need to restart nginx.
    7. You have finished setting up the Cypress software.

  8. At this point, launch and sign in to the Cypress web interface (from your browser),
    1. Click Remember me, click the (gear icon) Admin tab, then the Bundles tab, then use the + Import Bundle tab to navigate to find the 2Gb zip file you downloaded. This will take a few minutes to complete.
    2. While you're in this interface, you may as well create a vendor. Click Dashboard, then fill out for a new vendor. This can all be bogus. I did this (this is Munsters fodder):
      Vendor Name: Mockingbird Heights Clinic
       Vendor ID : 1313
             URL :
         Address : 1320 Mockingbird Boulevard, Mockingbird Heights
           State : CA
             Zip : 90210
    3. Click Add Vendor.

This sets up your Cypress validator, ready for use.