Architecture Deep Dive

​

System Overview

​

Core Architecture Principles

​

1. Daemon as Source of Truth

• Clients subscribe to daemon state via IPC
• State changes flow through the daemon, not peer-to-peer
• If the daemon restarts, clients reconnect and resync

​

2. Automerge Document as Canonical Notebook State

• Cell source code lives in the Automerge doc
• To execute a cell: write it to the doc first, then request execution by cell_id
• Multiple clients editing the same notebook see each other’s changes in real-time
• The daemon reads from the doc when executing

​

3. On-Disk Notebook as Checkpoint

• Daemon reads .ipynb on first open, loads into Automerge doc
• Daemon writes .ipynb on explicit save or auto-save intervals
• Unknown metadata keys preserved through round-trips
• Crash recovery: last checkpoint + Automerge doc replay

​

4. Local-First Editing, Synced Execution

Client                              Daemon
  |                                   |
  |-- [sync: update cell source] ---->|
  |<-- [sync: ack] -------------------|
  |                                   |
  |-- ExecuteCell { cell_id } ------->|  // No code parameter
  |<-- CellQueued -------------------|
  |<-- ExecutionStarted --------------|
  |<-- Output ------------------------|
  |<-- ExecutionDone -----------------|

​

5. Binary Separation via Manifests

• Output broadcasts contain blob hashes, not inline data
• Large outputs (images, plots) don’t block document sync
• Clients resolve blobs from the blob store (disk or HTTP)
• Deduplication and lazy loading

​

6. Daemon Manages Runtime Resources

• Clients don’t spawn kernels directly
• Environment selection based on notebook metadata
• Tool availability via rattler bootstrap
• Clients are stateless with respect to runtime resources

​

Environment Management Architecture

​

Two-Stage Detection

​

Project File Discovery

• Checks for pyproject.toml, pixi.toml, environment.yml at each level
• First (closest) match wins
• Same-directory tiebreaker: pyproject.toml > pixi.toml > environment.yml
• Stops at .git boundaries and home directory

​

Environment Source Labels

​

Content-Addressed Caching

• Hash = SHA256(sorted deps + requires_python + env_id), first 16 hex chars
• Location: ~/.cache/runt/envs/{hash}/
• When deps are non-empty, env_id excluded (cross-notebook sharing)
• When deps are empty, env_id included (per-notebook isolation)

• Hash = SHA256(sorted deps + channels + python version + env_id), first 16 hex chars
• Location: ~/.cache/runt/conda-envs/{hash}/

​

Prewarmed Environment Pool

1. Try daemon pool (shared across windows)
2. Try in-process pool (local to this window)
3. Create fresh environment

​

Inline Dependency Environments

~/.cache/runt/inline-envs/
  inline-a1b2c3d4/    # Hash of ["requests"]
  inline-e5f6g7h8/    # Hash of ["pandas", "numpy"]

1. notebook_sync_server.rs detects uv:inline from trusted notebook metadata
2. Calls inline_env::prepare_uv_inline_env(deps) which returns cached env or creates new one
3. Kernel launches with the cached env’s Python

​

Daemon Architecture

​

Singleton Per User

​

IPC Communication

• Environment pool requests (Take, Return, Status)
• Automerge sync messages
• Settings sync
• Ping/health checks

​

State Storage

~/.cache/runt/
├── runtimed.sock           # IPC socket
├── runtimed.log            # Daemon logs
├── daemon.json             # PID, version, endpoint
├── daemon.lock             # Singleton lock
├── envs/                   # Prewarmed environments
│   ├── runtimed-uv-{uuid}/
│   └── runtimed-conda-{uuid}/
├── inline-envs/            # Inline dependency envs
│   └── inline-{hash}/
├── conda-envs/             # Conda environments
│   └── conda-{hash}/
├── blobs/                  # Content-addressed blob store
└── notebook-docs/          # Automerge notebook docs

​

Dev Mode (Per-Worktree Isolation)

• CONDUCTOR_WORKSPACE_PATH is set (Conductor users)
• RUNTIMED_DEV=1 is set (manual opt-in)

• No conflicts when testing across branches
• Code changes take effect immediately on restart
• No interference with system daemon

# Terminal 1: Start dev daemon
cargo xtask dev-daemon

# Terminal 2: Run notebook app
cargo xtask dev

# App connects to worktree daemon, not system daemon

​

Kernel Launching

​

Kernel Startup Sequence

​

Tool Bootstrapping

use kernel_launch::tools;

let deno = tools::get_deno_path().await?;  // PATH first, then ~/.cache/runt/tools/
let uv = tools::get_uv_path().await?;
let ruff = tools::get_ruff_path().await?;

​

Trust System

• Trusted
• Untrusted
• SignatureInvalid
• NoDependencies

​

Crate Architecture

​

Workspace Structure

crates/
├── notebook/          # Tauri app (main binary)
├── runtimed/          # Background daemon
├── runt/              # CLI binary
├── sidecar/           # Output viewer
├── kernel-launch/     # Shared kernel launching
├── kernel-env/        # Environment management
├── tauri-jupyter/     # Shared Jupyter types
├── runt-trust/        # Trust verification
├── runt-workspace/    # Workspace detection
├── runtimed-py/       # Python bindings
└── xtask/             # Build orchestration

​

Dependency Graph

​

Key Files

​

Daemon (Kernel Management)

​

Notebook Crate (Tauri Commands)

​

Shared Kernel Launch Crate

​

Frontend

​

Frontend Architecture

​

Component Structure

src/
├── components/
│   ├── ui/                    # shadcn primitives
│   ├── cell/                  # Notebook cells
│   ├── outputs/               # Output renderers
│   ├── editor/                # CodeMirror editor
│   └── widgets/               # ipywidgets controls
└── lib/
    └── utils.ts               # cn() and utilities

​

Key Hooks

​

Dependency Management UI

​

Build System

​

Build Order

• sidecar crate embeds apps/sidecar/dist/ via rust-embed
• notebook crate embeds apps/notebook/dist/ via Tauri
• Tauri bundles runtimed and runt binaries as sidecar processes

​

xtask Orchestration

// Simplified xtask logic
fn build() {
    run("pnpm", &["build"])?;              // Build frontends
    run("cargo", &["build", "--release"])?; // Build Rust
    copy_binaries()?;                       // Copy to Tauri bundle dir
}

• cargo xtask build — Full debug build
• cargo xtask build --rust-only — Skip frontend rebuild
• cargo xtask build-app — Release .app/.AppImage/.exe
• cargo xtask build-dmg — Release DMG (macOS)

​

Performance Considerations

​

Instant Notebook Startup

• Pool maintains 3 ready UV envs + 3 ready Conda envs
• Warming loops run every 30s
• Environments include ipykernel, ipywidgets, and common deps
• Python bytecode precompiled (.pyc warmup)

​

Content-Addressed Caching

• Notebook A with ["pandas", "numpy"]
• Notebook B with ["numpy", "pandas"]
• Both use the same cached environment (sorted before hashing)

​

Blob Store for Outputs

• Outputs stored as content-addressed blobs
• Sync protocol sends blob hashes only
• Clients fetch blobs lazily on demand
• Deduplication across notebooks

​

Security

​

Iframe Isolation

• sandbox="allow-scripts allow-same-origin"
• Tauri API not exposed to iframe
• postMessage eval channel for controlled communication

​

Trust System

• Trust dialog shown on first open
• HMAC signature verification
• Per-machine trust keys
• Prevents automatic code execution

​

Next Steps

• Building from Source - Set up your environment
• Testing - Run and write tests
• Contributing Guidelines - Contribution workflow
• Release Process - How releases work