Jupyter Kernel Agent

Jupyter Kernel Agent lets you run Jupyter code remotely by forwarding code to an HTTP endpoint and streaming results back in Jupyter’s native format.
Connect your Jupyter environment to clusters, GPU servers, or any backend that implements the Kernel Agent API.

Features

• 📡 Remote code execution over HTTP
• 🔑 Bearer token authentication
• 🖥️ Multiple backends (one kernel per endpoint)
• 🔄 Built-in magics for session management:
  • %reset — clear remote namespace / start new session
  • %shutdown — shut down remote session
  • %welcome — show kernel info
  • %reconnect — reconnect after disconnect
• 🛑 Disconnection handling: hold (default) or exit

Installation

pip install jupyter-kernel-agent

This provides two CLI tools:

• agent-server — run the FastAPI backend for code execution
• kernel_agent — manage Jupyter kernelspecs (install/list/delete)

Running the Server

Start the server with an API key:

agent-server --host 0.0.0.0 --port 8000 --api_key SECRET123

Test with curl:

curl -sX POST http://127.0.0.1:8000/kernel \
  -H "Authorization: Bearer SECRET123" \
  -H "Content-Type: application/json" \
  -d '{"action":"execute","session_id":"s1","code":"1+1","execution_count":1}'

Expected response:

{"ok":true,"outputs":[{"type":"execute_result","data":{"text/plain":"2"},"execution_count":1,"metadata":{}}]}

Installing a Jupyter Kernel

Install a kernel that connects to your server:

kernel_agent install \
  --endpoint http://127.0.0.1:8000/kernel \
  --name local \
  --api_key SECRET123 --user

List installed kernels:

kernel_agent list

You should see your new kernel listed and available in Jupyter.

System-wide Installation

To install for all users (e.g., JupyterHub):

sudo kernel_agent install \
  --endpoint http://127.0.0.1:8000/kernel \
  --name cluster \
  --api_key SECRET123 \
  --sys-prefix

Or specify a custom prefix:

sudo kernel_agent install \
  --endpoint http://127.0.0.1:8000/kernel \
  --name cluster \
  --api_key SECRET123 \
  --prefix /usr/local

Verify with:

jupyter kernelspec list

Usage in Notebooks

After installation, select your kernel (e.g., local or cluster) in Jupyter and run code as usual:

1+1
!uname -a
%reset

Outputs will be returned from the remote server.

License

Apache-2.0