Jupyter SuperKernel

Bring remote Python, MPI, and PyTorch compute into JupyterLab with the Super Kernels sidebar.

jupyter-superkernel adds the JupyterLab interface for signing in to a SuperKernel Gateway, creating remote kernels, selecting them from the normal Jupyter kernel picker, and managing their lifecycle. Notebook execution is provided by the companion superkernel runtime, which is installed automatically.

Features

• Add and manage multiple SuperKernel Gateways.
• Create Base Python, MPI, and PyTorch kernels from available runtime images.
• Choose node, CPU, and memory settings from a compact native JupyterLab UI.
• See preparing, ready, busy, idle, paused, and error states.
• Pause, resume, restart, or delete remote kernels.
• Inspect and clean up local notebook runtime sessions.
• Use standard Jupyter notebook execution, interruption, and restart actions.
• Share the same local Gateway and kernel configuration with the SuperKernel VS Code extension.

Requirements

• Python 3.10 or newer
• JupyterLab 4
• Access to a SuperKernel Gateway and a valid API key

Installation

Install the package into the same Python environment that runs JupyterLab:

uv pip install jupyter-superkernel

For a JupyterHub installation, select its Python environment explicitly:

uv pip install --python /path/to/jupyterhub/bin/python jupyter-superkernel

Restart JupyterLab or JupyterHub after installation. The Python server extension and prebuilt JupyterLab extension are included in the wheel; no Node.js build is required.

Getting started

1. Open JupyterLab and select the Super Kernels icon in the left sidebar.
2. Under Gateways, choose Add Gateway and enter the Gateway URL and API key supplied by your administrator.
3. Under Kernels, choose Add Kernel.
4. Select a logged-in Gateway, runtime image, and compute configuration.
5. Create or open a notebook and select the new kernel from Jupyter's standard kernel picker.

Kernel cards show their current configuration and status. Lifecycle controls on each card let you pause or resume compute when it is not needed, restart a kernel, or delete it. Local runtime rows identify notebook sessions currently using that remote kernel and provide a targeted cleanup action.

Cells run in submission order. Normal Python cells keep a persistent namespace for that notebook session. Cells beginning with ! or % run as shell commands in the selected remote runtime.

Security

The API key is used only during Gateway login and is not stored. The resulting session is saved in a private local authentication file and never embedded in notebooks or Jupyter kernelspecs. Installed kernelspecs contain only the Gateway address, remote kernel identifier, and a reference to that private authentication file.

Local SuperKernel state is stored under ~/.superkernel with restrictive file permissions so the JupyterLab and VS Code integrations can safely share the same Gateway logins and kernel registrations.

Troubleshooting

If the sidebar does not appear after installation, restart Jupyter and verify that both extensions are enabled:

jupyter server extension list
jupyter labextension list

Both lists should show jupyter_superkernel or jupyter-superkernel as enabled and valid.

Project status

Version 0.9.0 is the first public alpha release. It is intended for evaluation, and its integration contract may still evolve before 1.0.

Learn more at superkernel.leoustc.com.