---
url: /quickstart.md
description: >-
  Crash course covering CLI installation, Quantum SDK setup, and running a full
  quantum workflow from development to deployment on Kipu Quantum Hub.
---

# Quickstart

This page provides a crash course on using Kipu Quantum Hub to run an entire quantum workflow, from development to deployment :rocket:.

First of all, [create an account](https://hub.kipu-quantum.com) if you don't have one yet.

:::details TL;DR

To get started quickly, install the CLI and the Quantum SDK in a Python virtual environment:

```bash
npm install -g @quantum-hub/qhubctl
uv add qhub-quantum

qhubctl login -t YOUR_PERSONAL_ACCESS_TOKEN_HERE
```

To run a Qiskit program, all you need is an account and three lines of Quantum code:

```python
from qhub.quantum.sdk import HubQiskitProvider

qiskit_circuit = ...  # create your Qiskit circuit here

# Either use the CLI to log in or set the environment variable KQH_PERSONAL_ACCESS_TOKEN.
provider = HubQiskitProvider()
# Alternatively, you can pass the access token as an argument to the constructor
provider = HubQiskitProvider(access_token="YOUR_PERSONAL_ACCESS_TOKEN_HERE")

result = provider.get_backend("azure.ionq.simulator").run(qiskit_circuit, shots=100).result()
```

You can find more examples and documentation on how to use different backends etc. in the [Quantum SDK documentation](sdk-quantum.md).

:::

## Install the CLI

To install the CLI, you must install Node.js 20 or higher and the
`npm` command line interface using either a [Node version manager](https://github.com/nvm-sh/nvm) or a [Node installer](https://nodejs.org/en/download).

Then install the CLI using `npm`:

```bash
npm install -g @quantum-hub/qhubctl
```

> \[!TIP]
> Take a look at the [CLI reference](cli-reference) for more information on the available commands.

### Login to your account

Copy your [personal access token](https://dashboard.hub.kipu-quantum.com) to your clipboard.

Login to your account using your access token:

```bash
qhubctl login -t <your access token>
```

> \[!TIP]
> If you like to work in the context of an organization you joined on Kipu Quantum Hub, run
> `qhubctl set-context` and select the organization you want to work with.

## Run your first quantum program

The Quantum SDK provides an easy way to develop quantum circuits that can be executed on quantum backends/devices available through Kipu Quantum Hub.
The SDK allows you to use your favorite quantum libraries, such as Qiskit and AWS Braket, to construct circuits and run them on quantum hardware in the cloud.

::: warning IMPORTANT
You need Python 3.11 or higher to use the Quantum SDK.
:::

:::tip
Instead of using your global Python installation, we recommend creating a dedicated Python virtual environment for your quantum projects.

We recommend using [uv](https://docs.astral.sh/uv/) to create and manage Python virtual environments easily.
You can use [venv](https://docs.python.org/3/library/venv.html),
[virtualenv](https://virtualenv.pypa.io/en/latest/), or [conda](https://docs.conda.io/projects/conda/en/stable/) as well.
:::

### Set up a new project \[optional]

This step is optional but recommended to keep your project dependencies isolated.
Create a new directory for your quantum project and navigate into it:

```bash
mkdir ~/my-quantum-project
cd ~/my-quantum-project
```

We recommend using `uv` to create a new virtual environment in the project directory.
This helps to keep your project dependencies isolated from your global Python installation.

If you don't have
`uv` installed, you can install it as described in the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation).

Then create a new Python virtual environment using `uv`:

```bash
uv venv # Create a new virtual environment in the .venv directory
uv init # Initializes a new uv project
```

Activate the virtual environment:

```bash
source .venv/bin/activate
```

### Install the Quantum SDK:

You can install the Quantum SDK using `uv`:

::: tabs key:uvPip
\== uv

```shell
uv add qhub-quantum
```

\== pip

```bash
pip install --upgrade qhub-quantum
```

:::

### Example: Coin Toss

To construct a Qiskit circuit, i.e., a quantum algorithm, that simulates `n` coin tosses on a quantum computer, representing outcomes as zeros `0` and ones `1` instead of heads and tails.
This results in `2^n` possible outcomes, and each measurement (shot) of the quantum state yields one of these possibilities.
To run the circuit on a quantum backend via Kipu Quantum Hub, we use the `HubQiskitProvider` from our Quantum SDK.
This Qiskit provider connects to Kipu Quantum Hub, enabling execution of quantum circuits on supported devices.
Learn more about Qiskit [here](https://qiskit.org/).

> \[!TIP]
> We recommend using the CLI to log in and authenticate with Kipu Quantum Hub.
> Then, you can use the `HubQiskitProvider` without specifying the access token:
>
> ```python
> provider = HubQiskitProvider()
> ```

Add the following code to a new Python file, e.g., `coin_toss.py`:

```python
from qhub.quantum.sdk import HubQiskitProvider
from qiskit import QuantumCircuit, transpile

n_coin_tosses = 2

circuit = QuantumCircuit(n_coin_tosses)
for i in range(n_coin_tosses):
    circuit.h(i)
circuit.measure_all()

# Use qhubctl and log in with "qhubctl login" or set the environment variable KQH_PERSONAL_ACCESS_TOKEN.
# Alternatively, you can pass the access token as an argument to the constructor
provider = HubQiskitProvider()
### If you do not want to log in using the CLI, you can also provide your personal access token directly here:
# provider = HubQiskitProvider(access_token="YOUR_PERSONAL_ACCESS_TOKEN_HERE")

# Select a quantum backend suitable for the task. All KQH supported quantum backends are
# listed at https://hub.kipu-quantum.com/quantum-backends.
backend = provider.get_backend("azure.ionq.simulator")

# Transpile the circuit ...
circuit = transpile(circuit, backend)
# ... and run it on the backend
job = backend.run(circuit, shots=100)

counts = job.result().get_counts()

print(counts)
```

You can run the program like this:

```bash
python coin_toss.py
```

A possible outcome of the coin toss quantum algorithm could be:

```json
{
  "00": 23,
  "01": 22,
  "10": 29,
  "11": 26
}
```

> \[!TIP]
> We have prepared a Jupyter notebook that you can use to immediately run the Quantum Coin Toss example:
> Navigate to the [notebooks/coin\_toss.ipynb](https://dashboard.hub.kipu-quantum.com/community/implementations/1a0ae675-4b23-405c-af8e-f4189ff14e0f)

> \[!IMPORTANT]
> Access to IonQ's quantum simulator (`azure.ionq.simulator`) is free of charge.
> Other backends/devices requires an account with active payment information.

## Create your first Service project

Create a new project by running the following command:

```bash
qhubctl init
```

You will be prompted to provide some information about your project.
For this quickstart, select the following configuration:

* **Service name**: `my-project`
* **Starter template**: `Python Starter`
* **vCPU configuration**: `1 vCPU`
* **Memory configuration**: `1GB`

This will create a new directory called `my-project` containing all required files to run your quantum code on Kipu Quantum Hub.
The `Python Starter` templates implement the coin toss example from above as a Service.

Note the `qhub.json` file in the project directory, which contains the project configuration, for example:

```json
{
  "name": "my-project",
  "descriptionFile": "README.md",
  "resources": {
    "cpu": 1,
    "memory": 1
  },
  "runtime": "PYTHON_TEMPLATE"
}
```

> \[!TIP]
> For more information on the bootstrapped project structure, see the `README.md` file in the project directory.

### Test your service locally

Let's test your service locally before deploying it to Kipu Quantum Hub.
First, switch to your project directory:

```bash
cd my-project
```

Then, install the required dependencies.
We recommend creating a dedicated Python environment to install and track all required packages from the start.
You may use the `requirements.txt` file to create a virtual environment with the tooling of your choice.

For example, you can use `uv` to create a virtual environment and install the required packages:

```bash
uv venv
uv sync

source .venv/bin/activate
```

Open the `src/program.py` file, modify the following line and enter your personal access token:

```python
provider = HubQiskitProvider(access_token="YOUR_PERSONAL_ACCESS_TOKEN_HERE")
```

Finally, run your service locally:

```bash
python -m src
```

The output should look like this:

```json
{
  "counts": {
    "000": 6,
    "001": 13,
    "010": 19,
    "011": 18,
    "100": 8,
    "101": 14,
    "110": 8,
    "111": 14
  },
  "elapsed_time": 17.837932109832764
}
```

### Test your service locally using qhubctl

To begin, navigate to your project directory:

```bash
cd my-project
```

Next, run the following command:

```bash
qhubctl serve
```

Once the server is operational, you can access <http://localhost:8081/docs>.
This interface provides you the ability to run your current code and see the results.
Further information can be found in the [qhubctl reference](cli-reference#qhubctl-serve).

Open the `POST /` operation and click on the "Try it out" button.
Paste the following JSON into the request body field:

```json
{
  "data": {
    "n_coin_tosses": 2
  }
}
```

Click on the "Execute" button to run the service.
The response body will contain the ID of the service execution.
Copy the ID to your clipboard.

Open the `GET /{id}` operation and click on the "Try it out" button.
Paste the ID into the `id` field and click on the "Execute" button.
You can use this endpoint to check the status of the service execution.
If the status is `SUCCEEDED`, you can retrieve the result.

Open the `GET /{id}/result` operation and click on the "Try it out" button.
Paste the ID into the `id` field and click on the "Execute" button.
The response body will contain the result of the service execution, similar to this:

```json
{
  "counts": {
    "10": 30,
    "11": 25,
    "00": 24,
    "01": 21
  },
  "elapsed_time": 11.129297733306885,
  "_links": {
    "status": {
      "href": "/5b25134c-dd05-47a0-9c12-ff9816074936"
    }
  },
  "_embedded": {
    "status": {
      "id": "5b25134c-dd05-47a0-9c12-ff9816074936",
      "status": "SUCCEEDED",
      "created_at": "2025-03-24 11:16:20",
      "started_at": "2025-03-24 11:16:20",
      "ended_at": "2025-03-24 11:16:32"
    }
  }
}
```

Press Ctrl+C to stop the local server.

### Deploy your service

To deploy your service to Kipu Quantum Hub, run the following command in your project directory:

```bash
qhubctl up
```

This will compress your project directory and upload it.
After a successful deployment, you will find the service in the [Services](https://dashboard.hub.kipu-quantum.com/services) section.

Alternatively, you can create a ZIP file of your project and upload it manually to the platform:

```bash
qhubctl compress
```

Both commands, `qhubctl up` and `qhubctl compress` consider the definitions from the
`.dockerignore` file to exclude files and directories from being uploaded or compressed.

### Execute your service

Execute your service with the example input data stored in `input/data.json` and `input/params.json` by running the following command:

```bash
qhubctl run 
```

After a successful execution, the output should look like this:

```
Running Job (a7a3422b-9522-408b-96c9-32cdb497b12b)... Job succeeded.
See result at https://dashboard.hub.kipu-quantum.com/jobs/a7a3422b-9522-408b-96c9-32cdb497b12b
```

For more details and options of the `qhubctl run` command, see the [CLI reference](cli-reference#qhubctl-run-serviceid).

## What's next?