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
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.
spell jupyter command works similarly to
spell run, taking many of the same parameters such as
--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.