Getting started with your QMI

Once you've signed up and created an account for Quantum Cloud Services, you'll receive access to a dedicated Quantum Machine Image (QMITM). Your QMI comes pre-configured with the Forest SDK to develop hybrid quantum-classical programs, and the QCS command-line interface to easily schedule and manage reservations on Rigetti's quantum devices.

The Forest SDK includes pyQuil (a python library for hybrid quantum-classical programs), the QVM Simulator, and the Quil Compiler. Read the Forest™ SDK documentation to learn more.

When launching your QMI, you will have the option to launch a development environment directly from the web dashboard or add an SSH key to enable SSH access.

getting started

Both these methods will give you access to a JupyterLab Interface that will allow you to explore example notebooks, create new files(jupyter notebooks, python, etc), utilize the CLI, and customize your development environment.

Adding an optional SSH key will allow you to establish a secure shell connection, in addition to your JupyterLab interface, between your local computer and your QMI. Once you're connected, we'll run a simple quantum coin flip program to test that everything's working.

  • Checking for existing SSH keys
    Prior to generating a new SSH key, check to see if you have any existing SSH keys. We love GitHub's guide for this—check it out here.
  • Generating a new SSH key and adding it to the ssh-agent
    If you don't have an existing SSH key, you can generate a new SSH key and add it to the ssh-agent. We love GitHub's guide for this—check it out here. Don't forget to add your SSH key to the ssh-agent.
  • Adding a new SSH key to your QCS account
    To use your new (or existing) SSH key for QCS, you'll need to add it to your QCS account.

    For Mac:
    First, copy your SSH key to your clipboard by opening your terminal, and paste the following command:
    pbcopy < ~/.ssh/

    Note: If you've created a custom filename for your SSH key (i.e. it is not named, then modify the above pbcopy command to match your custom filename.

    For Windows/Linux:
    Locate the hidden .ssh folder, open the file in your favorite text editor, and copy its contents to your clipboard.

    Once you've copied the contents of your file (i.e. your public SSH key) to your clipboard, log in to your QCS Dashboard, and navigate to the Account > SSH Keys page. Paste in your SSH key.

    manage ssh key

  • Connecting to your QMI with SSH
    Once you've successfully generated an SSH key and added it to your QCS account, you're ready to connect to your QMI. 

    1. While logged in to your QCS dashboard, locate the card labeled Quantum Machine ImageQMI

      1. Open your Terminal and ssh into your QMI by typing:

        ssh forest@<QMI_IP_ADDRESS> 

        Note: if you receive the following prompt "Are you sure you want to continue connecting (yes/no)?," then confirm by entering yes.

      2. Congrats! You're now connected to your QMI—you should see the following welcome message in your terminal:

      3. You also now have the ability to power off your QMI right from the console by clicking the "Stop" button in the bottom right corner. You can also power it back on, open Jupyter Notebooks right from the new user interface.

  • Using PuTTY
    For users with older versions of Windows, you may need to use PuTTY to generate an SSH key. We recommend this guide for help doing so.

    Once you've generated an SSH key using PuTTY,  use the following command in your terminal to connect to your Quantum Machine Image:

    putty -ssh forest@<QMI_IP_ADDRESS> 


  • Troubleshooting
    If you encounter a Permission denied issue, try repeating the steps above to generate an SSH key and add it to the ssh-agent.

    If you've renamed your id_rsa and files, you'll need to either revert their names back to the original defaults, or instead of copying the SSH command that's provided in your Dashboard, use the following command instead: 

    ssh -i ~/.ssh/<YOUR_PRIVATE_KEY> forest@<IP-ADDRESS>

    If you continue to encounter issues connecting to your QMI, please contact us at

  • Run your first program
    To execute your first program on your QMI, we will run a simple quantum coin-toss program using the QVM simulator. This program prepares a quantum state which is in an equal superposition of the |0> (heads) and |1> (tails) states on three separate qubits (coins). It uses quantum mechanics to randomly select between heads and tails, similar to flipping a coin.

    This program, with the filename, is already included in the home directory of your QMI (once you've connected to your QMI, type ls -a to list all files).

    To execute it, first launch a virtual environment:

    source ~/.virtualenvs/venv/bin/activate

    Then, simply run:


    You should see an output similar to the following: output
    You can see that 3 qubits (each column) gave random results for this experiment over 10 coin flips (each row).

    If you run this program many times, you will see different random results each time, but the percentage of results which are 0 or 1 will each approach 50%, like a fair coin.

    We invite you to look inside to see how the program was built and executed using pyQuil. We've included verbose comments to explain each step. You can quickly do this with the following command:


    Great! Your QMI is now set up and you've used it to successfully simulate a quantum program. Check out the Forest™ SDK documentation to develop your own program, and then after testing it on the QVM simulator, learn how to use the command-line interface to execute your program on the real quantum hardware. 

  • Moving files to/from your QMI
    Developing programs can be done on your local computer, or on your Quantum Machine Image. Read our guide to learn how to move files to/from your QMI. 

  • Setting up a Jupyter Notebook
    To install and use Jupyter Notebook onto your QMI, check out the instructions in our guide.