Kernel Management - nteract Desktop

The runt jupyter commands manage standalone Jupyter kernels (launched outside of the notebook app).

These commands are for standalone kernels started with runt jupyter start. Kernels managed by the daemon (from notebook app) are listed with runt notebooks instead.

Subcommands

Command	Description
`ps`	List running kernels
`start`	Start a new kernel
`stop`	Stop a kernel by ID
`interrupt`	Send interrupt signal to a kernel
`exec`	Execute code in a running kernel
`console`	Launch interactive console (see Console)
`clean`	Remove stale connection files
`sidecar`	Launch sidecar viewer for a kernel

runt jupyter ps

List all running kernels (both standalone and daemon-managed).

runt jupyter ps [--json] [--verbose]

Options

json

boolean

Output in JSON format

verbose

boolean

Show port numbers and connection file paths

Example Output

$ runt jupyter ps
╭─────────────┬──────────┬────────┬──────────┬────────────────────────────╮
│ NAME        │ LANGUAGE │ STATUS │ SOURCE   │ NOTEBOOK                   │
├─────────────┼──────────┼────────┼──────────┼────────────────────────────┤
│ python      │ python   │ idle   │ runtimed │ ~/notebooks/analysis.ipynb │
│ deno        │ deno     │ idle   │ runtimed │ ~/notebooks/script.ipynb   │
│ jovial-goat │ python   │ alive  │ jupyter  │ -                          │
╰─────────────┴──────────┴────────┴──────────┴────────────────────────────╯

SOURCE: runtimed = daemon-managed, jupyter = standalone kernel
NOTEBOOK: Only shown for daemon-managed kernels

Verbose Output

$ runt jupyter ps --verbose

Shows connection details:

╭──────────────┬──────────┬────────┬───────┬───────┬───────┬──────┬────┬──────────────────────────────╮
│ NAME         │ LANGUAGE │ STATUS │ SHELL │ IOPUB │ STDIN │ CTRL │ HB │ CONNECTION FILE              │
├──────────────┼──────────┼────────┼───────┼───────┼───────┼──────┼────┼──────────────────────────────┤
│ jovial-goat  │ python   │ alive  │ 52311 │ 52312 │ 52313 │ 5231 │ 52 │ ~/.../runt-kernel-jovial-... │
╰──────────────┴──────────┴────────┴───────┴───────┴───────┴──────┴────┴──────────────────────────────╯

runt jupyter start

Start a standalone kernel.

runt jupyter start <NAME>

Arguments

NAME

string

required

Kernel name to launch (e.g., python3, julia, deno).Must be a valid kernelspec installed on the system. List available kernelspecs with jupyter kernelspec list.

Example

$ runt jupyter start python3
Kernel started with ID: jovial-goat
Connection file: ~/.local/share/jupyter/runtime/runt-kernel-jovial-goat.json

The kernel runs in the background and can be used with:

runt jupyter exec — Execute code
External Jupyter clients (connect via the connection file)
runt jupyter sidecar — View outputs

runt jupyter stop

Stop a running kernel.

runt jupyter stop <ID>
runt jupyter stop --all

Arguments

string

Kernel ID to stop (from runt jupyter ps).Required unless --all is used.

Options

all

boolean

Stop all running standalone kernels.

Examples

# Stop specific kernel
$ runt jupyter stop jovial-goat
Kernel with ID jovial-goat stopped

# Stop all kernels
$ runt jupyter stop --all
Stopped jovial-goat
Stopped happy-duck

Stopped 2 kernel(s)

runt jupyter interrupt

Send an interrupt signal to a running kernel (equivalent to Ctrl+C).

runt jupyter interrupt <ID>

Arguments

string

required

Kernel ID to interrupt.

Example

$ runt jupyter interrupt jovial-goat
Interrupt sent to kernel jovial-goat

Use this to stop long-running computations without killing the kernel.

runt jupyter exec

Execute code in a running kernel.

runt jupyter exec <ID> [CODE]

Arguments

string

required

Kernel ID to execute code in.

CODE

string

Code to execute. If omitted, reads from stdin.

Examples

Execute inline code

$ runt jupyter exec jovial-goat "print('Hello, World!')"
Hello, World!

Execute from stdin

$ echo "import numpy as np; print(np.__version__)" | runt jupyter exec jovial-goat
1.26.0

Execute from file

$ runt jupyter exec jovial-goat < script.py

Output Handling

stdout: Printed to terminal
stderr: Printed to terminal (in red if supported)
Return values: Displayed as plain text
Errors: Full traceback shown

Exit Codes

0: Code executed successfully
1: Execution error (exception raised)

runt jupyter clean

Remove stale kernel connection files.

runt jupyter clean [--timeout SECS] [--dry-run]

Options

timeout

number

default:"2"

Timeout in seconds for heartbeat check when determining if a kernel is alive.

dry-run

boolean

Show what would be removed without actually deleting files.

Example

$ runt jupyter clean
Removed: ~/.local/share/jupyter/runtime/kernel-12345.json
Removed: ~/.local/share/jupyter/runtime/runt-kernel-old-kernel.json

Cleaned 2 stale connection files (3 alive, 0 errors)

Dry Run

$ runt jupyter clean --dry-run
Would remove: ~/.local/share/jupyter/runtime/kernel-12345.json
Would remove: ~/.local/share/jupyter/runtime/runt-kernel-old-kernel.json

Dry run complete: 2 stale, 3 alive, 0 errors

runt jupyter sidecar

Launch the sidecar output viewer for a running kernel.

runt jupyter sidecar <CONNECTION_FILE> [--quiet] [--dump FILE]

Arguments

CONNECTION_FILE

string

required

Path to a kernel connection file (e.g., ~/.local/share/jupyter/runtime/kernel-12345.json)

Options

quiet

boolean

Suppress output messages

dump

string

Dump all Jupyter messages to a JSON file for debugging

Example

# Find a running kernel's connection file
$ runt jupyter ps --verbose
╭──────────────┬──────────┬────────┬───────┬───────┬───────┬──────┬────┬──────────────────────────────╮
│ NAME         │ LANGUAGE │ STATUS │ SHELL │ IOPUB │ STDIN │ CTRL │ HB │ CONNECTION FILE              │
├──────────────┼──────────┼────────┼───────┼───────┼───────┼──────┼────┼──────────────────────────────┤
│ jovial-goat  │ python   │ alive  │ 52311 │ 52312 │ 52313 │ 5231 │ 52 │ ~/.../runt-kernel-jovial-... │
╰──────────────┴──────────┴────────┴───────┴───────┴───────┴──────┴────┴──────────────────────────────╯

# Launch sidecar viewer
$ runt jupyter sidecar ~/.local/share/jupyter/runtime/runt-kernel-jovial-goat.json

The sidecar viewer displays kernel outputs (images, HTML, plots) in a native window. Useful for viewing rich outputs from console or script-based kernel interactions.

The sidecar is primarily for debugging. For interactive notebook work, use the nteract Desktop app instead.

Connection Files

Standalone kernels create connection files at:

~/.local/share/jupyter/runtime/runt-kernel-{id}.json

These files contain:

ZeroMQ port numbers (shell, iopub, stdin, control, heartbeat)
IP address and transport protocol
HMAC signature key

External Jupyter clients can connect to kernels using these files.

Advanced: Custom Kernel Commands

For kernels without a kernelspec, use runt console --cmd instead:

runt console --cmd "deno jupyter --kernel --conn {connection_file}"

This launches an interactive console. See Console for details.

Troubleshooting

Kernelspec not found

Error: Kernelspec 'python3' not foundSolution:

List installed kernelspecs: jupyter kernelspec list

Install the missing kernel:

# Python
pip install ipykernel
python -m ipykernel install --user

# Deno
deno jupyter --install

# Julia
# Run in Julia REPL:
using Pkg; Pkg.add("IJulia")

Can't connect to kernel

Error: Connection timeout or “kernel not found”Solution:

Verify kernel is running: runt jupyter ps
Check the kernel ID matches exactly
Look for errors in kernel output (kernels log to terminal by default)

Stale connection files

Symptoms: runt jupyter ps shows dead kernels, or connection files left after crashesSolution:

# Clean up automatically
runt jupyter clean

# Or manually remove
rm ~/.local/share/jupyter/runtime/runt-kernel-*.json

runt console — Interactive REPL (easier than start + exec)
runt notebooks — List daemon-managed kernels
runt shutdown — Shutdown a notebook’s kernel

Commands

​Subcommands

​runt jupyter ps

​Options

​Example Output

​Verbose Output

​runt jupyter start

​Arguments

​Example

​runt jupyter stop

​Arguments

​Options

​Examples

​runt jupyter interrupt

​Arguments

​Example

​runt jupyter exec

​Arguments

​Examples

​Execute inline code

​Execute from stdin

​Execute from file

​Output Handling

​Exit Codes

​runt jupyter clean

​Options

​Example

​Dry Run

​runt jupyter sidecar

​Arguments

​Options

​Example

​Connection Files

​Advanced: Custom Kernel Commands

​Troubleshooting

​Related Commands

Build docs developers (and LLMs) love

Subcommands

runt jupyter ps

Options

Example Output

Verbose Output

runt jupyter start

Arguments

Example

runt jupyter stop

Arguments

Options

Examples

runt jupyter interrupt

Arguments

Example

runt jupyter exec

Arguments

Examples

Execute inline code

Execute from stdin

Execute from file

Output Handling

Exit Codes

runt jupyter clean

Options

Example

Dry Run

runt jupyter sidecar

Arguments

Options

Example

Connection Files

Advanced: Custom Kernel Commands

Troubleshooting

Related Commands