Workspaces

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.

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.

Next you'll set your environment settings. This includes choosing a machine type, installing any additional pip or apt packages, and setting any environment variables you need. If you have a conda requirements file you would like to use, you can set it here.

Note the inclusion of the Notebook Timeout. This allows you to configure an idle timeout: how long Spell will wait before shutting down the instance in the event of inactivity. By defualt, Spell uses an idle timeout of 30 minutes. This value can be adjusted anywhere from 5 minutes to Never.

The next screen allows you to add resources to the workspace. This step is optional. See the Resources page for more information. In this example, we will add cifar10, a folder containing data we previously uploaded to Spell, to the workspace.

After passing through one final conformation screen, the workspace will be created and launched.

Editing the workspace environment

You can edit a workspace after creation. First of all, make sure it is stopped. Then visit the workspace page, go to the "Details" tab, and click on "Actions" and then "Edit Workspace" on the top right. This will take you to the workspace edit menu:

The only aspects of a workspace that are not configurable after creation are the idle timeout and the GitHub repository the workspace was initialized with.

Starting or stopping a workspace

Creating a workspace will launch it automatically.

You may stop a running workspace from within the workspace by clicking on the orange "Stop" button on the top right of the screen Alternatively, you may stop it from the workspace list page by using the "Stop Notebook Server" option in the workspace actions list.

You can restart a stopped workspace by visiting the workspace page and clicking the "Start" button on the top right.

Team members can view, edit, start, and restart each others' stopped workspaces. However, only one person is allowed to run a workspace at a time. A notebook server must be stopped before another person can edit the workspace or restart the notebook server.

Mounting files to a running workspace

You can edit workspace resources while it is running. To do so navigate to the Files tab of your running Workspce. Click the Add Mount button on the bottom left and select the resource to be mounted.

Duplicating a workspace

Team members can freely duplicate one another's workspaces. To do so visit the workspace page, go to "Details", click on "Actions", and then click "Duplicate Workspace" on the top right.

This action can also be performed using the actions menu on the workspace list page.

Opening a workspace notebook in view-only mode

Anyone in the organization can open a Jupyter Notebook file (*.ipynb) in any workspace in view-only mode. This can even be done on running workspaces reserved by a different user.

To do this, navigate to the Files tab of the Workspace, find the .ipynb file you want to view, click the three dot action item on the right, and select Open as view only.

(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, --pip, and --apt. The only required argument is a workspace name. Below is an example of a spell jupyter command:

$ spell jupyter \
    --machine-type T4 \
    --pip joblib \
    --lab \
    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.

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.

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

(Advanced) Using workspaces in VSCode

If you'd prefer to edit and run your ipynb files from VSCode you can head to the Details tab for a running workspace and click the button at the bottom of the first section to copy the notebook URL to you clipboard. Following these instructions you can setup VSCode to execute on your remote Jupyter server.

This gives you easy access to varied machine types such as GPUs, as well as automatically providing metrics in the Spell website UI so you can see where your resource constraints are or how well the training is going over time. Any files you create via your notebook execution will be saved to the Spell Filesystem to help you track your work and make any data or models available for other workspaces, runs, or servers.

Note a limitation of the VSCode Jupyter support is that you're not able to access the remote ipynb files on the server. If you'd like to use those you will need to clone those locally and open the local copy in VSCode.