Skip to main content
The Session class is the primary interface for executing code. Each session connects to a notebook room in the daemon.

​
Constructor

Session(notebook_id=None)
​
notebook_id
str
Unique identifier for this session. If not provided, a random UUID is generated. Multiple Session objects with the same notebook_id will share the same kernel.
session = runtimed.Session()
print(session.notebook_id)  # "agent-session-a1b2c3d4-..."

​
Properties

​
notebook_id
str
Unique identifier for this notebook session.
​
is_connected
bool
Whether connected to the daemon.
​
kernel_started
bool
Whether a kernel is running.
​
env_source
str | None
Environment source (e.g., "uv:prewarmed", "conda:pyproject") if kernel is running.

​
Connection Methods

​
connect()

Connect to the daemon. 
session.connect()
This is called automatically by start_kernel() if not already connected. Respects the RUNTIMED_SOCKET_PATH environment variable if set.

​
start_kernel()

Start a kernel for this session. 
session.start_kernel(
    kernel_type="python",
    env_source="auto",
    notebook_path=None
)
​
kernel_type
str
default:"python"
Type of kernel: "python" or "deno".
​
env_source
str
default:"auto"
Environment source. Options:
  • "auto": Auto-detect from inline deps or project files
  • "uv:prewarmed": Use prewarmed UV environment
  • "conda:prewarmed": Use prewarmed Conda environment
  • For Deno kernels, this is ignored
​
notebook_path
str | None
Path to the notebook file on disk. Used for project file detection (pyproject.toml, pixi.toml, environment.yml) when env_source is "auto".
session.start_kernel()  # Uses prewarmed Python environment
If a kernel is already running for this session’s notebook_id, this returns immediately without starting a new one.

​
shutdown_kernel()

Shutdown the kernel. 
session.shutdown_kernel()

​
interrupt()

Interrupt the currently executing cell. 
session.interrupt()

​
Document Operations

​
create_cell()

Create a new cell in the automerge document. 
cell_id = session.create_cell(
    source="",
    cell_type="code",
    index=None
)
​
source
str
default:""
The cell source code.
​
cell_type
str
default:"code"
Cell type: "code", "markdown", or "raw".
​
index
int | None
Position to insert the cell. If not provided, appends at end.
​
return
str
The cell ID (e.g., "cell-a1b2c3d4-...")
cell_id = session.create_cell("print('hello')")
print(cell_id)  # "cell-a1b2c3d4-..."

​
set_source()

Update a cell’s source in the automerge document. 
session.set_source(cell_id, source)
​
cell_id
str
required
The cell ID.
​
source
str
required
The new source code.
session.set_source(cell_id, "print('updated')")

​
get_cell()

Get a cell from the automerge document. 
cell = session.get_cell(cell_id)
​
cell_id
str
required
The cell ID.
​
return
Cell
Cell object with id, cell_type, source, and execution_count properties.
cell = session.get_cell(cell_id)
print(cell.source)           # "print('hello')"
print(cell.execution_count)  # 1 or None
Raises: RuntimedError if cell not found.

​
get_cells()

Get all cells from the automerge document. 
cells = session.get_cells()
​
return
List[Cell]
List of Cell objects.
cells = session.get_cells()
for cell in cells:
    print(f"{cell.id}: {cell.source[:30]}...")

​
delete_cell()

Delete a cell from the automerge document. 
session.delete_cell(cell_id)
​
cell_id
str
required
The cell ID to delete.
session.delete_cell(cell_id)

​
Execution Methods

​
execute_cell()

Execute a cell by ID. 
result = session.execute_cell(
    cell_id,
    timeout_secs=60.0
)
​
cell_id
str
required
The cell ID to execute.
​
timeout_secs
float
Maximum time to wait for execution.
​
return
ExecutionResult
Result with outputs, success status, and execution count.
cell_id = session.create_cell("x = 42")
result = session.execute_cell(cell_id)
print(result.success)         # True
print(result.execution_count) # 1
The daemon reads the cell’s source from the automerge document and executes it. This ensures all clients see the same code being executed.If a kernel isn’t running yet, this will start one automatically.
Raises: RuntimedError if not connected, cell not found, or timeout.

​
run()

Convenience method: create a cell, execute it, and return the result. 
result = session.run(
    code,
    timeout_secs=60.0
)
​
code
str
required
The code to execute.
​
timeout_secs
float
Maximum time to wait for execution.
​
return
ExecutionResult
Result with outputs, success status, and execution count.
result = session.run("print('hello')")
print(result.stdout)  # "hello\n"
print(result.success) # True
This is a shortcut that combines create_cell() and execute_cell(). The cell is written to the automerge document before execution, so other connected clients will see it.

​
queue_cell()

Queue a cell for execution without waiting for the result. 
session.queue_cell(cell_id)
​
cell_id
str
required
The cell ID to execute.
session.queue_cell(cell_id)
# Execution happens in background
# Poll for results later:
cell = session.get_cell(cell_id)
Raises: RuntimedError if not connected or cell not found.

​
Metadata Operations

​
set_metadata()

Set a metadata value in the automerge document. 
session.set_metadata(key, value)
​
key
str
required
The metadata key.
​
value
str
required
The metadata value (typically JSON).
import json
metadata = {"kernelspec": {"name": "python3"}}
session.set_metadata("notebook_metadata", json.dumps(metadata))

​
get_metadata()

Get a metadata value from the automerge document. 
value = session.get_metadata(key)
​
key
str
required
The metadata key.
​
return
str | None
The metadata value or None if not set.
value = session.get_metadata("notebook_metadata")
if value:
    metadata = json.loads(value)

​
Context Manager

Sessions work as context managers for automatic cleanup: 
with runtimed.Session() as session:
    session.start_kernel()
    cell_id = session.create_cell("1 + 1")
    result = session.execute_cell(cell_id)
# Kernel automatically shut down on exit

​
Complete Example

import runtimed

# Create a session with context manager
with runtimed.Session(notebook_id="my-notebook") as session:
    # Start Python kernel
    session.start_kernel()
    print(f"Environment: {session.env_source}")  # "uv:prewarmed"
    
    # Create and execute cells
    cell1 = session.create_cell("x = 42")
    result1 = session.execute_cell(cell1)
    print(f"Success: {result1.success}")  # True
    
    cell2 = session.create_cell("print(x)")
    result2 = session.execute_cell(cell2)
    print(f"Output: {result2.stdout}")  # "42\n"
    
    # List all cells
    cells = session.get_cells()
    print(f"Total cells: {len(cells)}")  # 2
    
    # Update and re-execute
    session.set_source(cell1, "x = 100")
    session.execute_cell(cell1)
    result3 = session.execute_cell(cell2)
    print(f"Updated output: {result3.stdout}")  # "100\n"

​
See Also

AsyncSession

Async version of Session

ExecutionResult

Understanding execution results

Build docs developers (and LLMs) love

Get started for freeTalk to us