One Python kernel per file,and it outlives your IDE.
DarkPyonix binds a Python kernel to a notebook file. Close the editor, lose the network or kill the manager: the run keeps going, and the next tool that opens the file finds the same kernel.
Notebooks are plain .py files. Every run is recorded beside the file in
__runs__/ as an nbformat 4 notebook.
- One kernel per file
- Kernels outlive managers
- Stop means interrupt
- Standard library only, Python 3.8+
darkpyonix run train.py # run the whole file, follow the output
darkpyonix run train.py --detach # start it and return the run id
darkpyonix logs train.py --follow # follow the latest run
darkpyonix stop train.py # interrupt the running cell; the kernel stays
darkpyonix vars train.py # what the kernel holds nowBuilt for runs that take hours
The kernel id comes from the file's path. Every IDE, agent and shared viewer that opens
train.py reaches the same kernel. Running the same file twice is refused with
the current run's details, so an agent cannot start a duplicate by mistake.
Stopping raises KeyboardInterrupt in the running cell. The variables stay,
so the next run continues from them.
What it is
DarkPyonix has three parts in this repository. The kernel is a Python process
bound to one file. It uses only the standard library and starts from any Python 3.8 or newer
interpreter without being installed there. The manager is an HTTP front that
finds running kernels, starts new ones and serves editors, agents and the shared notebook. It
is the same Rust binary as the darkpyonix CLI. The runtime API
is what a notebook imports as darkpyonix.
The manager is disposable. A kernel never depends on one being alive, so several managers can attach to the same kernel and any of them can go away.
Where it stands today
A redesign is under way. Items marked changing work today but are being replaced; the linked issue says what replaces them.
| Part | Status | Reference |
|---|---|---|
| Kernel: one per file, outlives managers, interrupt, run logs | implemented | SPEC FR-K, FR-X, FR-R |
| Runtime API and notebook parser | implemented | SPEC FR-F |
Rust manager and darkpyonix CLI | implemented | SPEC FR-M, FR-C |
| Discovery without registry files | changing #50 | INTENT D4 |
| Event streams handed from the manager to the kernel | changing #47 | INTENT D6 |
| Password login and share-token lifetime | changing #48 | SPEC FR-A |
| 2025 permission model and WebSocket sync | changing #49 | SPEC FR-S |
| PyPI release 0.2.0 | planned #46 | #45 |
| Prebuilt CLI binary (wheel with the binary) | planned | INTENT D10 |
| VS Code and IntelliJ notebook renderers | planned #22 | |
| ash opening a shared kernel | planned #20 | |
| darkpyonix.dev hub | planned #21 | #41 |
Start here
Install and first run
Get the CLI, pick an interpreter, run a file.
Notebook files
Cells, metadata, parameters and markdown in a file that stays valid Python.
The darkpyonix CLI
run, stop, logs, vars and the rest, with exit codes.
Run logs
The __runs__/ folder and the __runs__ variable inside the kernel.
Manager HTTP API
The endpoints every client uses, under /api/.
Editors, ash and agents
Who connects to a kernel, and how.