jupyterlite-remote-server

A JupyterLite extension that connects to a remote Jupyter server for all services (kernels, contents, terminals, etc.).

This extension replaces JupyterLite's in-browser service implementations with standard JupyterLab service managers that communicate with a remote Jupyter server. This allows you to run a static JupyterLite frontend while using a real Jupyter server for all backend operations.

How It Works

The extension provides ServiceManagerPlugins that:

1. Provide standard JupyterLab service managers configured to connect to a remote server
2. Read server connection settings dynamically from PageConfig
3. Provide a vendored theme manager that reads theme assets from a configurable URL

The corresponding JupyterLite in-browser service plugins must be disabled via jupyter-lite.json configuration (see Usage with JupyterLite).

Configuration

Configure the extension by setting these options in jupyter-lite.json.

Default Configuration (All Services)

These options apply to all services unless overridden by service-specific options:

Theme Configuration

Service-Specific Configuration (Optional)

You can configure different URLs and tokens for specific service groups. If not specified, services fall back to the default remoteBaseUrl and remoteToken.

Usage with JupyterLite

1. Start the Jupyter Server

Start a Jupyter server with CORS enabled to allow connections from JupyterLite:

jupyter server --ServerApp.token=my-token --ServerApp.allow_origin='*'

2. Create JupyterLite Configuration

Create a jupyter-lite.json configuration file.

Basic Configuration (Single Server)

Use the default options when all services connect to the same server:

{
  "jupyter-lite-schema-version": 0,
  "jupyter-config-data": {
    "remoteBaseUrl": "http://localhost:8888/",
    "remoteToken": "my-token",
    "fullThemesUrl": "http://localhost:8080/build/themes",
    "disabledExtensions": [
      "@jupyterlite/services-extension:config-section-manager",
      "@jupyterlite/services-extension:default-drive",
      "@jupyterlite/services-extension:event-manager",
      "@jupyterlite/services-extension:exporters",
      "@jupyterlite/services-extension:kernel-manager",
      "@jupyterlite/services-extension:kernel-client",
      "@jupyterlite/services-extension:kernel-spec-client",
      "@jupyterlite/services-extension:kernel-spec-manager",
      "@jupyterlite/services-extension:kernel-specs",
      "@jupyterlite/services-extension:nbconvert-manager",
      "@jupyterlite/services-extension:session-manager",
      "@jupyterlite/application-extension:service-worker-manager",
      "@jupyterlab/apputils-extension:themes"
    ]
  }
}

Advanced Configuration (Multiple Servers)

Use service-specific options when different services need to connect to different servers:

{
  "jupyter-lite-schema-version": 0,
  "jupyter-config-data": {
    "remoteBaseUrl": "http://localhost:8888/",
    "remoteToken": "default-token",
    "remoteContentsBaseUrl": "http://files-server:8889/",
    "remoteContentsToken": "files-token",
    "remoteKernelsBaseUrl": "http://compute-server:8890/",
    "remoteKernelsToken": "compute-token",
    "fullThemesUrl": "http://localhost:8080/build/themes",
    "disabledExtensions": [
      "@jupyterlite/services-extension:config-section-manager",
      "@jupyterlite/services-extension:default-drive",
      "@jupyterlite/services-extension:event-manager",
      "@jupyterlite/services-extension:exporters",
      "@jupyterlite/services-extension:kernel-manager",
      "@jupyterlite/services-extension:kernel-client",
      "@jupyterlite/services-extension:kernel-spec-client",
      "@jupyterlite/services-extension:kernel-spec-manager",
      "@jupyterlite/services-extension:kernel-specs",
      "@jupyterlite/services-extension:nbconvert-manager",
      "@jupyterlite/services-extension:session-manager",
      "@jupyterlite/application-extension:service-worker-manager",
      "@jupyterlab/apputils-extension:themes"
    ]
  }
}

In this example:

• File operations (contents) use http://files-server:8889/
• Kernel operations (kernels, sessions, kernel specs) use http://compute-server:8890/
• All other services fall back to the default http://localhost:8888/

3. Build and Serve JupyterLite

pip install jupyterlite-core jupyterlite-remote-server
jupyter lite build
cd _output
python -m http.server 8080

Then open http://localhost:8080/lab/ in your browser.

Demo

The demo/ directory contains a complete working example with separate servers for contents and kernels. To run it locally:

# Install the demo dependencies
pip install -r demo/requirements.txt

# Build the JupyterLite site
cd demo
jupyter lite build

Then start three terminals:

# Terminal 1 — Jupyter server for contents and other services
jupyter server --port=8888 --ServerApp.token=my-token --ServerApp.allow_origin='*'

# Terminal 2 — Jupyter server for kernels
jupyter server --port=7777 --ServerApp.token=kernels-token --ServerApp.allow_origin='*'

# Terminal 3 — JupyterLite frontend
cd demo/_output
python -m http.server 8080

Open http://localhost:8080/lab/ in your browser.

Plugins Provided

This extension provides the following ServiceManagerPlugins:

Disabled Extensions

The following JupyterLite and JupyterLab plugins must be disabled in jupyter-lite.json to avoid conflicts with the plugins provided by this extension:

Requirements

• JupyterLab >= 4.0.0
• A running Jupyter server with CORS enabled

Install

pip install jupyterlite-remote-server

Uninstall

pip uninstall jupyterlite-remote-server

Contributing

Development install

# Clone the repo and change to the directory
git clone https://github.com/jtpio/jupyterlite-remote-server.git
cd jupyterlite-remote-server

# Set up a virtual environment
python -m venv .venv
source .venv/bin/activate

# Install in development mode
pip install --editable "."
jupyter labextension develop . --overwrite

# Rebuild after making changes
jlpm build

Development with watch mode

# Watch the source directory (in one terminal)
jlpm watch

# Run JupyterLab (in another terminal)
jupyter lab

Development uninstall

pip uninstall jupyterlite_remote_server

Then remove the symlink from jupyter labextension list location named jupyterlite-remote-server.

Packaging

See RELEASE