> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vessl.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a new workspace
To **create** a **workspace**, you need to select few options including workspace name, cluster, resource, image and few advanced settings.
Enjoy your interactive works
## Workspace name
Once you start to create a new workspace, the default workspace name will be randomly generated. Specify a good name to remember.
## Cluster
You can choose between **VESSL Cloud**, which is a cluster managed by VESSL AI, or a custom cluster that you register yourself. (See [configure organization cluster](/guides/clusters/aws#private-clouds) for more details.) **VESSL Cloud** is always hosted on a cloud vendor's server, while the custom cluster can be hosted either on a cloud server or on an on-premises server.
We support the following integrations:
* **AWS EKS**
* **GCP GKE**
## Resource
Choose the type of resource that the container will use. Select the resource among the dropdown option or specify the requirements manually.
## Max runtime
Specify the max runtime for this workspace. After max runtime, workspace will be automatically stopped.
For the **Enterprise plan**, Organization admin can limit the max runtime that
users can input.
## Image
You can choose the Docker image that the workspace container will use. There are two types of images: the **Managed Image** and the **Custom Image**. Select the Docker image type that you want to run on the workspace container.
For the **Managed Image**, you can simply select such an option, then the
image managed by VESSL AI will be used in default. You can run Jupyter
services on the managed image.
You can use any docker images from **Docker Hub** or
[AWS ECR](https://aws.amazon.com/ecr/). To run a workspace with custom
images, your custom images have to satisfy below requirements.
* Jupyterlab
* VESSL runs Jupyterlab and expose port `8888`. Jupyter should be
pre-installed in the container image.
* sshd
* VESSL runs sshd and expose port `22` as NodePort. sshd package should be
pre-installed in the container image.
* Persistent Volume Claim (PVC) mountable at `/root`
* VESSL mounts a PVC at `/root` to keep state across Pod restarts.
### Public image
To pull images from the public Docker registry, you can simply pass the image
URL as the below example.
### Private image
To pull images from the private Docker registry or the private AWS ECR, you
should [integrate your credentials in organization settings
first](/guides/organization/integrations.mdx). Then check the private image
checkbox and select the credentials you have just integrated. Below is an
example of a private image from the AWS ECR.
Debian based images are compatible.
## Volumes
Volumes enable you to bring data into your workspace and provide persistent storage solutions for your development environment. They are essential for accessing datasets, code repositories, and other files needed for your interactive work.
### Import Volumes
Import volumes download data from external sources into your workspace container at startup. This is useful for:
* **Code**: Pull code from version control systems such as GitHub, GitLab, or BitBucket.
* **Dataset and Model**: Retrieve datasets or models defined in VESSL Dataset or VESSL Model Registry.
* **Hugging Face**: Fetch datasets or models from Hugging Face repositories.
* **Files**: Incorporate files from VESSL Storage volumes.
* **Object Storage**: Download data directly from cloud services like AWS S3 or Google Cloud Storage.
### Mount Volumes
Mount volumes provide persistent storage solutions, directly attaching to your workspace container for ongoing data access. They are particularly valuable for:
* **Dataset**: Attach datasets predefined in VESSL Dataset for direct use in the container.
* **VESSL Storage**: Mount volumes from VESSL Storage for persistent file access across workspace sessions.
* **External Storage**: Connect to external storage solutions like AWS S3 or Google Cloud Storage.
* **On-premises Storage**: Connect to on-site data storage solutions using Network File System (NFS) or host path configurations (custom clusters only).
* **GCS Fuse**: Integrate Google Cloud Storage using GCS Fuse for seamless data accessibility.
Unlike runs, workspaces don't typically use export volumes since the `/root` directory provides built-in persistence for your work.
Explore VESSL's storage system for managing your data and volumes.
## Advanced setting
### Disk
You can specify the **disk** **size** to use in your container. This will be the request storage size of your PVC. **The disk size cannot be changed once the workspace is created.**
Disk size can be ignored in a custom cluster due to limitation of kubernetes.
([official
docs](https://kubernetes.io/docs/concepts/storage/volumes/#resources))
### Port
You can customize **port** settings. By default, 8888 (jupyter) and 22 (ssh) are exposed.
### Initialization (init) script
**Init script** is a shell script that runs every time the workspace starts. Because `/root` is the only persistent directory, packages you installed outside the home directory may reset on stop and start. In this case, you can fill **init script** with install commands such as `apt-get update && apt-get install ripgrep -y`.