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
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distributions
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file runtimed-2.7.4-cp39-abi3-win_amd64.whl.
File metadata
- Download URL: runtimed-2.7.4-cp39-abi3-win_amd64.whl
- Upload date:
- Size: 4.4 MB
- Tags: CPython 3.9+, Windows x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
uv/0.12.6 {"installer":{"name":"uv","version":"0.12.6","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}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
82c07aa1d1ca6b61d9b22f8ec14139250b156398a8c2b51c1cfb45d4b1f05fcb
|
|
| MD5 |
0164f82f324f81c5c281d900ccba0925
|
|
| BLAKE2b-256 |
9e89a5f428f9fa8c436add79c6f022c215112be693b8fc0a009ddb3608bc6adb
|
File details
Details for the file runtimed-2.7.4-cp39-abi3-manylinux_2_39_x86_64.whl.
File metadata
- Download URL: runtimed-2.7.4-cp39-abi3-manylinux_2_39_x86_64.whl
- Upload date:
- Size: 7.1 MB
- Tags: CPython 3.9+, manylinux: glibc 2.39+ x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
uv/0.12.6 {"installer":{"name":"uv","version":"0.12.6","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}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
d023e332b6bf08e22b8df256582f9623a0dbc265cc0b0ed8ebf3f5d4d9e413a1
|
|
| MD5 |
90c679de44b44f78e8c01c64cfda5ef2
|
|
| BLAKE2b-256 |
0db7245c2d6a7f4f3973dc3837eb036b24c4a0f985b7046b2752d22b29e4c216
|
File details
Details for the file runtimed-2.7.4-cp39-abi3-macosx_11_0_arm64.whl.
File metadata
- Download URL: runtimed-2.7.4-cp39-abi3-macosx_11_0_arm64.whl
- Upload date:
- Size: 4.8 MB
- Tags: CPython 3.9+, macOS 11.0+ ARM64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
uv/0.12.6 {"installer":{"name":"uv","version":"0.12.6","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}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
cdfab7babc540ebee79b247ef190e71a7a852c6008d2116de11483ada6faa053
|
|
| MD5 |
90c188357e0e8d4b2b56cd975e18d8fd
|
|
| BLAKE2b-256 |
9b1638c36b55c3da34a6c0c81345b60b43e118745a6e1cbd09ab55d120992e79
|
File details
Details for the file runtimed-2.7.4-cp39-abi3-macosx_10_12_x86_64.whl.
File metadata
- Download URL: runtimed-2.7.4-cp39-abi3-macosx_10_12_x86_64.whl
- Upload date:
- Size: 4.6 MB
- Tags: CPython 3.9+, macOS 10.12+ x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
uv/0.12.6 {"installer":{"name":"uv","version":"0.12.6","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}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
54ed9182e844100e890bf723302c33089cd8a336b5b39332c0cb4a7607da56e8
|
|
| MD5 |
2bc7f53408f7b4df066a83db9dc4e2d4
|
|
| BLAKE2b-256 |
e3ee3be5b504a48ebf9c48985920d7f43c5dde2d0176459d396ec5c32b1ff863
|
