Skip to main content

Projects & Workspaces

Organize work with projects and develop in powerful cloud-based environments (JupyterHub, VS Code) with three types of persistent storage for seamless team collaboration.

How to Create a Project​

Step 1: Navigate to Projects​

  • Click Projects in the main navigation
  • Click Create Project button

Step 2: Configure Project​

Project Details:

  • Name: Unique project identifier (e.g., customer-churn-analysis)
  • Display Name: Friendly name shown in UI
  • Description: Project purpose and goals
  • Tags: Organize by department, team, or category
  • Team Members: Add collaborators with view or edit permissions

Step 3: Create Project Volumes (Optional)​

Add shared storage volumes accessible to all workspaces in this project:

  1. Click Add Volume in project settings
  2. Enter volume name (e.g., training-data, models, results)
  3. Set storage size (default: 10GB, max: 1TB)
  4. Choose storage class: gp3 (general purpose), io1 (high performance)
  5. Click Create Volume
tip

Project volumes are mounted at /project/volume-name in all workspaces. Perfect for shared datasets and team code.

How to Create a Workspace​

Step 1: Select Project​

  • Navigate to Projects
  • Click on a project name
  • Click Create Workspace button

Step 2: Choose Environment​

Development Environments​

JupyterHub

  • Image: jupyter/datascience-notebook
  • Port: 8888
  • Best For: Data science, ML, interactive notebooks, Python/R development
  • Pre-installed data science libraries
  • Multiple kernels (Python, R, Julia)
  • Interactive visualizations

VS Code

  • Image: codercom/code-server
  • Port: 8080
  • Best For: Full-stack development, debugging, version control
  • Full VS Code IDE in browser
  • Extensions marketplace
  • Git integration, debugging

Three Volume Types​

Volume TypeScopeMount PathLifecycle
Workspace VolumeSingle workspace only/workspacePersists for life of workspace (deleted with workspace)
Project VolumeAll workspaces in project/project/<name>Persists for life of project (deleted with project)
Shared VolumeMultiple projects/shared/<name>Persists until explicitly deleted

Volume Lifecycle Details​

Workspace Volumes:

  • Data in /workspace persists through workspace stop/start cycles
  • Volume is deleted only when the workspace itself is deleted
  • Perfect for personal files, experiments, and temporary data

Project Volumes:

  • Accessible from all workspaces within the project
  • Data persists through workspace stop/start and even workspace deletion
  • Volume is deleted only when the project is deleted
  • Use the Sync button in workspace header to backup changes to project storage

Shared Volumes:

  • Accessible from workspaces across multiple projects
  • Persists independently until explicitly deleted by an admin
  • Use the Sync button in workspace header to backup changes to shared storage
Important

Only files saved within /workspace, /project/*, or /shared/* directories persist. System-level installations (e.g., pip install or apt-get install) do not persist between workspace restarts.

To persist Python packages, use a virtual environment inside your workspace:

python -m venv /workspace/venv
source /workspace/venv/bin/activate
pip install your-packages

Step 3: Configure Resources​

Resource Allocation:

  • CPU: 0.5 - 16 cores
  • Memory: 1GB - 64GB RAM
  • GPU: Optional (NVIDIA T4, A10G, A100)
  • Workspace Storage: 5GB - 500GB persistent disk

Step 4: Connect Services (Optional)​

Connect data sources, add-ons, and AI models to your workspace via STRONGLY_SERVICES:

  • Select PostgreSQL, MongoDB, or other data sources
  • Connect to AI models from AI Gateway
  • Link workflows for programmatic execution

Step 5: Launch Workspace​

  1. Review configuration
  2. Click Create Workspace
  3. Wait for provisioning (typically 30-90 seconds)
  4. Click Open to launch JupyterHub or VS Code in new tab

Using Volumes in Code​

# Python Example
import pandas as pd
import os

# Workspace volume (personal - unique to this workspace)
results_df.to_csv('/workspace/experiments/results.csv')

# Project volume (shared across all workspaces in project)
train_df = pd.read_csv('/project/training-data/train.csv')

# Shared volume (organization-wide access)
reference_df = pd.read_parquet('/shared/common-datasets/reference.parquet')

Managing Workspaces​

Start/Stop/Restart​

  • Stop idle workspaces to save costs
  • All data in volumes persists when stopped
  • Restart anytime without losing work
  • Auto-stop after configurable idle time

Upgrade Resources​

  • Stop workspace before upgrading
  • Modify CPU, memory, or GPU allocation
  • Increase workspace storage size
  • Restart with new configuration

Install Packages​

  • JupyterHub: Use pip, conda, or apt-get in terminal
  • VS Code: Install extensions from marketplace
  • Use virtual environments in /workspace/venv to persist Python packages
  • Share environment.yml or requirements.txt with team

Collaborate with Team​

  • Share project volumes for common datasets
  • Use Git for version control within workspace
  • Export notebooks to share with project members
  • Set up shared volumes for organization-wide access