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.

To update the list of Python packages installed in a running workspace, navigate to the "Details" tab, then click on the edit icon in the "Environment" card.

For all other changes, you will need to stop the workspace first. 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.

Managing workspace extensions

Because Spell workspaces are a thin wrapper around JupyerLab, they support JupyterLab extensions.

Spell workspaces install the following extensions by default:

jupyterlab-git~=0.32.2
ipywidgets~=7.7.0

You can install additional extensions in workspaces (or install a different version of these preinstalled extensions) in the usual way. As of JupyterLab 3.0, this is usually as simple as installing the extension's Python package.

Note that if your workspace uses a conda environment, you must install the extension using the --conda-env flag, not the --pip or --requirements-file flags.

Note that new extensions will not be loaded until JupyterLab restarts. You will need to stop and restart the workspace in order for the changes to take effect.

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.

Using the Spell client from within a workspace

Workspaces are provisioned with the Spell client installed. The client is configured with the credentials of the user that is currently using the workspace. This allows you to use Spell CLI and Python API commands without needing to perform any further configuration.

Committing changes to GitHub

You may commit any changes you make in a workspace back to GitHub. We recommend using the JupyterLab Git extension, which comes preinstalled in Spell workspaces by default.

To begin, click on the Git icon in the menu bar on the far left. This will open the Git pane:

Stage the changes you wish to push and create a commit for them. Then click on the "Push committed changes" button on the top right to push your changes. The first time you do so in a new workspace session, you will be prompted to provide your GitHub username and Personal Access Token:

Provide valid credentials and will push your changes to the repository. This flow works for both public and private repositories. Note that you must use a personal access token, as GitHub no longer supports commits authenticated using your user password.

This flow can can also be performed using the git add, git commit, and git push command-line instructions.

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 the JupyterLab kernel remotely

JupyterLab supports remote execution of notebooks using the server kernel. In this mode, the Jupyter Notebook is opened and edited on a remote client (your local machine), but all of the code you run within the notebook is actually executed on the server (the JupyterLab server process).

Spell supports this flow. To use it, start a new workspace on Spell, then navigate to the Details tab. Click the "Copy" button in the "Notebook URL" section. This will add a long secret JupyterLab connection URL that looks something like the following to your clipboard:

https://api.spell.ml/notebooks/sbnDavdrMIY90k_FlMorYeZvC-U?token=1f8de781c1e2bb41d40cb221b8613bd8467f3f97c9e241bb

You may then connect to this running workspace by passing this URL to any tool that supports this feature (remote JupyterLab connections).

For example, this feature is built into Visual Studio Code—refer to their documentation page "Connect to a Remote Jupyter Server" for details. After following the instructions therein, any notebook (*.ipynb file) you create in Visual Studio Code anywhere on your machine will connect to the remote kernel automatically.

You may confirm that the connection is working by running the command !hostname within a notebook cell—this should print spell.

This feature has a number of limitations to keep in mind:

• Your local notebook can view and read files within the workspace. Any new files you create from within the notebook (using e.g. %%writefile) will be created in the workspace, not on your local machine.
• Any files you create or modify will be written to SpellFS at the end of the run, as usual.
• Your local notebook cannot be seen or interacted with from within the workspace.
• Your local notebook will not be backed up to SpellFS at the end of the run.
• Workspace resource utilization (e.g. disk, memory, etcetera) will be logged on Spell as usual.