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.1
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.1-cp39-abi3-win_arm64.whl | CPython 3.9 | abi3 | Windows ARM64 | Details |
| runtimed-2.8.1-cp39-abi3-win_amd64.whl | CPython 3.9 | abi3 | Windows x86-64 | Details |
| runtimed-2.8.1-cp39-abi3-manylinux_2_39_x86_64.whl | CPython 3.9 | abi3 | Linux glibc 2.39+ x86-64 | Details |
| runtimed-2.8.1-cp39-abi3-manylinux_2_39_aarch64.whl | CPython 3.9 | abi3 | Linux glibc 2.39+ ARM64 | Details |
| runtimed-2.8.1-cp39-abi3-macosx_11_0_arm64.whl | CPython 3.9 | abi3 | macOS 11.0+ ARM64 | Details |
| runtimed-2.8.1-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.1-cp39-abi3-win_arm64.whl
| Download URL | runtimed-2.8.1-cp39-abi3-win_arm64.whl |
|---|---|
| Size | 18.9 MB |
| Tags | CPython 3.9 Windows ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
072dde7d827a93ae1ce22ad0f5c5ce6a29b456b4ca654748e74e7f478f20bb83
|
|
BLAKE2b-256 checksum How to use checksums |
04c7801478a347301da464523c14cd0dfca09d06751fbb646b461438f5be191e
|
| 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.1-cp39-abi3-win_amd64.whl
| Download URL | runtimed-2.8.1-cp39-abi3-win_amd64.whl |
|---|---|
| Size | 19.4 MB |
| Tags | CPython 3.9 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
0c9691837d15fb63b4aea036d23bf6f73a4fa0454d3c68c63efdab6fc24303a3
|
|
BLAKE2b-256 checksum How to use checksums |
eb0be3ec04124cb51d6616095ebc9e374870b4e10875765deb088de356dd12b7
|
| 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.1-cp39-abi3-manylinux_2_39_x86_64.whl
| Download URL | runtimed-2.8.1-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 |
7b42a30f6ce51d42fb046a5dd385289f9c5761e27de156b50280ba51da8d24cb
|
|
BLAKE2b-256 checksum How to use checksums |
62324fcce95974452007f5173824c7de261fe15dfc19b8f2cf0c8631c878a6b6
|
| 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.1-cp39-abi3-manylinux_2_39_aarch64.whl
| Download URL | runtimed-2.8.1-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 |
0131164ab2eb747471f6049a53288655e68b547bcaabf95014181ef387b4ed6d
|
|
BLAKE2b-256 checksum How to use checksums |
f27677170debfce2d9a58f0ac78412d21c0b5850f70b9c0dfb6f2da237d093c1
|
| 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.1-cp39-abi3-macosx_11_0_arm64.whl
| Download URL | runtimed-2.8.1-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 |
454c50e263426547176fcd245aa40805e73e8fae425742dc827796686f61078c
|
|
BLAKE2b-256 checksum How to use checksums |
3c4274d6a45d59c1f7947c8a0d1d9514b5c08bb641743b5ed79a3750894e342f
|
| 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.1-cp39-abi3-macosx_10_12_x86_64.whl
| Download URL | runtimed-2.8.1-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 |
c38e072f14df86100374561b2c974cde3cbcd45633b466c720278b6c333d2ff0
|
|
BLAKE2b-256 checksum How to use checksums |
97d5eb65e2d1ec97ebc9a7e478e36af1b5501e8aa8a913fae51dbf4bb66def49
|
| 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}
|
