Skip to main content

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

Documentation

See crates/runtimed/AGENTS.md for architecture and Python binding usage.

Metadata

Release files for runtimed 2.10.1

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.10.1
File Actions
runtimed-2.10.1-cp39-abi3-win_arm64.whl CPython 3.9 abi3 Windows ARM64 Details for runtimed-2.10.1-cp39-abi3-win_arm64.whl
runtimed-2.10.1-cp39-abi3-win_amd64.whl CPython 3.9 abi3 Windows x86-64 Details for runtimed-2.10.1-cp39-abi3-win_amd64.whl
runtimed-2.10.1-cp39-abi3-manylinux_2_39_x86_64.whl CPython 3.9 abi3 Linux glibc 2.39+ x86-64 Details for runtimed-2.10.1-cp39-abi3-manylinux_2_39_x86_64.whl
runtimed-2.10.1-cp39-abi3-manylinux_2_39_aarch64.whl CPython 3.9 abi3 Linux glibc 2.39+ ARM64 Details for runtimed-2.10.1-cp39-abi3-manylinux_2_39_aarch64.whl
runtimed-2.10.1-cp39-abi3-macosx_11_0_arm64.whl CPython 3.9 abi3 macOS 11.0+ ARM64 Details for runtimed-2.10.1-cp39-abi3-macosx_11_0_arm64.whl
runtimed-2.10.1-cp39-abi3-macosx_10_12_x86_64.whl CPython 3.9 abi3 macOS 10.12+ x86-64 Details for runtimed-2.10.1-cp39-abi3-macosx_10_12_x86_64.whl

Total release size: 135.5 MB

Release files / runtimed-2.10.1-cp39-abi3-win_arm64.whl

Download URL runtimed-2.10.1-cp39-abi3-win_arm64.whl
Size 20.7 MB
Tags CPython 3.9 Windows ARM64 abi3
SHA-256 checksum
How to use checksums
a9e8f690d2dfba056aa839182e21ab26184f9ee4f676336dbf86dd30417a7388
BLAKE2b-256 checksum
How to use checksums
9fc42a16110fea074baaba8f32fca1fb2dfac01bfabda1eeea10633b83377a91
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.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.10.1-cp39-abi3-win_amd64.whl

Download URL runtimed-2.10.1-cp39-abi3-win_amd64.whl
Size 21.3 MB
Tags CPython 3.9 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
e9bb0743ef9cc6294f58044594ccc8d407cd4ef50b7afab772f636a77b09584a
BLAKE2b-256 checksum
How to use checksums
61450ebd32bdab45ea8ab5bba5cc0ecc0349db7921957f4d04e1e9b4f8d7a8c6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.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.10.1-cp39-abi3-manylinux_2_39_x86_64.whl

Download URL runtimed-2.10.1-cp39-abi3-manylinux_2_39_x86_64.whl
Size 24.6 MB
Tags CPython 3.9 Linux glibc 2.39+ x86-64 abi3
SHA-256 checksum
How to use checksums
fb5a1faabe4d4205adeef81d8e81eeb7ae2b9c82bd16f0cd6d5473979ac9fb8b
BLAKE2b-256 checksum
How to use checksums
1926185a45f620ae02b29e5cf6792ff0d8fab0fa9ac634e72f99b57148c58c8e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.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.10.1-cp39-abi3-manylinux_2_39_aarch64.whl

Download URL runtimed-2.10.1-cp39-abi3-manylinux_2_39_aarch64.whl
Size 26.0 MB
Tags CPython 3.9 Linux glibc 2.39+ ARM64 abi3
SHA-256 checksum
How to use checksums
6f9425c252327d40733bf65cb7c1b0b537f314b66ea44cf4b9fc9d74b15131fa
BLAKE2b-256 checksum
How to use checksums
3893a936477ef8dbf36a2fb8a39457769d44094aaa1f695d34ac8e12b8c01573
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.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.10.1-cp39-abi3-macosx_11_0_arm64.whl

Download URL runtimed-2.10.1-cp39-abi3-macosx_11_0_arm64.whl
Size 21.7 MB
Tags CPython 3.9 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
9d54c1a964b0f0d6f25a2df28095cfcaa2d89365cee965e42fccf3343b69b612
BLAKE2b-256 checksum
How to use checksums
7d73b16f6ceeaa4ea5d4daebedd890b0d0b27141a1cf16b7780fdc8919cd7aa4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.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.10.1-cp39-abi3-macosx_10_12_x86_64.whl

Download URL runtimed-2.10.1-cp39-abi3-macosx_10_12_x86_64.whl
Size 21.3 MB
Tags CPython 3.9 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
f86046b242d643f2a5dc93bec416d0283deffeb7f880e2b11337c2022a962754
BLAKE2b-256 checksum
How to use checksums
07767e76ba8aacaad38ac095fec1de9bf36c9b2eb42c1ebc4903cd6fd62fb0ea
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.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.10.1

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.

Release history Release notifications | RSS feed

This release

2.10.1 This release

6 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page