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.