Tithon keeps Jupyter kernels and live output alive on the host, not the client

A project called Tithon, which surfaced on the Hacker News front page via its GitHub repository, takes aim at a familiar annoyance in data work: the Jupyter kernel that dies the moment its client does. The project pairs a long-lived daemon with a VSCode extension so that a kernel and everything it has printed keep running on the host, whether the editor is open, the network is up, or neither.

According to the project's README, the setup has two parts. A Python daemon owns the kernel and serves clients, while the VSCode extension opens a percent-format Python file as a notebook. Close the window, lose your SSH connection, or come back hours later, and the same session is still there and still streaming.

The problem it targets

The README walks through three common failure modes when running long jobs on a remote GPU machine. JupyterLab will reconnect after you return, but anything printed while you were away is gone, because iopub output is streamed over the WebSocket and never persisted server-side, leaving nothing to replay. VSCode's built-in Jupyter support ties the kernel's lifetime to the extension-host process, so closing the window or dropping the network kills the kernel along with the session. And tmux plus jupyter console survives a disconnect, but at the cost of rich output such as plots, HTML and widgets, and it cannot be opened from a second client.

The project identifies a shared root cause: the session's source of truth lives on the client, or in a channel that does not outlive a disconnect. Tithon moves that source of truth onto the host.

How it works

The kernel runs detached from the daemon using setsid, so it is not a child process. The daemon can crash, restart, or be upgraded while the kernel keeps running, re-attaching through a persisted connection file. Every iopub and shell message is journaled verbatim into an append-only SQLite database in WAL mode, alongside a folded per-execution snapshot of the current display state, which keeps reconnects fast. Clients attach with the last sequence number they saw and receive a snapshot followed by an ordered, gapless delta stream, so reconnecting is just resuming the stream.

Rich outputs such as images are stored as real files referenced by hash rather than embedded as base64, and ipywidgets traffic is folded into a widget-state snapshot, so a tqdm progress bar or a slider returns at its real value. Backpressure is bounded: per-subscriber queues are capped, and a client that falls too far behind is dropped and resynced on reconnect, so one slow consumer cannot balloon daemon memory or block the others. The daemon binds a 0600 Unix domain socket and exposes no TCP port. The kernel itself is plain ipykernel, meaning Tithon replaces the session-management layer around the execution engine, not the engine.

The VSCode experience

The extension opens a plain .py file with # %% cell markers as a notebook, with the usual cells, run buttons and rich output. Selecting the Tithon kernel attaches the session automatically, and output is journaled on the host, so reopening the notebook later restores and resumes streaming without any command. Over a VSCode Tunnel or Remote-SSH the behaviour is identical, because the extension host runs on the remote machine and talks to the daemon's host-local socket directly, with no port forwarding needed.

Outputs are matched to cells by content hash, so they survive edits and reopens; output from a cell that was edited after it ran is flagged as stale. The .py file itself stays pure source, keeping diffs clean. For sharing, the daemon also writes the folded output state as text under a .tithon directory in the project, with per-cell JSON and sha256-deduplicated images, which can be committed so that anyone cloning the repository gets the results, or gitignored entirely.

The README adds an AI-agent angle: the same notebook that costs roughly 250 lines of JSON scaffolding becomes about 50 lines of clean Python, and images stored as real files can be handed to a model as actual images rather than base64 it cannot read.

Requirements and status

Tithon needs Python 3.11+ for the daemon and CLI and a Unix-like host, developed and tested on Linux; Windows users are directed to WSL with the WSL extension. The CLI ships on PyPI and the extension is on the VSCode Marketplace, with commands for running code, streaming events and checking status; attach --since is the reconnection knob. The project is explicit that it is alpha software: it works and is in daily use, but users should expect rough edges, and bug reports are welcomed.

Why it matters

The coupling between kernels and clients is a longstanding pain point for anyone running long computations on remote machines, and the standard workarounds each give something up, whether history, rich output, or multi-client access. By journalling messages server-side and detaching the kernel from both the daemon's and the editor's lifecycles, Tithon treats a notebook session as a durable service rather than an ephemeral attachment to a window. The alpha status and Linux-focused daemon are real caveats, but the design, with resumable streams, folded snapshots and file-referenced outputs, is a credible answer to a problem most notebook users have hit at least once.