> 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 Compute Modes
This quick start provides a step-by-step walkthrough for running two workspaces that share a single GPU using SM-sharing, and for verifying the compute mode after submission.
A GPU compute mode always accompanies a GPU memory fraction — the memory fraction determines how much GPU memory the workload receives, and the compute mode determines how the workloads sharing that GPU divide the GPU compute. For background on both modes, 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 1 GPU.
* A GPU is available that is not currently running other workloads using GPU fractions.
**Note**
* The compute mode is exclusive per GPU. The first workload placed on a GPU fixes the compute mode of that GPU, and every workload that joins afterwards must request the same mode. Starting this walkthrough on a GPU that is already running time-slicing workloads prevents the SM-sharing workspaces from being placed on it.
* 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 the First 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`)
9. Under **Compute resources**, click the **load** icon. A side pane appears, displaying a list of available compute resources. To add a new compute resource:
* Click the **+** icon to create a new compute resource
* Enter sm-sharing-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 **GB** - Fraction of a GPU device’s memory
* Set the memory **Request** - 20GB
* Click **CREATE COMPUTE RESOURCE**
* Select the newly created compute resource from the side pane
10. Open the **General** section and locate **Set annotation(s)**. Click **+ANNOTATION** and set the compute mode:
* **Name** - `nvidia.com/container..gpu-compute.mode`
* **Value** - `"sm-sharing"`, including the quotation marks
11. 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-1" --image jupyter/scipy-notebook \
--gpu-memory-request 20G \
--annotation nvidia.com/container.workload-name-1.gpu-compute.mode=sm-sharing \
--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-1",
"projectId": "",
"clusterId": "",
"spec": {
"command" : "start-notebook.sh",
"args" : "--NotebookApp.token=''",
"image": "jupyter/scipy-notebook",
"annotations": [
{
"name": "nvidia.com/container.workload-name-1.gpu-compute.mode",
"value": "sm-sharing"
}
],
"compute": {
"gpuDevicesRequest": 1,
"gpuRequestType": "memory",
"gpuMemoryRequest": "20G"
},
"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/compute-modes-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.
## Step 3: Submitting the Second Workspace
Repeat Step 2 with a different workload name, using the same compute resource and the same `sm-sharing` compute mode. Both workspaces request 20 GB of GPU memory, so both can be placed on the same GPU.
**Note**
A workload requesting `time-slicing`, or a workload submitted without a compute mode annotation, is not placed on this GPU while the SM-sharing workspaces are running on it.
## Step 4: Verifying the Compute Mode
1. Go to the Workload manager → Workloads
2. Select one of the workspaces you created and click **SHOW DETAILS**
3. Open the **YAML** tab
4. Confirm that `nvidia.com/container..gpu-compute.mode` is present with the value `sm-sharing`
Confirm the annotation is present on the pod:
```sh
kubectl get pod -n -o jsonpath='{.metadata.annotations}'
```
Confirm the annotation is present on the pod:
```sh
kubectl get pod -n -o jsonpath='{.metadata.annotations}'
```
Both workspaces now run concurrently on separate streaming multiprocessors of the same GPU. Had the workloads used time-slicing, they would have taken sequential turns on the GPU compute engines instead.
## Next Steps
* Choose between the two modes for your own workloads using [GPU compute modes](/run-ai/self-hosted/documentation/platform-management/runai-scheduler/resource-optimization/gpu-fractions/compute-modes).
* Manage and monitor your newly created workloads using the [Workloads](/run-ai/self-hosted/documentation/workloads-in-nvidia-run-ai/workloads) table.