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 nteract MCP 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 inside asyncio.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.

Metadata

Release files for runtimed 2.7.7a202609010906

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for runtimed 2.7.7a202609010906
File	Interpreter	ABI	Platform	Reset
runtimed-2.7.7a202609010906-cp39-abi3-win_amd64.whl 4.4 MB Sep 1, 2026 Without provenance	CPython 3.9	abi3	Windows x86-64	Details
runtimed-2.7.7a202609010906-cp39-abi3-manylinux_2_39_x86_64.whl 7.1 MB Sep 1, 2026 Without provenance	CPython 3.9	abi3	Linux glibc 2.39+ x86-64	Details
runtimed-2.7.7a202609010906-cp39-abi3-macosx_11_0_arm64.whl 4.8 MB Sep 1, 2026 Without provenance	CPython 3.9	abi3	macOS 11.0+ ARM64	Details
runtimed-2.7.7a202609010906-cp39-abi3-macosx_10_12_x86_64.whl 4.6 MB Sep 1, 2026 Without provenance	CPython 3.9	abi3	macOS 10.12+ x86-64	Details

Total release size: 21.0 MB

Release files / runtimed-2.7.7a202609010906-cp39-abi3-win_amd64.whl

Download URL	runtimed-2.7.7a202609010906-cp39-abi3-win_amd64.whl
Size	4.4 MB
Tags	CPython 3.9 Windows x86-64 abi3
SHA-256 checksum How to use checksums	`491882f13696d6893137b311847ada556382b30d92087dd2b0908cc62eb90d14`
BLAKE2b-256 checksum How to use checksums	`34d104033881139e475e0d6b1b49533a70740fd00b208abcdeda3e18672ffc41`
Upload date	Sep 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.8 {"installer":{"name":"uv","version":"0.12.8","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.7.7a202609010906-cp39-abi3-manylinux_2_39_x86_64.whl

Download URL	runtimed-2.7.7a202609010906-cp39-abi3-manylinux_2_39_x86_64.whl
Size	7.1 MB
Tags	CPython 3.9 Linux glibc 2.39+ x86-64 abi3
SHA-256 checksum How to use checksums	`2866988c580a0ad3bb54a840c393ed75e005556d758f2871aecbb0c0ba048b30`
BLAKE2b-256 checksum How to use checksums	`0e50814fc3bf071a7a8b33e303618be3de7460db92492e06ebd1cc2ef2ea5ee9`
Upload date	Sep 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.8 {"installer":{"name":"uv","version":"0.12.8","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.7.7a202609010906-cp39-abi3-macosx_11_0_arm64.whl

Download URL	runtimed-2.7.7a202609010906-cp39-abi3-macosx_11_0_arm64.whl
Size	4.8 MB
Tags	CPython 3.9 abi3 macOS 11.0+ ARM64
SHA-256 checksum How to use checksums	`36fbb086bfbd2602994add550a8517b06e5038e58b01023c214d81741329d6aa`
BLAKE2b-256 checksum How to use checksums	`2f5b23191d0b34caa17a92dd25c8543c1b115be8532972d86eb6000c418f3e05`
Upload date	Sep 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.8 {"installer":{"name":"uv","version":"0.12.8","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.7.7a202609010906-cp39-abi3-macosx_10_12_x86_64.whl

Download URL	runtimed-2.7.7a202609010906-cp39-abi3-macosx_10_12_x86_64.whl
Size	4.6 MB
Tags	CPython 3.9 abi3 macOS 10.12+ x86-64
SHA-256 checksum How to use checksums	`3db4f76c36b3ae44d0d7e3f54625b6f1ec85f9b9fcef90897c05ed6218901574`
BLAKE2b-256 checksum How to use checksums	`7fccd2ccf25b2efb253c8a0dab5cc84828d9d301894e550760df8df4465b2b4c`
Upload date	Sep 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.8 {"installer":{"name":"uv","version":"0.12.8","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}`

Security for runtimed 2.7.7a202609010906

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.