Starting a Jupyter Notebook

The instructions below will walk you through the process of launching a Jupyter Server workflow using the Fuzzball workflow catalog. The workflow catalog will help you generate, validate, and submit a Fuzzfile which runs a Jupyter Notebook. By default, this workflow uses a Jupyter container from quay.io.

You can start this workflow using either the web UI or the CLI.

select

Please select either the web UI or CLI tab to see the appropriate instructions for your environment.

web UI

If you click “Workflow Catalog”, you will see a page of workflow templates you use to create fuzzfiles and launch workflows. Using the search bar, find the “Jupyter Server” tile with the CIQ badge and click “Run”.

Fuzzball workflow catalog Jupyter Notebook template tile

You will be prompted with a pop-up showing template parameters which you can modify. If you’d like to accept the default values, you can click “Run” which will validate the Fuzzfile generated using the input specified.

Jupyter Notebook template continue with workflow submission

You will then be prompted to provide an optional descriptive name for your workflow.

Jupyter Notebook template workflow name prompt

Now you can click on “Start Workflow” and your workflow will be submitted. If you click “Go to Status” in the following dialog you can view the workflow status page. The screenshot below shows the status page for a Jupyter Notebook workflow submission.

Fuzzball workflow status page

To retrieve logs produced by this workflow, select the jupyter job within the workflow, and click the “Logs” option on the right.

Fuzzball workflow dashboard showing logs from the jupyter job

CLI

To run this workflow through the CLI you will need access to the Fuzzball CLI. You can install it using the Fuzzball CLI installation instructions.

First, you can create a values file values.yaml to populate the Jupyter Server workflow template using the command below. You can modify the parameters to your desired values or use the defaults below.

$ cat >values.yaml<<EOF
values:
  - name: "Type"
    string_value: "r"
  - name: "Cores"
    uint_value: 1
  - name: "Memory"
    string_value: "4GiB"
  - name: "GPUs"
    uint_value: 0
  - name: "Exclusive"
    bool_value: false
  - name: "Volume"
    string_value: "volume://user/persistent"
  - name: "ServiceScope"
    string_value: "user"
EOF

Next, you will need to find the workflow template ID. The command below lists workflow templates provided by CIQ. Note that the workflow-template ID may be different in your Fuzzball cluster.

$ fuzzball workflow-template list -f 'provider: "CIQ" AND name: "Jupyter"'
NAME           | ID                                   | OWNER    | PROVIDER | UPDATETIME            | DISABLED
Jupyter Server | f94e0a09-8d20-52da-b69d-825ab4824ded | PROVIDER | CIQ      | 2026-03-12 07:14:35PM | false

You can start a workflow with the workflow template ID and the values file (values.yaml) we created in the first step using the command below.

$ fuzzball workflow-template start --values values.yaml f94e0a09-8d20-52da-b69d-825ab4824ded
Workflow "0345befe-32b0-42c1-9b82-03d3d1c38434" started.

You can monitor the workflow’s status by running the following command:

$ fuzzball workflow describe 0345befe-32b0-42c1-9b82-03d3d1c38434
Name:      jupyter test
Email:     wresch@ciq.com
UserId:    87145648-b830-4291-ab7e-40880d61334e
Status:    STAGE_STATUS_STARTED
Cluster:   fuzzball-aws-stable
Created:   2026-04-06 12:55:25PM
Started:   2026-04-06 12:55:26PM
Finished:  N/A
Error:

Stages:
KIND     | STATUS   | NAME                                       | STARTED               | FINISHED              | PERSISTENT VOLUME | VOLUME REFERENCE
Workflow | Started  | 0345befe-32b0-42c1-9b82-03d3d1c38434       | 2026-04-06 12:55:26PM | N/A                   |                   |
Volume   | Finished | data                                       | 2026-04-06 12:55:26PM | 2026-04-06 12:55:28PM | true              | volume://user/persistent
Image    | Finished | docker://quay.io/jupyter/r-notebook:latest | 2026-04-06 12:55:26PM | 2026-04-06 12:57:25PM |                   |
Service  | Started  | jupyter                                    | 2026-04-06 12:59:22PM | N/A                   |                   |

You can view outputs logged by the workflow, by executing the following command:

$ fuzzball workflow log 0345befe-32b0-42c1-9b82-03d3d1c38434 jupyter
...
[I 2026-04-06 16:59:31.968 LabApp] JupyterLab extension loaded from /opt/conda/lib/python3.13/site-packages/jupyterlab
[I 2026-04-06 16:59:31.968 LabApp] JupyterLab application directory is /opt/conda/share/jupyter/lab
[I 2026-04-06 16:59:31.969 LabApp] Extension Manager is 'pypi'.
[I 2026-04-06 16:59:32.071 ServerApp] jupyterlab | extension was successfully loaded.
[I 2026-04-06 16:59:32.092 ServerApp] nbclassic | extension was successfully loaded.
[I 2026-04-06 16:59:32.096 ServerApp] notebook | extension was successfully loaded.
[I 2026-04-06 16:59:32.097 ServerApp] Serving notebooks from local directory: /data
[I 2026-04-06 16:59:32.097 ServerApp] Jupyter Server 2.17.0 is running at:
[I 2026-04-06 16:59:32.097 ServerApp] http://jupyter:27760/endpoints/accounts/b95f6f1b-1c70-491f-b83c-24eb89382f29/workflows/0345befe-32b0-42c1-9b82-03d3d1c38434/jupyter/jupyter/lab
[I 2026-04-06 16:59:32.097 ServerApp]     http://127.0.0.1:27760/endpoints/accounts/b95f6f1b-1c70-491f-b83c-24eb89382f29/workflows/0345befe-32b0-42c1-9b82-03d3d1c38434/jupyter/jupyter/lab
[I 2026-04-06 16:59:32.097 ServerApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).
[I 2026-04-06 16:59:33.338 ServerApp] Skipped non-installed server(s): basedpyright, bash-language-server, dockerfile-language-server-nodejs, javascript-typescript-langserver, jedi-language-server, julia-language-server, pyrefly, pyright, python-language-server, python-lsp-server, r-languageserver, sql-language-server, texlab, typescript-language-server, unified-language-server, vscode-css-languageserver-bin, vscode-html-languageserver-bin, vscode-json-languageserver-bin, yaml-language-server

Currently you need to use the UI to access the service endpoints.