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.6
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.6-cp39-abi3-win_arm64.whl | CPython 3.9 | abi3 | Windows ARM64 | Details |
| runtimed-2.8.6-cp39-abi3-win_amd64.whl | CPython 3.9 | abi3 | Windows x86-64 | Details |
| runtimed-2.8.6-cp39-abi3-manylinux_2_39_x86_64.whl | CPython 3.9 | abi3 | Linux glibc 2.39+ x86-64 | Details |
| runtimed-2.8.6-cp39-abi3-manylinux_2_39_aarch64.whl | CPython 3.9 | abi3 | Linux glibc 2.39+ ARM64 | Details |
| runtimed-2.8.6-cp39-abi3-macosx_11_0_arm64.whl | CPython 3.9 | abi3 | macOS 11.0+ ARM64 | Details |
| runtimed-2.8.6-cp39-abi3-macosx_10_12_x86_64.whl | CPython 3.9 | abi3 | macOS 10.12+ x86-64 | Details |
Total release size: 126.7 MB
Release files / runtimed-2.8.6-cp39-abi3-win_arm64.whl
| Download URL | runtimed-2.8.6-cp39-abi3-win_arm64.whl |
|---|---|
| Size | 19.0 MB |
| Tags | CPython 3.9 Windows ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
5f8411f70c76a67e369bdebac93498c057f3a136487444758cbd99ec1810feda
|
|
BLAKE2b-256 checksum How to use checksums |
4f1e1a5b27b59961ebbeea24a27fc9b29a2af0822d3801ba0636e2ddf5b0f1fb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","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.6-cp39-abi3-win_amd64.whl
| Download URL | runtimed-2.8.6-cp39-abi3-win_amd64.whl |
|---|---|
| Size | 19.6 MB |
| Tags | CPython 3.9 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
592583b303dd78760caef441b472a4f2d839fa3fbc62438d12d746a1ad9dfa0d
|
|
BLAKE2b-256 checksum How to use checksums |
94fd335591a1d3ba8d2858c42d4703c7b182a3c8a9669f3140eb3a1532351105
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","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.6-cp39-abi3-manylinux_2_39_x86_64.whl
| Download URL | runtimed-2.8.6-cp39-abi3-manylinux_2_39_x86_64.whl |
|---|---|
| Size | 23.2 MB |
| Tags | CPython 3.9 Linux glibc 2.39+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
453e6bd59062ab1599b36cd8afa91bc31cf101c416efe6c295312ee1275e6e53
|
|
BLAKE2b-256 checksum How to use checksums |
61c422d64418289c43a331cb58d2ccc09a46cf00387ad1cccc1ebaf0f7ae4758
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","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.6-cp39-abi3-manylinux_2_39_aarch64.whl
| Download URL | runtimed-2.8.6-cp39-abi3-manylinux_2_39_aarch64.whl |
|---|---|
| Size | 24.6 MB |
| Tags | CPython 3.9 Linux glibc 2.39+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
53cf10b44b14383077f292ce287aea17b715d6f5129fc5018a91d9983fe828f5
|
|
BLAKE2b-256 checksum How to use checksums |
4959d6697338debe5bdaa9991864154cc2ae7ffb6a7a99eed1f0da6c092a232f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","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.6-cp39-abi3-macosx_11_0_arm64.whl
| Download URL | runtimed-2.8.6-cp39-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 20.2 MB |
| Tags | CPython 3.9 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
dc4de9d027624d2dd41b77e869232d16cc8d6384c7299df7e75c5eef031e4b59
|
|
BLAKE2b-256 checksum How to use checksums |
c9dd14cfba7978f3a593cbe18827bdc58bfd7774bd26ad8c397fcee8a40c19d8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","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.6-cp39-abi3-macosx_10_12_x86_64.whl
| Download URL | runtimed-2.8.6-cp39-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 20.0 MB |
| Tags | CPython 3.9 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
13ba187b24d63bbbe8d5fe54002f4c597781cc040a45830ee61fbe70694aac78
|
|
BLAKE2b-256 checksum How to use checksums |
22e04e56da6f7109b1fa105b248eb58b8b914dc5d29b5f4cbdeaa359937e4b65
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","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}
|
