Jupyter Server Proxy

4.5.0 · active · verified Wed Apr 15

Jupyter Server Proxy is a Jupyter server extension that enables running arbitrary external processes (like RStudio, Shiny Server, Code Server) alongside a Jupyter notebook server and providing authenticated web access to them via proxied paths (e.g., /rstudio). It comes bundled with a JupyterLab extension to launch pre-defined processes. The current version is 4.5.0, and it generally follows a regular release cadence with bug fixes and new features, with major versions indicating potentially breaking changes.

Warnings

breaking Version 4.0.0 introduced several breaking changes: it now requires Python 3.8+, dropped support for JupyterLab 2, and renamed the JupyterLab extension from `@jupyterlab/server-proxy` to `@jupyterhub/jupyter-server-proxy`.
Fix: Ensure your environment meets Python 3.8+ and JupyterLab 3+ requirements. Update any references to the old JupyterLab extension name.
deprecated The `nbserverproxy` package is an older version and conflicts with `jupyter-server-proxy`. Installing both can lead to unexpected behavior or errors.
Fix: Uninstall `nbserverproxy` before installing `jupyter-server-proxy` using `pip uninstall nbserverproxy`.
gotcha When configuring proxying to *remote* hosts, simply setting `c.ServerApp.allow_remote_access = True` is insufficient. Jupyter Server Proxy uses its own `host_allowlist` configuration.
Fix: Use `c.ServerProxy.host_allowlist = ['example.com', '192.168.1.1']` (or a similar list of allowed hosts) in your `jupyter_server_config.py`.
gotcha It is a significant security concern if processes started by Jupyter Server Proxy can be accessed directly, bypassing Jupyter's authentication and authorization mechanisms.
Fix: Always ensure that the proxied processes are only accessible through the Jupyter Server's proxy endpoint. A common strategy is to run Jupyter Server within a container and restrict network access to only the Jupyter Server itself.
breaking Critical security vulnerabilities have been identified: Reflected XSS (CVE-2024-35225) due to unsanitized host parameter, and unauthenticated Websocket Proxying (CVE-2024-28179). These could allow an attacker to execute arbitrary JavaScript or bypass authentication for websocket connections.
Fix: Upgrade to jupyter-server-proxy 4.5.0 or later immediately to patch these vulnerabilities.

Install

pip install jupyter-server-proxy Standard Installation
pip install jupyter-server-proxy[standalone] Installation with Standalone Proxy
conda install -c conda-forge jupyter-server-proxy Conda Installation

Imports

ServerProxy
```
This is primarily configured via `jupyter_server_config.py` using `c.ServerProxy.servers`.
```
Jupyter Server Proxy is typically configured through Jupyter's configuration system (traitlets in files like `jupyter_server_config.py`) rather than direct Python imports in user application code. Direct imports like `from jupyter_server_proxy.handlers import ProxyHandler` or `from jupyter_server_proxy.config import ServerProxy` are for advanced use cases like building custom extensions or programmatic configuration, not common end-user interaction.

Quickstart

To use jupyter-server-proxy, you typically create a configuration file (e.g., `jupyter_server_config.py`) in your Jupyter config directory (often `~/.jupyter/`). In this file, you define the external processes you want to proxy using the `c.ServerProxy.servers` traitlet. The `command` list specifies how to start the process, with `{port}` being a mandatory placeholder that jupyter-server-proxy replaces with an available port. After configuring and restarting your Jupyter server, the proxied services become accessible via URLs like `<jupyter-url>/proxy/<server-name>/` or through launcher entries in JupyterLab if specified.

import os

# To configure jupyter-server-proxy, create or edit a file like
# ~/.jupyter/jupyter_server_config.py (or another config path)
# Example content for jupyter_server_config.py:
#
# c.ServerProxy.servers = {
#     'my-http-server': {
#         'command': ['python3', '-m', 'http.server', '{port}'],
#         'timeout': 20,
#         'launcher_entry': {
#             'title': 'My HTTP Server',
#             'enabled': True
#         }
#     },
#     'another-app': {
#         'command': ['sh', '-c', 'echo "Hello, {base_url}/proxy/{port}" > /tmp/output.txt && sleep 99999'],
#         'launcher_entry': {
#             'title': 'Another App',
#             'enabled': True
#         }
#     }
# }

print("Jupyter Server Proxy is configured via `jupyter_server_config.py`.")
print("Once configured, restart your Jupyter server.")
print("You can typically access proxied services at a URL like:")
print("  <jupyter-url>/proxy/my-http-server/")
print("Or launch from the JupyterLab Launcher if `launcher_entry` is enabled.")

# Example to demonstrate a command that could be run via the proxy (won't actually start here)
# For a real quickstart, this configuration needs to be placed in a .py config file.
# The '{port}' placeholder is crucial and is replaced by jupyter-server-proxy.
example_command = ['python3', '-m', 'http.server', '{port}']
print(f"\nExample command that can be proxied: {example_command}")

view raw JSON →