Metadata-Version: 2.4
Name: rustygate
Version: 0.1.8
Classifier: Programming Language :: Rust
Classifier: License :: Other/Proprietary License
Requires-Dist: fastcore>=2.2.11
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: pytest-timeout ; extra == 'dev'
Requires-Dist: httpx ; extra == 'dev'
Requires-Dist: websockets ; extra == 'dev'
Requires-Dist: jupyter-client ; extra == 'dev'
Requires-Dist: jupygate ; extra == 'dev'
Requires-Dist: ipymini ; extra == 'dev'
Provides-Extra: dev
Summary: Jupyter kernel gateway with terminals, files, and cells APIs, as a single binary
Author: Jeremy Howard
Maintainer-email: "fast.ai" <infos@fast.ai>
License: Proprietary
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/AnswerDotAI/rustygate
Project-URL: Issues, https://github.com/AnswerDotAI/rustygate/issues
Project-URL: Repository, https://github.com/AnswerDotAI/rustygate

# 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] [--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. `--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, 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](https://github.com/AnswerDotAI/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](https://docs.rs/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](DEV.md#mcp-api).

`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](DEV.md#mcp-api) for the tool and execution contract.

