rustygate

A Jupyter kernel gateway as one binary: kernels, terminals, files, search, and per-cell notebook operations, over the same REST and websocket API shapes jupyter_server uses.

Running

rustygate [--host H] [--port N] [--token T | --token-file PATH] [--trust-loopback] [--root DIR] [--tls]

The defaults are 127.0.0.1, port 8787, no auth, and the working directory as the files root. With a token set, requests carry Authorization: Bearer T; Jupyter's Authorization: token T form and ?token=T are also accepted. --token-file reads the token without putting it in the process arguments. --trust-loopback lets clients whose actual TCP peer is loopback omit the token. Do not use it behind an untrusted same-host reverse proxy, since the proxy is the TCP peer. Forwarded headers never affect authentication. --tls serves https and wss from a self-signed certificate generated at startup; clients opt out of verification (jupyasyncclient's verify=False).

Running as a service

rustygate service installs and controls a user service using launchd on macOS and systemd on Linux:

rustygate service install --root ~/git --workdir ~/git/project
rustygate service status
rustygate service restart
rustygate service stop
rustygate service start
rustygate service uninstall

install starts the service immediately; running it again replaces the configuration. Add --host 0.0.0.0 for direct network access, --token-file ~/.config/rustygate/token for authentication, --trust-loopback when same-host clients should not need that token, and --tls when wanted. A missing token file is generated with user-only permissions. --env-file sources environment variables inherited by kernels. The service PATH is the rustygate binary's own directory (the venv bin, under a pip install) plus the standard system directories, so kernels find python despite the minimal launchd and systemd defaults. The default loopback service can instead be reached remotely through an SSH tunnel.

GET / lists every route with a one-line summary, and GET /help/<path> describes the routes at a path (a template such as api/kernels/{kid}, or a concrete path): each method's parameters, query keys, body shape, and what it does. The text comes from the handlers' doc comments through the docments crate, so it cannot drift from the code.

GET /openapi.json is the same API as an OpenAPI 3.1 document, with request and response schemas generated (via schemars) from the typed query, body, and model structs the route table declares. The two websocket routes describe their message protocols in prose, since OpenAPI has no channel vocabulary.

MCP

POST /mcp is a stateful Streamable HTTP MCP server for Claude Code and other MCP clients. Its tools list, create, select, restart, interrupt, and delete kernels, plus execute Python/IPython cells (py); code runs exactly as written, so magics like a %%bash first line work unchanged. The MCP transport session remembers its current kernel server-side, so the model does not need to carry an id between calls. Executing with no kernel current starts one for the session, and ending the session (DELETE /mcp, which Claude Code sends on shutdown) stops every kernel the session created with autoclose. create(dlgname) is get-or-create by kernel path and autocloses its kernel by default (autoclose=false keeps it); an execution may name another existing binding for that call without changing the current selection. A client may also send per-session creation defaults (cwd, env, startup code, quiet) in its initialize params; see DEV.md.

POST /mcp/{path} is the smaller stateless alternative for clients configured for one dialog. The URL-decoded relative path is the fixed kernel binding, so no MCP session id or model-visible kernel selector is needed. It exposes only py and interrupt; the first execution lazily gets or creates the bound kernel, while interrupt never creates one. Its tool executions use kernel priority 1, ahead of queued normal-priority notebook runs without preempting a cell already running.

Kernels actually spawned through MCP receive RUSTYGATE_LAUNCHER=mcp, available during their startup profiles and preserved across restart. Selecting or get-or-creating a kernel that was already running does not alter its environment. See DEV.md for the tool and execution contract.