qruise flow deploy¶

Submit or update a persistent flow deployment.

Syntax¶

qruise flow deploy [OPTIONS]

qruise flow deploy update [OPTIONS]

Description¶

The qruise flow deploy command creates a persistent deployment in QruiseOS. A deployment packages the flow and its execution defaults so it can be triggered from the dashboard, from the CLI, or by one or more schedules.

Use qruise flow deploy update to update an existing deployment using the same options.

Deployments created with qruise flow deploy run on the QruiseOS infrastructure. To keep a deployment served from the current Python environment instead, use qruise flow serve.

Actions¶

Action	Description
(default)	Create a deployment.
`update`	Update an existing deployment.

Options¶

Option	Description
`-f, --flow-file`	Path of the flow definition file for scheduling the flow. Default: `qruise-flow.yaml`.
`-b, --branch`	The knowledge base branch to be used by the flow. Can also be set using the `QRUISE_FLOW_DEFAULT_INTEGRATION_BRANCH` env variable.
`-m, --no-merge`	If specified, the flow results will not be merged to the integration branch.
`-q, --qubits`	Limit the flow run to only specified qubits. If no qubits are specified, all qubits defined in the flow file will be used. Must have the list format.
`-s, --start`	Execute only notebooks with ordinal numbers greater than or equal to the number specified.
`-e, --end`	Execute only notebooks with ordinal numbers less than or equal to the number specified.
`-c, --concurrency`	Specify maximum number of tasks executing in parallel. Default: 4.
`-i, --interval`	Interval at which the flow should be run. Cannot be specified at the same time as `--schedule`. The value must be a string consisting of a numeral and a unit without whitespaces, e.g. `45m` (every 45 minutes) or `3h` (every 3 hours). Allowed unit values are `m`, `h`, and `d` for minutes, hours, and days, respectively.
`--schedule`	Schedule on which the flow should be run, in a cron-like format. Cannot be specified at the same time as `--interval.`
`-z, --time-zone`	Specify time zone for the cron schedule in a tz database format{:target="blank"}. If specified, `--schedule` must also be provided. Default:_ `UTC`
`--image`	Docker base image tag to be used. In the QruiseOS Jupyter container, `QRUISE_FLOW_IMAGE` is already set.
`--tag`	Version of the Docker image to be used. If specified, `--image` option must also be present.
`-n, --no-build`	If specified, the provided image will be used as-is and pulled at runtime.
`--prepare`	If specified, the flow is prepared but no further action is taken. Use for testing.
`--no-clean-up`	Keep the generated build directory after the command finishes.
`-x, --inplace`	If specified, the flow is prepared for execution in the same directory and not copied. Cannot be specified at the same time as `--output-dir`. Can be used for special cases for containerized deployment.
`-o, --output-dir`	Specifies path of the build directory for the flow, where `qruise` prepares it for scheduling or execution. Cannot be specified at the same time as `--inplace`. Default: `.qruise/build/<DATE_TIME>`.
`--help`	Show a help message and exit.

Environment variables¶

Variable	Description
`QRUISE_FLOW_DEFAULT_INTEGRATION_BRANCH`	Default knowledge base branch to be used by the flow. See the `--branch` option.
`QRUISE_FLOW_SKIP_MERGE`	If set to `True`, the results will not be merged to the integration branch by default. See the `--no-merge` option.
`QRUISE_FLOW_CRON_SCHEDULE`	Default schedule to be used by the flow. See the `--schedule` option for details and limitations. Cannot be set at the same time as `QRUISE_FLOW_INTERVAL_SCHEDULE`.
`QRUISE_FLOW_INTERVAL_SCHEDULE`	Default interval to be used by the flow. See the `--interval` option for details and limitations. Cannot be set at the same time as `QRUISE_FLOW_CRON_SCHEDULE`.
`QRUISE_FLOW_IMAGE`	Default Docker base image tag to be used. Already set in the QruiseOS Jupyter container.

Examples¶

Scheduling a nightly calibration run¶

Regular calibration of the QPU is crucial for smooth and high-fidelity operation. When you finish the development of your calibration flow (and test it using the qruise flow run command), you can schedule it using a single Qruise CLI command.

Suppose your flow file is located in $HOME/flows/my-flow.yaml and you want it to run every day at 1:00 UTC during a daily downtime window. To achieve that, run (using the same cron-like format to define the time):

qruise flow deploy --flow-file $HOME/flows/my-flow.yaml --schedule "0 1 * * *"

In this case, you don't need to specify the time zone as UTC is the default. However, if your device is located in a different time zone, you can specify it using the --time-zone option. For instance, if you operate from Berlin, Germany, you can run:

qruise flow deploy --flow-file $HOME/flows/my-flow.yaml --schedule "0 1 * * *" --time-zone Europe/Berlin

Modifying flow parameters¶

When you schedule a flow, it will use parameter values as defined in the flow definition file. To change them, you can modify the flow file, but sometimes it's desirable to change them during scheduling without actually touching the flow file. For this reason, qruise flow deploy allows you to override certain parameters, as described by the following table:

Parameter	Command line option
qubits	`-q, --qubits`
start position	`-s, --start`
end position	`-e, --end`
KB intergration branch	`-b, --branch`
skip merging results	`-m, --no-merge`

See the Options section for a detailed description of each parameter.

As an example, assume you have a flow file my-flow.yaml located in your current working directory, which has the following features:

four different qubits: Q1, Q2, Q3, and Q4
experiments with ordinal numbers 10 to 80

Now let's assume you want to schedule this flow but want it to:

run for Q1 and Q4 qubits only
run only experiments numbered 15 to 75

You can achieve this by running

qruise flow deploy --flow-file ./my-flow.yaml --qubits Q1,Q4 --start 15 --end 75

Range specification

The range specified by --start and --end is inclusive on both ends. Thus, passing --start 15 and --end 75 will result in both notebooks 15 and 75 being executed (as well as everything in between).

Customising Docker image¶

Similarly to changing flow parameter default values, you might want to change the Docker image used as a base for building the flow container or its version. By default, deployment uses the same base image as local execution with qruise flow run, which is QRUISE_FLOW_IMAGE (already set in the QruiseOS Jupyter container). To change the base image, you can use the --image option when you want to run the flow in an older QruiseOS environment.

qruise flow deploy --flow-file ./my-flow.yaml --image jupyterhub/jupyterhub --tag 2025.04.00

where we assumed that the flow file is located in ./my-flow.yaml. Similarly, if you wanted to switch the base from ubuntu to, say, jupyterhub/jupyterhub, you can achieve it with the following:

qruise flow deploy --flow-file ./my-flow.yaml --image jupyterhub/jupyterhub

Persistent flow deployment¶

For deployment, the flow folder and all user-installed libraries are stored in the QruiseOS store. When the deployment is triggered from the dashboard or a schedule, QruiseOS creates a container, copies the source code, and executes it.

qruise flow deploy --flow-file $HOME/flows/my-flow.yaml --schedule "0 1 * * *"

--schedule or --interval options can be omitted if you want to trigger the flow manually from the Dashboard. In this case, the flow will be deployed but not scheduled for execution.

Updating an existing deployment¶

To update a deployment definition, use the update action:

qruise flow deploy update --flow-file $HOME/flows/my-flow.yaml --schedule "0 */6 * * *"