Start a session¶

Codespaces are an asset of a Use Case. They store notebooks and associated files. This page outlines how to start a codespace session, upload files to a codespace, and manage its contents. You can view and manage codespaces from the Notebooks tile of the Use Case home page.

Review the capabilities overview and limits in the tabs below.

Add a codespace¶

To get started creating a codespace:

1. Navigate to the Use Case in which you want the codespace included and expand the Add dropdown. Hover on **Codespace and click:

   • Add codespace to create a new codespace and add files after creation.
   • Upload codespace to create the new codespace from local storage or a public or private repository.

   

Start a codespace session¶

To manage the contents of the codespace file system or edit and execute its files, you must first start the codespace's environment. Click the Session environment tile to configure the environment. The environment image determines the coding language, dependencies, and open-source libraries used in the notebook. The default image for a codespace is a pre-built Python image but you can also use a custom environment for the codespace session.

Once the environment is selected, you can choose a version ior use the default Latest. Then, start the container by toggling it on in the toolbar. Wait a moment for the environment to initialize, and once it displays the Started status, you can begin working with the codespace.

Codespace environment variables¶

For codespace entities, environment variables are defined at the codespace level and not the individual notebook file level. When a codespace session is started, DataRobot sets all environment variables defined in the Environment Variables tab. You can retrieve these environment variables, via code, from any notebooks in the codespace file system.

To access environment variables, click the Environment variables tile in the sidebar. Then click Create new entry. In the dialog box, enter the key and value for a single entry; optionally provide a description.

To add multiple variables, select Bulk import from the entry dropdown. In the entry window, enter each variable, on a new line, in the following format:

KEY=VALUE # DESCRIPTION

When you have finished adding environment variables, click Save.

Work with files¶

Each codespace consists of its own persistent file system, which is mounted to the path /home/notebooks/storage/ when the session begins. (You must start the codespace's environment before uploading files to it.) Click the Files tile in the left sideabar to upload and manage files and folders. You can also create new folders, notebook files, and non-notebook files from the file browser UI. To work with notebooks, upload .ipynbfiles.

Use the icons to:

• Create a notebook, file, or directory.
• Manage file content (copy, cut, paste, and delete).

To manage or edit files from directly within a codespace, expand the Actions menu to the right of the file to view the available actions.

Work with notebooks in a codespace¶

To edit and execute a notebook within a codespace, double click on a notebook file (.ipynb) in the file browser to open it. The codespace interface supports a tabbed experience, so you can open, view, and edit multiple files at the same time. Similar to Jupyter, opening a notebook file will start a kernel process for that notebook. Each opened notebook will run in its own kernel.

DataRobot indicates which notebooks are running in active kernels with the purple notebook icon in the file browser. Inactive notebooks use a white icon.

To shut down a kernel, open the Actions menu for a notebook file and select Shut down kernel.

Work with non-notebook files¶

In addition to editing and executing notebooks, codespaces offer a text editor for you to also view and edit other file types. For example, as shown below, you can view image files and edit Python utility scripts.

Persistent dependency installations¶

When you install runtime custom dependencies into a codespace during an active session, Python and pip dependencies and HuggingFace artifacts can persist across sessions if they are installed to the user's virtual env. This persistent dependency installation capability is only supported when Python-based images are used for the codespace session.

A codespace has two virtual environments:

• The user virtual environment,(/home/notebooks/storage/.venv): A new user virtual environment that persists any custom dependencies that are installed at runtime throughout codespace sessions. This venv is associated with the codespace (since it's persisted in the codespace file system), so all users who have access to the codespace will be able to access the same set of persisted pip installations when they start the codespace session.

• The kernel virtual environment, (/etc/system/kernel/.venv): A built-in image virtual environment that holds all dependencies that DataRobot provides as a part of the selected notebook environment image. This virtual environment does not maintain any custom dependencies that you install; it maintains them for the duration of the session.

Although you cannot directly access the user virtual environment from the UI (it is not shown in the codespace file system panel), you can access it via the terminal. This is where you can install custom dependencies that will persist across sessions via !pip install <PACKAGE_NAME>.

By default, all new dependencies you install via !pip install will go into the user venv. The user venv takes precedence if you install a different version of a library DataRobot provides as a part of the built-in notebook image.

Disable persistent dependency installations¶

If you want to disable persistent dependency installation for a given codespace, first add a new environment variable NOTEBOOKS_NO_PERSISTENT_DEPENDENCIES=1 to the codespace. Then, run rm -rf /home/notebooks/storage/.venv from the codespace terminal to remove the existing user venv. After that, restart your codespace session. Any Python dependencies installed at runtime will no longer be persisted between sessions.

Dependency installation considerations¶

DataRobot packages¶

If you use the dependency installation feature to install the datarobotx package or newer versions of the datarobot package (newer than the version preinstalled in the built-in images), you can corrupt the preinstalled datarobot package included with other DataRobot packages (e.g., datarobot-mlops-connected-client). This is because when you install a new package or a new version of an existing package in an active codespace session, it’s installed into the user's virtual environment which takes precedence over the kernel virtual environment. Installing the datarobotx package creates the datarobot package in the user's virtual environment, preventing the correct installation in the kernel environment. This interferes with the successful installation of packages such as the datarobot-mlops-connected-client; however, pip (or your package manager of choice) still registers the package as installed.

To resolve this error, run pip install with --force-reinstall for all shadowed libraries extending the datarobot package (e.g., datarobot-mlops-connected-client). For example pip install datarobot-mlops-connected-client --force-reinstall.

Updating dependencies¶

After importing a dependency, you may upgrade it over time. Because DataRobot does not automatically recognize these dependency changes, you must restart the kernel in order for DataRobot to recognize the changes. To do so, click the restart icon (the circular arrow) in the toolbar.

Check import locations¶

To check where a dependency was imported from, run the following command in a notebook cell or in the terminal.

pip list -v

Package                          Version      Location                                             Installer
-------------------------------- ------------ ---------------------------------------------------- ---------
...
datarobot                        3.3.0        /etc/system/kernel/.venv/lib/python3.9/site-packages pip
...

To check the size of a user virtual environment, run the following command in the terminal.

(.venv) [notebooks@kernel ~/storage]$ du -h . -d 1
14M     ./.venv
14M     .

If your user virtual environment seems broken and you want to recreate it, run the following command in the terminal.

rm -rf /home/notebooks/storage/.venv
python -m venv /home/notebooks/storage/.venv

Next steps¶

With a codespace session running, automate notebook runs on a schedule or use the integrated terminal to manage your environment further.

• Connect a local IDE to a codespace: Open the codespace from Visual Studio Code over SSH.
• Codespace scheduling: Automate code-based workflows by scheduling notebooks in a codespace to run in non-interactive mode.
• Notebook terminals: Use the integrated terminal to run shell commands, install packages, and execute scripts in a codespace session.
• Manage the notebook environment: Configure the resource type, environment image, and inactivity timeout for a codespace session.