runtimed
Python bindings for the nteract runtime daemon. Execute code, manage kernels, and interact with notebooks programmatically.
Download the nteract desktop app — it ships the runtimed daemon and gives you a visual interface for your notebooks.
Using runtimed with agents? The
nteractMCP server is built on runtimed and provides a ready-made agentic interface for AI assistants. It's also a great example of how to use runtimed in practice.
Installation
pip install --pre runtimed
# or: uv pip install --prerelease allow runtimed
Only pre-release wheels are being published while the library surface settles. The stable channel is frozen at the last-shipped release; the --pre channel tracks the nightly desktop app and discovers the nightly daemon socket automatically. See #2217 for context.
Client() and the high-level Python API use default_socket_path() by default. That helper respects RUNTIMED_SOCKET_PATH, so exported test or MCP sockets take precedence over the package's default channel.
Quick Start
All examples use
await— run them insideasyncio.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')")
execution = await cell.execute()
result = await execution.result()
print(execution.execution_id) # durable execution UUID
print(result.stdout) # "hello\n"
recovered = await client.get_execution_result(execution.execution_id)
print(recovered.stdout)
# 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")
execution = await cell.execute()
await execution.result()
# 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)
If you need to target a specific release channel instead of the current process default:
import os
import runtimed
os.environ["RUNTIMED_SOCKET_PATH"] = runtimed.socket_path_for_channel("nightly")
client = runtimed.Client()
Use default_socket_path() for normal current-process behavior. Use socket_path_for_channel("stable"|"nightly") only for explicit channel targeting or cross-channel discovery because it intentionally ignores RUNTIMED_SOCKET_PATH.
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)
if notebook.runtime.kernel.status == runtimed.KERNEL_STATUS.IDLE:
print("kernel is idle")
# 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
- The runtimed daemon, which ships with the nteract desktop app. For development, see the nteract/nteract repo.
- Python 3.10+
Documentation
See crates/runtimed/AGENTS.md for architecture and Python binding usage.
1 maintainer
Metadata
1 maintainer
Release files for runtimed 2.8.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| runtimed-2.8.0-cp39-abi3-win_arm64.whl | CPython 3.9 | abi3 | Windows ARM64 | Details |
| runtimed-2.8.0-cp39-abi3-win_amd64.whl | CPython 3.9 | abi3 | Windows x86-64 | Details |
| runtimed-2.8.0-cp39-abi3-manylinux_2_39_x86_64.whl | CPython 3.9 | abi3 | Linux glibc 2.39+ x86-64 | Details |
| runtimed-2.8.0-cp39-abi3-manylinux_2_39_aarch64.whl | CPython 3.9 | abi3 | Linux glibc 2.39+ ARM64 | Details |
| runtimed-2.8.0-cp39-abi3-macosx_11_0_arm64.whl | CPython 3.9 | abi3 | macOS 11.0+ ARM64 | Details |
| runtimed-2.8.0-cp39-abi3-macosx_10_12_x86_64.whl | CPython 3.9 | abi3 | macOS 10.12+ x86-64 | Details |
Total release size: 125.8 MB
Release files / runtimed-2.8.0-cp39-abi3-win_arm64.whl
| Download URL | runtimed-2.8.0-cp39-abi3-win_arm64.whl |
|---|---|
| Size | 18.9 MB |
| Tags | CPython 3.9 Windows ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
c2b802628c153ba45df32d3db2910636ca422e027f01814727b5bbc10a1a5ae7
|
|
BLAKE2b-256 checksum How to use checksums |
5af776cc948734461fd32dab5bba58c1b6b295fdeb6f566397bc745522a39051
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / runtimed-2.8.0-cp39-abi3-win_amd64.whl
| Download URL | runtimed-2.8.0-cp39-abi3-win_amd64.whl |
|---|---|
| Size | 19.4 MB |
| Tags | CPython 3.9 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
b7892c8eea859ec97f5a44a75c456cc1328c0064d8bd727417b62e7113cc07e2
|
|
BLAKE2b-256 checksum How to use checksums |
018b74ec6c3f5d150f4d1cd58273b415b15491226ff79caed4bbdd0930b5cbaa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / runtimed-2.8.0-cp39-abi3-manylinux_2_39_x86_64.whl
| Download URL | runtimed-2.8.0-cp39-abi3-manylinux_2_39_x86_64.whl |
|---|---|
| Size | 23.1 MB |
| Tags | CPython 3.9 Linux glibc 2.39+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
81635d59da8d2b7e0858efb0ac3b8a25d0eafd83644fd152b4bf4439de93e22d
|
|
BLAKE2b-256 checksum How to use checksums |
b2a2cf670299a45ab2aa0429565de42e6be8138f40a4a82459da18b47e90c6de
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / runtimed-2.8.0-cp39-abi3-manylinux_2_39_aarch64.whl
| Download URL | runtimed-2.8.0-cp39-abi3-manylinux_2_39_aarch64.whl |
|---|---|
| Size | 24.4 MB |
| Tags | CPython 3.9 Linux glibc 2.39+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
ce292f209e51cd65e37c024bbf6ac825faf6dd5e26ec889b2a2deaaced3c026c
|
|
BLAKE2b-256 checksum How to use checksums |
f911ce6a96b400e239229a0388c580f18681e1e873a76fc66acb7be7c81b0e96
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / runtimed-2.8.0-cp39-abi3-macosx_11_0_arm64.whl
| Download URL | runtimed-2.8.0-cp39-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 20.1 MB |
| Tags | CPython 3.9 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
585b4bddbd8d7b38e0981b902be748b437890c5f6e3dc444a2bde8023ff5ede2
|
|
BLAKE2b-256 checksum How to use checksums |
737f6fa282896e5d81897841f0dad50c6ca33ce57cb6c268f6278c93f6075ee6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / runtimed-2.8.0-cp39-abi3-macosx_10_12_x86_64.whl
| Download URL | runtimed-2.8.0-cp39-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 19.9 MB |
| Tags | CPython 3.9 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
377ac3cd8cf5df74d72dc2eaee96a1e239a53e67e01cbdd266ce3fc793fce5e4
|
|
BLAKE2b-256 checksum How to use checksums |
8e9b75a0fb931a573ecba059a08dde417e3cf441a1b437ebceb291d8e71b199f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
