runtimed 2.0.3a202603231736

Python toolkit for Jupyter runtimes, powered by runtimed Rust binaries

runtimed

Python toolkit for Jupyter runtimes, powered by runtimed Rust binaries. Execute code, manage kernels, and interact with notebooks programmatically.

Installation

pip install runtimed

Note: The 2.0 release is currently in pre-release. Use pip install --pre runtimed (or uv pip install --prerelease allow runtimed) to get the latest 2.x build matching the nteract desktop nightly.

Quick Start

All examples use await — run them inside asyncio.run(main()), a Jupyter notebook, or a Python REPL with top-level await (e.g. python -m asyncio).

import asyncio
import runtimed

async def main():
    client = runtimed.Client()
    notebook = await client.create_notebook()

    # Create and execute cells
    cell = await notebook.cells.create("print('hello')")
    result = await cell.run()
    print(result.stdout)  # "hello\n"

    # Read cell properties (sync — local CRDT replica)
    print(cell.source)      # "print('hello')"
    print(cell.cell_type)   # "code"

    # Edit cells
    await cell.set_source("x = 42")
    await cell.run()

    # Save the notebook
    path = await notebook.save_as("/tmp/my-notebook.ipynb")

asyncio.run(main())

Features

• Document-first model with Automerge CRDT sync
• Sync reads, async writes — reads from local replica, writes sync to peers
• Multi-client support for shared notebooks
• Rich output capture (stdout, stderr, display_data, errors)

API Overview

Client

client = runtimed.Client()

# Discover active notebooks
notebooks = await client.list_active_notebooks()
for info in notebooks:
    print(f"{info.name} [{info.status}] ({info.active_peers} peers)")

# Open, create, or join notebooks
notebook = await client.open_notebook("/path/to/notebook.ipynb")
notebook = await client.create_notebook(runtime="python")
notebook = await client.join_notebook(notebook_id)

Notebook

async with await client.create_notebook() as notebook:
    # Cells collection (sync reads, async writes)
    print(len(notebook.cells))
    for cell in notebook.cells:
        print(f"{cell.id[:8]}: {cell.source[:40]}")

    # Runtime state (sync read from local doc)
    print(notebook.runtime.kernel.status)

    # Runtime lifecycle
    await notebook.start(runtime="python")
    await notebook.restart()
    await notebook.interrupt()
    await notebook.save()
# Session closed automatically on exit

Cells

# Create cells
cell = await notebook.cells.create("import math")
cell = await notebook.cells.insert_at(0, "# Title", cell_type="markdown")

# Access cells
cell = notebook.cells.get_by_index(0)    # by position
cell = notebook.cells.get_by_id(cell_id) # by ID
matches = notebook.cells.find("import")  # search source

# Read properties (sync)
print(cell.source, cell.cell_type, cell.outputs)

# Mutate (async)
await cell.set_source("x = 2")
await cell.append("\ny = 3")
result = await cell.run()
await cell.delete()

Requirements

• runtimed daemon running (see CLAUDE.md — use cargo xtask dev-daemon for development or cargo xtask install-daemon for the system service)
• Python 3.10+

Documentation

See docs/python-bindings.md for full documentation.