> ## 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 VSCS Development Environment

> Create, access, and manage VSCS development environments in Siverse, and configure browser-based VS Code access, SSH connections, and remote development directories.

VSCS stands for VS Code Server and is used to run a VS Code development environment in the cloud. You can open VS Code in a browser, or enable SSH access to connect to the development environment from a local terminal, local VS Code, Cursor, or similar tools.

VSCS is suitable for multi-file project development, remote connections from local IDEs, long-running debugging, and reusing editor extension configurations. If you only need interactive Notebook analysis, you can use a JupyterLab development environment.

## Choose an Access Method

* **Browser-based VS Code**: After the development environment is running, open the VS Code page in a browser. This method is suitable for installation-free, lightweight development and temporary debugging.
* **SSH connection**: Connect to the development environment remotely through a local SSH client or local IDE. This method is suitable for local toolchains, remote development, and multi-file project development.

You can enable either method separately or enable both at the same time. Both methods access the same development environment and share the same files, Volume, and mounted data. If you require SSH access, prepare an SSH public key and securely store the corresponding private key.

## Prepare an SSH Public Key

If you only use browser-based VS Code, you can skip this section. If you need to connect to VSCS through SSH or a local IDE, prepare an SSH public key first.

If you do not yet have an SSH key pair, generate one locally:

```bash theme={null}
ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa -N ""
cat ~/.ssh/id_rsa.pub
```

When creating a VSCS development environment or managing SSH keys, enter only the SSH public key. Do not upload or paste the private key.

To save commonly used SSH public keys in advance, go to **Develop > VSCS** and open **SSH Key Management**. Click **Create**, then enter the SSH public key and an identifiable title, such as the device name or intended use.

## Create a VSCS Development Environment

### 1. Go to the Creation Page

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

### 2. Configure the Settings

#### Basic Information

| Configuration item | Description |
| - | - |
| Region and cluster | Determines where the development environment runs. Available resource specifications, images, Volumes, datasets, models, and other options vary according to the selected region and cluster. We recommend selecting a cluster in the same region as your data, models, and compute resources or one nearby. |
| Name | Used to identify the development environment in the list and details pages. The name must comply with platform validation rules. If a name conflict is reported during submission, change the 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 the development environment in the list. After it is made public, compute resources, storage directories, and management actions remain controlled by their respective permissions. |

#### Resource Information

| Configuration item | Description |
| - | - |
| Resource type | Select **Reserved**, **Ondemand**, or **Spot**. Different resource types affect the resource source, billing method, and interruption risk. |
| Instance | If you use **Reserved**, select an available resource pool. |
| Instance type | Select **GPU** or **CPU**. For code editing, dependency installation, and lightweight debugging, you can usually select CPU. Select GPU when you need to run model training, validate inference, or perform GPU-accelerated tasks. |
| Resource specification | Select a specification from the instance list. The resources requested by a development environment must fit on a single node. If you select multiple candidate specifications, they are 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, arrange them from highest to lowest priority. During scheduling, the platform attempts the higher-priority specifications first. |

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

#### Environment Information

| Configuration item | Description |
| - | - |
| Access method | Select **VSCS**, **SSH**, or enable both methods. When enabling SSH, select or enter an SSH public key. Store the private key only on a locally controlled device. |
| Workspace directory | Configure the default working directory opened after entering VSCS. The workspace directory is only a path setting and does not automatically create persistent storage. We recommend pointing it to a mounted Volume path; otherwise, files may be lost after a restart, migration, or creation of a new environment. |
| Image | Select **Preset**, **Custom**, or **Input** to determine the system environment, dependency libraries, and development tools in the development environment. We recommend using validated images with fixed versions and confirming the required image components based on the access method. |
| Volume | Select the Volume to mount and enter its mount path in the Pod. To retain code, extension configurations, dependency caches, output results, or model files, mount a Volume and save important files to its path. We recommend using directories beginning 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 dataset to mount. You can mount a subdirectory as needed. Datasets are typically used as input and are not recommended as output directories. |
| Model | Select the model to mount. You can mount a subdirectory as needed. Models are typically used as input and are not recommended as output directories. |
| Command | Enter shell commands to run before VSCS 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 will block VSCS startup. For stable dependencies, we recommend including them in the image. |

We recommend that VSCS images include the following components:

* `bash`: The platform startup script depends on `bash`. If it is missing, the development environment may fail to start.
* `code-server`: Required when browser-based VS Code access is enabled. We recommend preinstalling it in the image to reduce startup time and improve stability.
* `openssh-server` or `sshd`: Required when SSH access is enabled.
* `wget` or `curl`: When local VS Code, Cursor, or similar tools connect through Remote-SSH for the first time, the remote IDE may need to download server components.

If the image does not include `code-server` or SSH-related components, the platform may attempt to inject them at startup. To reduce startup time and improve stability, we recommend preinstalling the required components in the image.

#### Advanced Configuration

| Configuration item | Description |
| - | - |
| Environment variables | Add environment variables as key-value pairs for use by startup commands, terminals, 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 configuration does not change the UTC cron requirement of the **Scheduled Start/Stop** panel. |

### 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 does not refresh immediately, first refresh the page or search for the development environment by name to avoid creating duplicates. 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 on the details page.

## Access a VSCS Development Environment

### Open VS Code in a Browser

1. Go to **Develop > VSCS**.
2. Find the target development environment in the list.
3. Confirm that the development environment is running and that the **VSCS** access method is enabled.
4. Click **Open**.

After it opens, you will enter browser-based VS Code. Closing the browser only disconnects access; it does not stop the development environment or release compute resources.

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

### Connect through SSH or a Local IDE

1. Go to **Develop > VSCS**.
2. Open the details page of the target development environment and copy the current SSH connection information.
3. Use the corresponding private key to connect from a local terminal, local VS Code, Cursor, or a similar tool.

If the connection fails after a restart or rescheduling, use the current connection information on the details page as the authoritative source, and check whether your local SSH configuration still points to the old address or port.

After connecting, confirm that the workspace directory, Volume, dataset, and model mount paths meet your expectations. If you need to reuse the server components, extensions, and user configuration of your local IDE, it is recommended that you store them in a mounted Volume.

## Save Files, Dependencies, and Execution Progress

Files, editor settings, software environments, and program execution states must be saved separately. Before rebuilding, stopping, rescheduling, or deleting a development environment, confirm how each type of output will be preserved.

| Content to save | Recommended storage 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 the files from the code repository. |
| Editor settings and extensions | Point the user configuration directory, extension directory, or remote IDE component directory to a persistent directory that you can write to. | Mount the same directory in the new environment, and verify that the extensions and remote components are compatible with the image, architecture, and IDE version. |
| Software dependencies | Save them as a custom image, or retain the Dockerfile, dependency manifest, and installation scripts. | Create a new environment using the custom image, or reinstall and validate the dependencies based on the dependency manifest. |
| Execution progress | Have the program actively save checkpoints or intermediate results. | Load the checkpoint after the program starts to resume execution. |

### Save Files and Output

Code, dependency manifests, output results, and model files that need to be retained long term should be saved 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 container path | Stored content | Usage recommendation |
| - | - | - |
| `/mnt/workspace/project` | Source code, configuration, and dependency manifests | Synchronize to a code repository or back up according to your team's policy. |
| `/mnt/workspace/outputs` | Experiment results and checkpoints | Use separate subdirectories for different experiments to avoid overwriting historical results. |
| `/mnt/workspace/notebooks` | Notebook files and saved outputs | If you also edit Notebooks in VSCS, save the `.ipynb` files promptly. |

A path name does not determine whether data is persistent; what matters is whether the path is within a valid mount. It is recommended that you separate input data from output directories to avoid modifying shared data sources.

### Save Editor Settings and Extensions

If you want to continue reusing editor settings, remote IDE components, or extensions after rebuilding an environment, point the relevant configuration directories to a persistent directory that you can write to when creating or updating a VSCS development environment.

| Usage method | Configuration recommended for persistence |
| - | - |
| Browser-based VS Code | User configuration directory and extension directory. |
| SSH + local VS Code or Cursor | Remote server components, remote user configuration directory, and extension directory for the relevant tool. |

Use different directories for different tools. Multiple users should not share the same writable configuration directory. After changing the image, system architecture, or IDE version, check the compatibility of saved extensions and remote components again.

### 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**, enter the image information, and submit it.
4. Keep the source development environment running during the save process. Avoid stopping, deleting, rescheduling, or making substantial additional dependency changes.
5. Go to the custom image build records to confirm that the save was successful. Then create a development environment using the new image and verify that the key dependencies are available.

Existing build tasks, container size, and other conditions may restrict image saving. If saving fails, view the custom image build logs to identify the cause. For environments maintained over the long term, retain the Dockerfile, dependency manifest, or installation scripts. A saved image does not include mounted Volumes, process memory, or execution state. Dependencies that exist only in mounted Volumes require remounting the Volumes or installation based on the dependency manifest. For complete information about build records, logs, and image reuse, see [Build and Manage Custom Images](/siverse/images/build-custom-images.md).

### Save Execution Progress

Terminal processes, debugging sessions, and GPU execution states are not automatically saved when the browser or SSH connection is disconnected. For long-running experiments, save checkpoints in the program and resume from them after a restart.

Closing the browser or disconnecting SSH only disconnects access and does not automatically stop the development environment. However, an in-place restart, rescheduling, stopping, automatic scale-in, or deletion interrupts processes. Save files and execution progress before performing any of these operations.

## View and Manage Development Environments

### View Status and Resources

On the **Develop > VSCS** list or details page, view the development environment status, resource specifications, actual instance, resource pool, running duration, and events to determine whether the environment is ready, whether resources are sufficient, or whether 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, based on the displayed guidance, check the resource quota, image components, Volume mount path, startup command, environment variables, or access method configuration.

> [!NOTE]
>
> In the storage information section on the details page, you can view Pod ephemeral storage usage. Ephemeral storage is suitable for small amounts of disposable runtime files. Data that must be retained, such as code, plug-in configurations, dependency caches, debugging output, 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 operations on a VSCS development environment from the list or details page.

#### Choose a Start or Restart Method

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

| Scenario | Recommended operation | Check after the operation |
| - | - | - |
| The development environment has stopped and needs to be used again. | **Start** | Wait for the development environment to enter the running state, then retrieve the current connection information. |
| The development environment is still on the current Pod or node, and you only need to reset terminal processes or the remote IDE session. | **Restart In Place** | Reconnect to VSCS and verify that processes, files, and dependencies meet your expectations. |
| You need to revalidate resources, rebuild the environment, or recover an abnormal environment through rescheduling. | **Reschedule and Restart** | Wait for the development environment to become ready again, then check the image, mount paths, runtime dependencies, and current connection information. |

#### Other Operations

* **Stop**: Shuts down the running development environment and releases compute resources. The development environment configuration and data written to Volumes are retained.
* **Update**: Modifies the image, resource specifications, Volume mounts, dataset or model mounts, startup command, environment variables, access method, or workspace directory configuration. Changes to resources, images, or mounts may affect execution, 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 the save process. Perform this operation when no interactive work is in progress.
* **Adjust Visibility**: Sets the development environment to private or visible within the Project Group. Adjusting visibility does not affect the running state.
* **Delete**: Removes the development environment record and releases occupied resources. Before deletion, confirm that any data you need to retain has been saved to a Volume.

Some operations may be unavailable while the environment is queued or transitioning between states. If an operation fails or does not complete for an extended period, first check the status details and events. Do not repeatedly submit the same operation.

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

Keeping a VSCS development environment running for an extended period continuously consumes compute resources. You can configure scheduled start/stop or automatic scale-in based on your usage patterns to reduce idle resource consumption. If you need to run long-running experiments, first confirm whether the relevant policies are enabled, and save your files and progress in advance.

### Configure Scheduled Start/Stop

Go to **Develop > VSCS**, 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 | Example cron expression |
| - | - | - |
| 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 week. The time zone 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 starts still require time for resource scheduling to complete.

### Configure Automatic Scale-In

Go to **Develop > VSCS**, 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-only 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.

## Resolve Remote IDE Component Download Failures

Some GPU nodes cannot access the internet. When local VS Code, Cursor, or similar tools first connect through Remote-SSH, they may need to download server components or extensions on the remote end. If the target GPU node cannot access the internet, the connection may stall during the download phase.

You can use an internet-enabled CPU development environment to pre-download the required components, then switch to the target GPU resource specification:

1. Create an SSH-enabled CPU development environment and mount a persistent Volume.
2. Set the user configuration directory and extension installation directory to paths in that Volume.
3. Use local VS Code or Cursor to connect to the CPU development environment through Remote-SSH, allowing the remote IDE to download server components to the Volume.
4. Update the resource specification to the target GPU resource specification while retaining the same Volume, user configuration directory, and extension installation directory.
5. Connect to the development environment again from the local IDE. The components already downloaded to the Volume can then be reused.

Both the CPU and GPU stages must mount the same Volume and use identical user configuration directory and extension installation directory paths.

## FAQs

> **What should I do if a development environment remains queued for a long time or fails to be created?**
>
> Check 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 browser-based VS Code cannot be opened?**
>
> Confirm that the development environment is running and that the **VSCS** access method is enabled. If it repeatedly restarts, check whether the image includes `code-server`, and review the startup command, environment variables, and mount path.

> **What should I do if an SSH connection times out?**
>
> Confirm that the **SSH** access method is enabled and use the current connection information shown on the development environment details page. Then check whether your local network, target port, and local SSH configuration are reachable.

> **What should I do if SSH displays Permission denied (publickey)?**
>
> Confirm that the platform is configured with a public key and that the matching private key is used locally. Also check the username, private key path, and connection information used by your local IDE or SSH client.

> **What should I do if SSH displays remote host identification has changed?**
>
> After confirming that the connection address comes from the console details page, clear the old local record and reconnect.
>
> ```bash theme={null}
> ssh-keygen -R "[<PUBLIC_IP>]:<PORT>"
> ```

> **What should I do if my local IDE stalls while downloading server components on the first connection?**
>
> Confirm whether the node hosting the development environment can access the internet. If it cannot, first use an internet-enabled CPU development environment to pre-download for offline use, then switch to the target GPU resource specification while retaining the same Volume, user configuration directory, and extension installation directory.

> **What should I do if files, extensions, or dependencies are missing after a restart?**
>
> First confirm that files and configurations were written to the Volume. Code, extension configurations, dependency caches, and output results must be persisted separately. Saving an image does not back up the mounted Volume 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, access method, and sanitized error information. Do not send private keys, access keys, or complete links containing authentication information.

## Related Documentation

* [Use a JupyterLab Development Environment](/siverse/development/use-jupyterlab-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)


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