> This page is for Self-Hosted, version v3.0 (default).
> For other versions, use one of these documentation indexes:
> - v3.0 (default): https://docs.nvidia.com/run-ai/self-hosted/v3.0/llms.txt
> - v2.26: https://docs.nvidia.com/run-ai/self-hosted/v2.26/llms.txt
> - v2.25: https://docs.nvidia.com/run-ai/self-hosted/v2.25/llms.txt
> - v2.24: https://docs.nvidia.com/run-ai/self-hosted/v2.24/llms.txt
> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/run-ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/run-ai/_mcp/server.
# Launching Workloads with GPU Memory Fractions
This quick start provides a step-by-step walkthrough for running a Jupyter Notebook workspace using [GPU memory fractions](/run-ai/self-hosted/documentation/platform-management/runai-scheduler/resource-optimization/gpu-fractions/memory-fractions).
NVIDIA Run:ai’s GPU memory fractions provide an agile and easy-to-use method to share a GPU or multiple GPUs across workloads. With GPU memory fractions, you can divide the GPU memory into smaller chunks and allocate each chunk to a different workload, resulting in higher GPU utilization and more efficient resource allocation. How those workloads share the GPU compute is set separately — refer to [GPU compute modes](/run-ai/self-hosted/documentation/platform-management/runai-scheduler/resource-optimization/gpu-fractions/compute-modes).
## Prerequisites
Before you start, make sure:
* You have created a [project](/run-ai/self-hosted/documentation/platform-management/manage-ai-initiatives/organization/projects) or have one created for you.
* The project has an assigned quota of at least 0.5 GPU.
**Note**
Flexible workload submission is enabled by default. If unavailable, contact your administrator to enable it under **General settings** → Workloads → Flexible workload submission.
## Step 1: Logging In
Browse to the provided NVIDIA Run:ai user interface and log in with your credentials.
Run the below --help command to obtain the login options and log in according to your setup:
```sh
runai login --help
```
To use the API, you will need to obtain a token as shown in [API authentication](/run-ai/self-hosted/reference/rest-api/getting-started/how-to-authenticate-to-the-api).
## Step 2: Submitting a Workspace
1. Go to the Workload manager → Workloads
2. Click **+NEW WORKLOAD** and select **Workspace**
3. Select under which **cluster** to create the workload
4. Select the **project** in which your workspace will run
5. Select **Start from scratch** to launch a new workspace quickly
6. Enter a **name** for the workspace (if the name already exists in the project, you will be requested to submit a different name)
7. Click **CONTINUE**
In the next step:
8. Under **Environment**, click the **load** icon. A side pane appears, displaying a list of available environments. Select the **‘jupyter-lab’** environment for your workspace (Image URL: `jupyter/scipy-notebook)`
* If ‘jupyter-lab’ is not displayed in the gallery, follow the below steps to create a one-time environment configuration:
* Enter the jupyter-lab **Image URL** - `jupyter/scipy-notebook`
* Tools - Set the connection for your tool
* Click **+TOOL**
* Select **Jupyter** tool from the list
* Set the runtime settings for the environment. Click **+COMMAND & ARGUMENTS** and add the following:
* Enter the command - `start-notebook.sh`
* Enter the arguments - `--NotebookApp.token=''`
**Note:** If [path-based routing](/run-ai/self-hosted/documentation/installation-and-configuration/config/networking/external-access-to-containers#access-to-the-running-workloads-container) is enabled on the cluster, enter `--NotebookApp.base_url=/${RUNAI_PROJECT}/${RUNAI_JOB_NAME} --NotebookApp.token=''`.
9. Under **Compute resources**, click the **load** icon. A side pane appears, displaying a list of available compute resources. Select the **‘small-fraction’** compute resource for your workspace.
* If ‘small-fraction’ is not displayed in the gallery, follow the below steps to create a one-time compute resource configuration:
* Set **GPU devices** per pod - 1
* Enable **GPU fractioning** to set the GPU memory per device:
* Select **% (of device)** - Fraction of a GPU device’s memory
* Set the memory **Request** - 10 (the workload will allocate 10% of the GPU memory)
* Optional: set the **CPU compute per pod** - 0.1 cores (default)
* Optional: set the **CPU memory per pod** - 100 MB (default)
10. Click **CREATE WORKSPACE**
1. Go to the Workload manager → Workloads
2. Click **+NEW WORKLOAD** and select **Workspace**
3. Select under which **cluster** to create the workload
4. Select the **project** in which your workspace will run
5. Select **Start from scratch** to launch a new workspace quickly
6. Enter a **name** for the workspace (if the name already exists in the project, you will be requested to submit a different name)
7. Click **CONTINUE**
In the next step:
8. Select the **‘jupyter-lab’** environment for your workspace (Image URL: `jupyter/scipy-notebook)`
* If the ‘jupyter-lab’ is not displayed in the gallery, follow the below steps:
* Click **+NEW ENVIRONMENT**
* Enter jupyter-lab as the **name** for the environment. The name must be unique.
* Enter the jupyter-lab **Image URL** - `jupyter/scipy-notebook`
* Tools - Set the connection for your tool
* Click **+TOOL**
* Select **Jupyter** tool from the list
* Set the runtime settings for the environment. Click **+COMMAND & ARGUMENTS** and add the following:
* Enter the command - `start-notebook.sh`
* Enter the arguments - `--NotebookApp.token=''`
**Note:** If [path-based routing](/run-ai/self-hosted/documentation/installation-and-configuration/config/networking/external-access-to-containers#access-to-the-running-workloads-container) is enabled on the cluster, enter `--NotebookApp.base_url=/${RUNAI_PROJECT}/${RUNAI_JOB_NAME} --NotebookApp.token=''`.
* Click **CREATE ENVIRONMENT**
The newly created environment will be selected automatically
9. Select the **‘small-fraction’** compute resource for your workspace
* If ‘small-fraction’ is not displayed in the gallery, follow the below steps:
* Click **+NEW COMPUTE RESOURCE**
* Enter small-fraction as the **name** for the compute resource. The name must be unique.
* Set **GPU devices** per pod - 1
* Enable **GPU fractioning** to set the GPU memory per device:
* Select **% (of device)** - Fraction of a GPU device’s memory
* Set the memory **Request** - 10 (the workload will allocate 10% of the GPU memory)
* Optional: set the **CPU compute per pod** - 0.1 cores (default)
* Optional: set the **CPU memory per pod** - 100 MB (default)
* Click **CREATE COMPUTE RESOURCE**
The newly created compute resource will be selected automatically
10. Click **CREATE WORKSPACE**
Copy the following command to your terminal. Make sure to update the below with the name of your project and workload. For more details, see [CLI reference](/run-ai/self-hosted/reference/cli/runai/workspace/runai-workspace-submit):
```sh
runai project set "project-name"
runai workspace submit "workload-name" --image jupyter/scipy-notebook \
--gpu-devices-request 0.1 --command --external-url container=8888 \
--name-prefix jupyter --command -- start-notebook.sh \
--NotebookApp.token=
```
Copy the following command to your terminal. Make sure to update the below parameters. For more details, see [Workspaces](https://docs.nvidia.com/run-ai/self-hosted/v3.0/reference/rest-api/endpoints/workloads/workspaces/create-workspace-1) API:
```bash
curl -L 'https:///api/v1/workloads/workspaces' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
-d '{
"name": "workload-name",
"projectId": "",
"clusterId": "",
"spec": {
"command" : "start-notebook.sh",
"args" : "--NotebookApp.token=''",
"image": "jupyter/scipy-notebook",
"compute": {
"gpuDevicesRequest": 1,
"gpuRequestType": "portion",
"gpuPortionRequest": 0.1
},
"exposedUrls" : [
{
"container" : 8888,
"toolType": "jupyter-notebook",
"toolName": "Jupyter"
}
]
}
}
```
* `` - The link to the NVIDIA Run:ai user interface
* `` - The API access token obtained in [Step 1](/run-ai/self-hosted/documentation/platform-management/runai-scheduler/resource-optimization/quick-starts/gpu-fractions-quickstart#step-1-logging-in)
* `` - The ID of the Project the workload is running on. You can get the Project ID via the [Get Projects](https://docs.nvidia.com/run-ai/self-hosted/v3.0/reference/rest-api/endpoints/organizations/projects/get-projects) API.
* `` - The unique identifier of the Cluster. You can get the Cluster UUID via the [Get Clusters](https://docs.nvidia.com/run-ai/multi-tenant/v3.0/reference/rest-api/endpoints/organizations/clusters/get-clusters) API.
* `toolType` will show the Jupyter icon when connecting to the Jupyter tool via the user interface.
* `toolName` will show when connecting to the Jupyter tool via the user interface.
**Note**
The above API snippet runs with NVIDIA Run:ai clusters of 2.18 and above only.
## Step 3: Connecting to the Jupyter Notebook
1. Select the newly created workspace with the Jupyter application that you want to connect to
2. Click **CONNECT**
3. Select the Jupyter tool. The selected tool is opened in a new tab on your browser.
To connect to the Jupyter Notebook, browse directly to `https:////`
To connect to the Jupyter Notebook, browse directly to `https:////`
## Next Steps
Manage and monitor your newly created workload using the [Workloads](/run-ai/self-hosted/documentation/workloads-in-nvidia-run-ai/workloads) table.