kernel_gateway

Jupyter Kernel Gateway is a standalone Tornado web server that provisions and proxies access to Jupyter kernels over HTTP and WebSockets, without any of the Jupyter Notebook or JupyterLab editing UI. Client applications talk to kernels through REST calls to start and stop them and through WebSocket connections that carry the Jupyter kernel protocol directly, the same wire protocol notebook front-ends use, so any client that speaks it can drive a remote kernel.

Beyond raw kernel access, its notebook-http personality turns an existing notebook into a web API: cells are annotated with the HTTP verb and path they should answer, and the gateway executes the matching cell in a pooled kernel whenever a matching request arrives, optionally emitting a Swagger/OpenAPI spec for the resulting endpoints. This makes it a lightweight way to run interactive compute at the edge of a data pipeline, attach a notebook client to a remote cluster, or turn a data-science notebook into a microservice, all while reusing the same kernel-launching code as Jupyter Notebook itself.

What You Get

• A Tornado-based server exposing the Jupyter kernel protocol over WebSockets and kernel lifecycle management over REST
• A notebook-http mode that serves HTTP requests directly from annotated notebook cells, with automatic Swagger/OpenAPI generation
• Token-based request authorization and configurable CORS headers via reusable Tornado handler mixins
• TLS/SSL support (keyfile, certfile, client CA) and pluggable identity/authorization providers built on jupyter_server
• Extensive environment-variable configuration (KG_*) for port, base URL, kernel limits, seeding notebook, and pool pre-spawning, suited to container and cloud deployment

Common Use Cases

• Attaching a local Jupyter Notebook or JupyterLab client to kernels running near data or compute in the cloud
• Turning a data-science notebook into a lightweight HTTP microservice without rewriting its logic as an application
• Giving non-notebook web clients (dashboards, custom UIs) programmatic access to provision and drive kernels
• Running headless, scaled-out kernel execution behind a load balancer using tools like Kubernetes or Cloud Foundry

Under The Hood

Architecture KernelGatewayApp (kernel_gateway/gatewayapp.py), a traitlets-based JupyterApp subclass, owns process-level configuration (port, ip, base_url, auth token, CORS headers, TLS) and wires up one of two “personality” classes at startup: JupyterWebsocketPersonality (jupyter_websocket/) or NotebookHTTPPersonality (notebook_http/), each contributing its own set of Tornado routes to the shared application. Both personalities sit on top of SeedingMappingKernelManager and SessionManager (services/), which extend jupyter_server’s kernel/session managers, and on jupyter_server’s BaseKernelWebsocketConnection/ZMQChannelsWebsocketConnection for the actual kernel wire protocol. Cross-cutting handler behavior (CORS, token auth, JSON error formatting) is composed via mixins (mixins.py) rather than deep inheritance, and notebook_http/handlers.py’s NotebookAPIHandler executes annotated cells against a pooled kernel client, resolving iopub message callbacks into futures to produce the HTTP response. Because both personalities plug into the same Tornado application object at boot, changing how KernelGatewayApp initializes them would touch the entire request-routing surface.

Tech Stack Built for Python 3.8+ on Tornado for the HTTP/WebSocket server and traitlets/JupyterApp for CLI and environment-variable driven configuration. Kernel lifecycle and protocol handling rely on jupyter_client, jupyter_core, and jupyter_server (kernelspec management, kernel connection channels, mapping kernel manager), with nbformat used to read seed notebooks and requests for outbound HTTP. The project builds with hatchling and ships to PyPI as jupyter-kernel-gateway, installing a jupyter-kernelgateway console script.

Code Quality The test suite (tests/) covers app configuration, both personalities, and the notebook-http cell/swagger parsers using pytest with pytest-cov and pytest_jupyter fixtures. CI runs the suite across Ubuntu and macOS on Python 3.8 through 3.12 via hatch, enforces a per-run coverage floor and an 80% overall coverage gate, and runs a dedicated lint job, alongside pre-commit hooks configured in the repo. Error handling favors explicit, typed exceptions (CodeExecutionError, UnsupportedMethodError) surfaced as structured JSON error responses rather than being swallowed, and docstrings follow a consistent numpy-style format across handlers and mixins.

API Design The standout design choice is turning an unmodified notebook into a web API purely through cell annotations parsed at startup, with no code changes to the notebook and an automatically generated Swagger/OpenAPI document describing the resulting endpoints. Getting a running API from an existing notebook requires no custom server code, just the jupyter kernelgateway console script and a --seed_uri pointing at it, though the surrounding configuration surface (dozens of KG_* environment variables and traitlets) is broad for teams tuning production deployments.