What Is a Workspace?

The Basics

Jupyter Workspaces are collections of files, notebooks, and other related resources that can be run using a Jupyter Notebook or JupyterLab.

You can launch a Jupyter Workspace from Spell's web console, or from the CLI. For more on how to install the CLI, go to our Quickstart docs.

Creating a Workspace in the Web

Workspaces are created using the Create New Workspace button at the top right of the Workspaces section of the web console.

This will launch the Create Workspace wizard, which will take you through the steps to add code and resources to your Notebook server environment.

1: Name and Code

First, you'll be asked to give your Workspace a name (required). You'll also have the option to add code by initializing your Workspace from a GitHub repository. If you enter a URL for a public GitHub Repo, your Workspace environment will be initialized with all the files and notebooks associated with that repo.

In the below screenshot, we are intitializing our Workspace with a style transfer repository.

A screenshot of the first screen in the create new workspace wizard

2: Environment

Next, you'll set your environment settings. This includes choosing a machine type (a full list of machine types is available in our FAQs), a framework, JupyterLab/Notebook, and adding any optional dependencies such as pip or apt packages.

Since the code running inside this Workspace doesn't need other dependencies, we don't need to add additional pip and apt dependencies beyond what's included in the Spell default environment.

A screenshot of the second screen in the create new workspace wizard

3: Datasets

Adding datasets is optional. While you can add datasets by including them in a GitHub repo and adding that in step 1, it is better to upload the datasets to Spell and mount them into your Workspace. This way multiple Workspaces can quickly access the same dataset without having to upload it to Spell more than once. This is especially useful for teams where multiple people are using the same dataset for their work.

For this example, we will add one image from our uploads folder. (For more on how to upload files, see our uploads docs). To do this, we navigate to the directory or file we want, it to our mounts. We can also rename the mount using the pencil (edit) icon in the mounted resources list. Here, we've renamed bw-water.png to water.png.

A screenshot of the third screen in the create new workspace wizard

4: Confirm Variables

The final screen in the wizard asks you to confirm your settings. You'll be able to change most of these settings later by editing your Workspace.

A screenshot of the final screen, a receipt of the selections from past screens, in the create new workspace wizard

Creating a Workspace in the CLI

You can also create a workspace and launch a notebook server from the CLI using the spell jupyter command.

The spell jupyter command works similarly to spell run, taking many of the same parameters such as --machine-type, --framework, and --pip. Additionally, you can specify if you want to launch JupyterLab with --lab (the default is Jupyter Notebook). To read more about the command and its parameters, go to our CLI reference docs.

If the command is run from within a Git repository, any code and files committed to that repo will show up in the Jupyter workspace.

The only required argument is a workspace name. Below is an example of a spell jupyter command:

$ spell jupyter -t K80 --framework tensorflow --pip joblib -m myFile myNewWorkspace

The command will automatically launch a notebook server.

The Notebook Server

The Notebook Server contains your Jupyter Notebook or JupyterLab workspace, and the Spell header where you can stop your notebook. As you can see, the files and directories we added in the Creating a Workspace in the CLI step are all included in our JupyterLab file system.

A screenshot of the JupyterLab Server

Editing a Workspace Environment

You can only edit the environment of a stopped workspace. This includes actions like: editing the Workspace name and description adding pip and apt packages changing the machine type changing the framework * changing between Jupyter Notebook and JupyterLab

The only selection from the Create Workspace flow that you are not able to change is how your Workspace was initialized (empty or with code from a GitHub repository).

You can stop your workspace using the stop button in the header of your Notebook Server. Once the notebook is stopped, you can edit the workspace using the Actions dropdown to the top right.

A screenshot of the workspace list page with the action menu opened and edit workspace selected

Collaborating on the Same Workspace

Team members can view, edit, restart, and duplicate each other's stopped workspaces.

Note

Only one person is allowed to run a notebook server in a workspace at a time. A notebook server must be stopped before another person can edit the workspace or restart the notebook server.

Duplicating a Workspace

Team members can also duplicate each others' (or their own) workspaces by selecting Duplicate Workspace from the Actions dropdown menu of a stopped workspace.

Screenshot showing how to duplicate a workspace from the Workspace List page: A screenshot of the workspace list page with the action menu opened and duplicate workspace selected

Screenshot showing how to duplicate a workspace from a stopped Workspace Details page: A screenshot of a stopped notebook server page with the action menu opened and duplicate workspace selected

Sharing A View-Only Notebook File

You can share a view-only version of a Notebook file (.ipynb) to users within your organization. To do this, navigate to the Files tab of your Workspace, find the .ipynb file you want to share, click the three dot action item on the right side of the row, and select Open as view only. You can now share this page with anyone with access to your Spell organization.

A screenshot of a stopped notebook server page with the action menu opened and duplicate workspace selected

Export Notebook As Python Script

You can download a Notebook file (.ipynb) as a Python script (and run it on Spell!). navigate to the Files tab of your Workspace, find the .ipynb file you want to share, click the three dot action item on the right side of the row, and select Export notebook to script. The file will automatically download as a .py Python script.

To run this on Spell, add your file to a repository and initiate a Spell run from that repo.

Saving Files From a Workspace

You can save files and directories directly from your Workspace to Spell File System (without downloading/uploading). To do this, first stop your Workspace. Once the workspace has stopped navigate to the Files tab. Find the file you want to save to SpellFS, click the three dots to the right side of the row, and select Publish file to SpellFS.

A screenshot of a stopped notebook server page on the files tab with the dropdown open for a single file and publish file to spellfs selected

Mount Files Into a Running Workspace

You can add resources in the Spell File System (uploads, run outputs, public data, and buckets) to your Workspace while it is running. Navigate to the Files tab of your running Workspce. Click the Add mount button at the bottom of the page and select the resource to be mounted.

A screenshot of a stopped notebook server page on the files tab with the dropdown open for a single file and publish file to spellfs selected