> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scitix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Use the JupyterLab Development Environment

> Create, open, and manage JupyterLab development environments in Siverse for interactive Notebook development, data exploration, debugging, and validation.

JupyterLab development environments enable interactive Notebook development in a browser. You can select computing resources, images, Volumes, datasets, and models as needed to create an independent cloud-based development environment for data exploration, Notebook experiments, code debugging, and small-scale validation.

JupyterLab supports browser access only and does not support SSH login. To connect to a cloud environment through local VS Code, Cursor, or SSH, use a VSCS development environment.

## Create a JupyterLab Development Environment

### 1. Go to the Creation Page

1. Go to **Develop > JupyterLab**.
2. Click **Create**.

### 2. Configure the Settings

#### Basic Information

| Configuration item | Description |
| - | - |
| Region and cluster | Determines where the development environment runs. After selection, the available resource specifications, images, Volumes, datasets, models, and other options change accordingly. We recommend selecting the same or a nearby cluster as your data, models, and computing resources to reduce latency caused by cross-region access. |
| Name | Used to identify the development environment in lists and details. The name must comply with platform validation rules. If a name conflict occurs during submission, use a different name and try again. |
| Project Group | Specify the Project Group to which the development environment belongs. |
| Public within Project Group | Controls whether other users in the Project Group can view this development environment in the list. After it is made public, computing resources, storage directories, and management actions remain subject to their respective permissions. |

#### Resource Information

| Configuration item | Description |
| - | - |
| Resource type | Select **Reserved**, **Ondemand**, or **Spot**. Different resource types affect the where resources come from, billing method, and interruption risk. |
| Instance | If you use **Reserved**, select an available resource pool. |
| Instance type | Select **GPU** or **CPU**. CPU is generally suitable for data exploration and lightweight script debugging. Select GPU when you need to run model training, validate inference, or perform GPU acceleration tasks. |
| Resource specification | Select a specification from the instance list. Resources requested by a development environment must fit on the same node. If you select multiple candidate specifications, they serve as alternative scheduling options for the same development environment and do not create multiple development environments. |
| Number of specifications per node | Configure the number of specifications requested by a single development environment. For example, if each specification includes two GPUs, selecting two specifications requests four GPUs, along with the corresponding CPU and memory resources. |
| Resource priority | When selecting multiple candidate specifications, sort them from highest to lowest priority. During scheduling, the system attempts the higher-priority specifications first. |

When you submit the request, the platform verifies the resource quota and resource pool availability. If the quota is insufficient, reduce the number of specifications, select another specification, or contact an administrator to expand capacity.

#### Environment Information

| Configuration item | Description |
| - | - |
| Image | Select **Preset**, **Custom**, or **Input** to determine the system environment, dependency libraries, and toolchain in the development environment. We recommend using validated images with fixed versions. When using a custom image or image input, ensure that the image includes `bash` and JupyterLab-related components. |
| Volume | Select the Volumes to mount and specify the mount path in the Pod. To retain code, Notebooks, output results, model files, or installed dependencies, mount a Volume and write important files to the Volume path. We recommend using directories that begin with `/volume` or `/mnt` as mount paths to avoid overwriting the root directory or default image directories such as `/opt`, `/workspace`, and `/usr`. |
| Dataset | Select the datasets to mount. You can mount a subdirectory as needed. Datasets are generally used as input and are not recommended as output directories. |
| Model | Select the models to mount. You can mount a subdirectory as needed. Models are generally used as input and are not recommended as output directories. |
| Command | Enter shell commands to run before JupyterLab starts. These commands can be used to set environment variables or prepare directories. Commands must complete successfully and support repeated execution. Long-running training loops, continuously running services, or commands that require manual input block JupyterLab from starting. For stable dependencies, we recommend baking them into the image. |

#### Advanced Configuration

| Configuration item | Description |
| - | - |
| Environment variables | Add environment variables as key-value pairs for use by startup commands, Notebooks, or programs in the development environment. They are commonly used for configuration settings, paths, or credentials. Use sensitive information with caution. |
| Time zone | Configure the local time zone used by programs and logs in the development environment. The default is `Asia/Shanghai`. This setting does not change the UTC cron requirement of the **Scheduled Start/Stop** panel. |
| Default directory | Configure the root directory that the file browser opens after you enter JupyterLab. This directory must exist and be accessible. Setting it too narrowly may prevent other mounted directories from appearing in the file tree. The default directory is only an access path and does not automatically create persistent storage. To retain files, mount a Volume to this directory or its parent directory. |

### 3. Submit the Creation Request

Click **Create** to submit the request. The development environment is created asynchronously, and you can view status changes in the list.

If the request is submitted successfully but the list is not refreshed immediately, refresh the list or search for the development environment name before creating another one. After the development environment enters the running state, we recommend confirming the actual instance, resource pool, image pull result, storage mounts, and service startup result in the details.

## Open JupyterLab

1. Go to **Develop > JupyterLab**.
2. Find the target development environment in the list.
3. Confirm that the development environment is running.
4. Click **Open**.
5. After entering JupyterLab, confirm that the default directory and the mount paths for Volumes, datasets, or models are as expected.

After entering JupyterLab, you can create Notebooks, scripts, terminals, or consoles. Closing the browser only disconnects access; it does not stop the development environment or release computing resources.

![Open a JupyterLab development environment in a browser](https://mintcdn.com/scitix-adfc65c2/ZqwdmfntBUDyGPkJ/siverse/development/media/open-jupyterlab-development-environment.png?fit=max\&auto=format\&n=ZqwdmfntBUDyGPkJ\&q=85\&s=e3b39d8495bd5667929f5ed39befbdd6)

## Save Files, Dependencies, and Runtime Progress

Files, software environments, and program runtime states must be saved separately. Before rebuilding, stopping, rescheduling, or deleting a development environment, confirm how each type of output is saved.

| Content to save | Recommended method | Recovery method |
| - | - | - |
| Code and files | Save them to a mounted Volume and, when necessary, synchronize them to a code repository. | Remount the Volume or pull from the code repository. |
| Software dependencies | Save them as a custom image, or retain the Dockerfile, dependency list, and installation scripts. | Create a new environment using the custom image, or reinstall and verify dependencies according to the dependency list. |
| Execution progress | Have the program proactively save checkpoints or intermediate results. | Load the checkpoint after the program starts to resume execution. |

### Save Files and Outputs

Save Notebooks, code, dependency lists, outputs, and model files that need to be retained long term to a mounted Volume. Container local disks have limited capacity, and writing large amounts of data may cause the workload to be evicted by the system. Data written to the local disk may not be recoverable after the development environment is restarted, migrated, or deleted.

For example, after mounting a project Volume to `/mnt/workspace`, you can organize directories by purpose:

| Example path in the container | Content to save | Recommendations |
| - | - | - |
| `/mnt/workspace/project` | Source code, configurations, and dependency lists | Synchronize to a code repository or back up according to your team policy. |
| `/mnt/workspace/notebooks` | Notebook files and saved outputs | Save `.ipynb` files promptly to avoid retaining only unsaved browser state. |
| `/mnt/workspace/outputs` | Experiment results and checkpoints | Create separate subdirectories for different experiments to avoid overwriting historical results. |

A path name does not determine persistence; the key is whether it is within an active mount. Keep input data and output directories separate to avoid modifying shared data sources.

### Save Dependencies as an Image

If you install system dependencies, toolchains, or Python packages in a development environment and want to reuse them in a new environment, you can save the running development environment as a custom image.

1. Keep the source development environment in the running state.
2. Check that the container writable layer does not contain credentials, keys, temporary data, or sensitive files that should not be shared.
3. In the development environment actions, click **Save Image**, provide the image information, and submit it.
4. Keep the source development environment running during the save process. Avoid stopping, deleting, rescheduling, or making extensive dependency changes.
5. Confirm that the save succeeded in the custom image build records, then create a development environment using the new image and verify that key dependencies are available.

Existing build tasks, container size, and other conditions may limit image saving. If saving fails, check the custom image build logs to identify the cause. For long-term maintenance, it is still recommended that you retain the Dockerfile, dependency list, or installation scripts. Saving an image does not include mounted Volumes, process memory, or runtime state. Dependencies that exist only on mounted volumes require remounting the volume or installation according to the dependency list. For complete information about build records, logs, and image reuse, see [Build and manage custom images](/siverse/images/build-custom-images.md).

### Save Runtime Progress

Notebook files save only code, Markdown, and saved outputs; they do not save the complete Python process, GPU state, or training progress. Long-running experiments must save checkpoints in the program and resume from checkpoints after a restart.

Closing the browser only disconnects access and does not automatically stop the development environment. However, in-place restarts, rescheduling, stopping, automatic scale-in, or deletion interrupt Notebook, script, and terminal processes. Before performing these actions, save your files and runtime progress.

## View and Manage Development Environments

### View Status and Resources

On the **Develop > JupyterLab** list or details page, view the development environment status, resource specifications, actual instance, resource pool, runtime duration, and events to determine whether the development environment is ready, resources are sufficient, or it has been idle for an extended period.

If the development environment does not enter the running state, first check the status details and events. Then, follow the prompts to check resource quotas, image components, volume mount paths, startup commands, or environment variables.

> [!NOTE]
>
> In the storage information on the details page, you can view Pod ephemeral storage usage. Ephemeral storage is suitable for small amounts of disposable runtime files. Data that needs to be retained, such as notebooks, dependency caches, checkpoints, output results, or model files, should be written to a mounted Volume. For more information, see [Best Practices for Using Ephemeral Storage](/siverse/best-practices/use-ephemeral-storage.md).

### Manage the Lifecycle

After creation, you can perform lifecycle management actions for JupyterLab development environments from the list or details page.

#### Choose How to Start or Restart

When you need to reuse or restart a development environment, select an action based on its current status and your objective.

| Scenario | Recommended action | Checks after the action |
| - | - | - |
| The development environment has stopped and needs to be used again. | **Start** | Wait for the development environment to enter the running state, then reopen JupyterLab. |
| The development environment remains on the current Pod or node, and you only need to reset Notebook, script, or terminal processes. | **Restart In Place** | Reopen JupyterLab and check whether processes, files, and dependencies are as expected. |
| You need to revalidate resources, rebuild the environment, or recover an abnormal environment through rescheduling. | **Reschedule and Restart** | After the development environment is ready again, check the image, mount paths, runtime dependencies, and access entry point. |

#### Other Actions

* **Stop**: Stops the running development environment and releases compute resources. Development environment configurations and data written to Volumes are retained.
* **Update**: Modifies configurations such as the image, resource specifications, Volume mounts, dataset or model mounts, startup commands, and environment variables. Changes to resources, images, or mounts may affect operation, and some changes take effect only after a restart.
* **Clone**: Creates a new development environment based on the current configuration. Cloning does not copy the complete disk, process memory, or non-persistent data.
* **Save Image**: Saves the running development environment as a custom image for later reuse of installed dependencies and tools. The development environment may be temporarily unavailable during saving, so it is recommended to perform this action when no interactive operations are in progress.
* **Adjust Visibility**: Sets the development environment to private or public within the project group. Adjusting visibility does not affect the running state.
* **Delete**: Removes the development environment record and releases occupied resources. Deletion is irreversible. Before deleting, confirm that any data you need to retain has been saved to a Volume.

Some actions may be unavailable while queued or during status transitions. If an action fails or does not complete for an extended period, first check the status details and events. Do not repeatedly submit the same action.

## Configure Scheduled Start/Stop and Automatic Scale-In

A JupyterLab development environment continuously consumes compute resources while it is running. You can configure scheduled start/stop or automatic scale-in based on your usage habits to reduce idle resource consumption. If you need to run long-running experiments, first confirm whether relevant policies are enabled and save files and progress in advance.

### Configure Scheduled Start/Stop

Go to **Develop > JupyterLab**, and select **Scheduled Start/Stop** from the **More** actions for the target development environment.

Scheduled start/stop automatically starts or stops development environments according to recurring time rules and is suitable for development scenarios with fixed working hours. The panel uses a six-field cron expression: second, minute, hour, day, month, and day of week. The time zone is UTC.

| Target Beijing time | Converted UTC time | Cron example |
| - | - | - |
| Start at 09:00, Monday through Friday | 01:00 on the same day | `0 0 1 * * 1-5` |
| Stop at 18:00, Monday through Friday | 10:00 on the same day | `0 0 10 * * 1-5` |

When the schedule crosses midnight, you must also adjust the date or day of the week. The timezone setting in the development environment does not change the UTC requirement of the **Scheduled Start/Stop** panel. After submission, you can verify through events whether the schedule runs as expected. Scheduled startup still requires waiting for resource scheduling to complete.

### Configure Automatic Scale-In

Go to **Develop > JupyterLab**, and select **Automatic Scale-In** from the **More** actions for the target development environment.

Automatic scale-in determines whether to stop a development environment based on GPU utilization and an observation window. CPU development environments are currently not supported. Automatic scale-in does not automatically restart the development environment after it is triggered. To continue using it, start it manually or use a scheduled start/stop plan.

| Evaluation method | Observed value | Configuration considerations |
| - | - | - |
| `MaxOverTime` | The maximum GPU utilization within the window. | Brief utilization spikes also affect the evaluation. This method is suitable when you want to retain occasional GPU activity. |
| `AvgOverTime` | The average GPU utilization within the window. | Extended periods of low utilization reduce the average. This method is suitable for reclaiming resources based on overall idle time. |

When setting the window and threshold, consider data loading, CPU preprocessing, and normal debugging wait times. During these stages, the GPU may be idle while the program is still running. The current control flow may also scale the environment down to 0 when no monitoring samples are available. Before enabling this feature, save your files and progress, and determine how you will resume work afterward.

## Debug Distributed Tasks with JupyterLab

If you need to temporarily validate a distributed training script in a Notebook environment, you can create multiple JupyterLab development environments and run `torchrun` in the terminal of each environment using the same primary-node address and port. You can obtain the primary-node address in the primary-node environment by running `echo $POD_IP`.

```bash theme={null}
# Primary node
torchrun --master_addr <PRIMARY_NODE_POD_IP> --master_port 23457 \
  --nnodes 2 --nproc_per_node 1 --node_rank 0 trainer.py

# Other nodes
torchrun --master_addr <PRIMARY_NODE_POD_IP> --master_port 23457 \
  --nnodes 2 --nproc_per_node 1 --node_rank 1 trainer.py
```

Ensure that `--master_addr`, `--master_port`, `--nnodes`, and `--nproc_per_node` are consistent across all nodes. Set `--node_rank` according to the node order. For formal large-scale training, workloads that require queue scheduling, or scenarios requiring more reliable fault tolerance, we recommend using Training.

## FAQs

> **What should I do if a development environment remains queued for a long time or fails to be created?**
>
> View the status details and events to confirm that the selected resource specification, remaining quota, and pool availability meet the requirements. If the quota is insufficient, reduce the number of specifications, switch to a different specification, or contact an administrator to expand capacity.

> **What should I do if JupyterLab cannot be opened or repeatedly restarts?**
>
> Confirm that the development environment is running, and check whether the image includes `bash` and JupyterLab-related components. Then check the startup command, environment variables, and mount path. Ensure that the initialization command has exited normally and that no continuously running service or command waiting for manual input is blocking startup.

> **What should I do if Volume, dataset, or model paths are unavailable?**
>
> Confirm that mount objects and mount paths in the Pod are configured in matching pairs. Ensure that mount paths do not overwrite system directories or conflict with other mount paths. If a mount directory cannot be written to, check directory permissions, read/write access, capacity, and limits.

> **What should I do if importing packages in a Notebook fails?**
>
> Confirm that the Kernel used by the Notebook is the same interpreter used to install the dependencies. If dependencies are installed in a container-local path, they may need to be reinstalled after restarting, migrating, or creating a new environment. We recommend incorporating stable dependencies into the image or retaining a dependency list.

> **What should I do if files, extensions, or dependencies are missing after a restart?**
>
> First, confirm whether files and configurations have been written to Volume. Notebook files, code, extension configurations, dependency caches, and output results must be persisted separately. Saving an image does not back up mounted Volume data or process state.

> **What information should I provide when requesting support?**
>
> Provide the development environment type and ID, region and cluster, time of occurrence, status details, image information, and sanitized error messages. Do not send private keys, access keys, or complete links containing authentication information.

## Related Documentation

* [Use a VSCS Development Environment](/siverse/development/use-vscode-server-development-environment.md)
* [Create and Use Storage Volumes](/siverse/resources/create-and-use-storage-volumes.md)
* [Mount Datasets in Development Environments and Training Tasks](/siverse/datasets/mount-datasets-in-workloads.md)
* [Create Training Tasks](/siverse/training/create-training-tasks.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.