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.2
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.2-cp39-abi3-win_arm64.whl | CPython 3.9 | abi3 | Windows ARM64 | Details |
| runtimed-2.8.2-cp39-abi3-win_amd64.whl | CPython 3.9 | abi3 | Windows x86-64 | Details |
| runtimed-2.8.2-cp39-abi3-manylinux_2_39_x86_64.whl | CPython 3.9 | abi3 | Linux glibc 2.39+ x86-64 | Details |
| runtimed-2.8.2-cp39-abi3-manylinux_2_39_aarch64.whl | CPython 3.9 | abi3 | Linux glibc 2.39+ ARM64 | Details |
| runtimed-2.8.2-cp39-abi3-macosx_11_0_arm64.whl | CPython 3.9 | abi3 | macOS 11.0+ ARM64 | Details |
| runtimed-2.8.2-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.2-cp39-abi3-win_arm64.whl
| Download URL | runtimed-2.8.2-cp39-abi3-win_arm64.whl |
|---|---|
| Size | 18.9 MB |
| Tags | CPython 3.9 Windows ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
8a60e2b14b1d6b83dc834295fcff02a6f03f7050a06bc9470c11b204f84795f7
|
|
BLAKE2b-256 checksum How to use checksums |
56e423fe63c775bc4afdd5386df75748b69b7ba91ac33b57846619ef3c5c3235
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.24 {"installer":{"name":"uv","version":"0.12.24","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.2-cp39-abi3-win_amd64.whl
| Download URL | runtimed-2.8.2-cp39-abi3-win_amd64.whl |
|---|---|
| Size | 19.4 MB |
| Tags | CPython 3.9 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
3459a4f07bfc03fbcc2c44945ecde671effc4915e67640393eafc83b6d8d260a
|
|
BLAKE2b-256 checksum How to use checksums |
c786581bb98ebd36af90fa3085fe10f3f46eb5dfecf8014711534643787775ee
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.24 {"installer":{"name":"uv","version":"0.12.24","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.2-cp39-abi3-manylinux_2_39_x86_64.whl
| Download URL | runtimed-2.8.2-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 |
913622ca18a8ea8ac9cb8eea455442e83aaa87025ba023a7ca8850558c8ea2c6
|
|
BLAKE2b-256 checksum How to use checksums |
0ebfe660b7d0737d038132832460ba979d818773f32a9faea6ac1aafc2b3a6f3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.24 {"installer":{"name":"uv","version":"0.12.24","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.2-cp39-abi3-manylinux_2_39_aarch64.whl
| Download URL | runtimed-2.8.2-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 |
de703f212098f1bbdd6f8f035b637c6e77776945169eef55e235bc30d02a1fb5
|
|
BLAKE2b-256 checksum How to use checksums |
0206f53a027e529375815128bc33a3cd7a8b8f50f71fbe063e7e9997d0b9512f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.24 {"installer":{"name":"uv","version":"0.12.24","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.2-cp39-abi3-macosx_11_0_arm64.whl
| Download URL | runtimed-2.8.2-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 |
198ec2b2a3b89dc78b02e19fd6b502c03b792a05158f5b3d7dbd8ace47ceba94
|
|
BLAKE2b-256 checksum How to use checksums |
c56b1547bc4f32c53ec8e377689b313e24a68f0509740789d03100d3c2ceffc9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.24 {"installer":{"name":"uv","version":"0.12.24","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.2-cp39-abi3-macosx_10_12_x86_64.whl
| Download URL | runtimed-2.8.2-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 |
ec2462739da62a4d4edd5f163cb047acd3ac9432e32e876181608f699e0a5be1
|
|
BLAKE2b-256 checksum How to use checksums |
610496fd34b64dc707be49b1b6f97413f44e37263ae1ac5a231c17d9eee5f999
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.24 {"installer":{"name":"uv","version":"0.12.24","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}
|
