What Is a Workspace

Workspaces are collections of files, notebooks, and other related resources that can be run using a Jupyter Notebook or JupyterLab. Workspaces are still just runs under the hood: we manage all of the compute and storage for you, so that you can focus on the code.

A screenshot of the JupyterLab Server

Creating a workspace using the web console

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

First, you'll be asked to give your Workspace a name. You'll also have the option of initializing your Workspace from a GitHub repository.

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

Next you'll set your environment settings. This includes choosing a machine type (for a full list of the machine types available see the page "Instance types"), a framework, toggling JupyterLab or Jupyter Notebook, and adding any optional pip or apt packages.

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

The next screen allows you to add resources to the workspace. This is optional. See the Resources page for more information.

For this example, we will add one image from our uploads folder. (For more on how to upload files, see the page "What Is A Resource?". To do this, we navigate to the directory or file we want and add 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

The fourth and final screen is a confirmation screen. Note that you'll be able to change most of these settings later.

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

Editing the 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
  • Switching 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

Mounting files to a running workspace

You can edit workspace resources (e.g. uploads, run outputs, public data, and buckets) while it is running. To do so 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

Sharing workspace notebooks

You can share a view-only version of any Jupyter Notebook files (.ipynb) in your workspace with anyone else in 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, and select Open as view only.

Sharing a workspace

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

Note however that 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 in your organization can freely duplicate each other's workspaces.

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

(Advanced) Creating a workspace using 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. The only required argument is a workspace name. Below is an example of a spell jupyter command:

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

If the command is run from within a Git repository, any code and files committed to that repo will be added to the workspace.

Additionally, you can specify that 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.

(Advanced) Exporting a notebook as a script

You can download a Notebook file (.ipynb) as a Python script (.py). 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, and select Export notebook to script.

(Advanced) Publishing workspace files to SpellFS

By default, the files inside of a workspace will only be visible within that workspace. To make those files visible to other workspaces and/or runs (without downloading/uploading), you can publish the files (as resources) to SpellFS.

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, 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

The files will be available under the workspace_exports path in SpellFS.