Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

3.0 KB
Raw Blame

Host protocol

The public contract for discovering local marimo hosts and working with their notebooks and runtimes.

The base OpenAPI schema contains stable contracts. Experimental features live in experimental/<feature>/, with an additive OpenAPI Overlay, specification, fixtures, and conformance tests.

The composed schema is the source of truth for the Python types in marimo/_core/protocol.py, the typed event adapters in marimo/_core/protocol_events.py, and the TypeScript schemas and types in packages/client/src/protocol.ts. The frontend defines the native marimo extension event itself, with an unknown payload.

The editor consumes host events through the /ws and /sse session routes, which establish the editor session before streaming events. Connection options such as session_id, types, and cursor are top-level URL parameters. The host notebook event endpoint also accepts run_id; session routes reject that filter. Notebook page parameters are forwarded as a URL-encoded query string in the query_params parameter. For example, a notebook's ?types=scatter&tag=a&tag=b becomes query_params=types%3Dscatter%26tag%3Da%26tag%3Db on the connection URL; it does not change the stream's types filter, and repeated values are preserved.

Missing or empty query_params supplies no notebook parameters. Top-level connection parameters are never exposed as notebook parameters.

Generate and check the Python bindings from the repository root:

make host-protocol-codegen
make host-protocol-check
uv run --group test pytest tests/_lint/test_host_protocol_overlays.py

Generate and check the TypeScript bindings:

pnpm --dir packages/client codegen
pnpm --dir packages/client codegen:check
pnpm --dir packages/client test

Other consumers can generate types from the same schema by pinning a marimo commit. Use the examples and conformance tests from that commit too.

Selecting experimental contracts

marimo's checked-in Python and TypeScript bindings include all experimental features. The generation commands above preserve that selection.

To generate stable-only bindings in a separate directory:

# Python types and event adapters
uv run --no-config --locked --script protocols/host/generate.py --output-dir /tmp/host-python

# TypeScript types, validation schemas, and operation definitions
pnpm --dir packages/client codegen:stable --output-dir /tmp/host-typescript

Both generator scripts default to stable-only bindings. Add --include-experimental for all features or --include-experimental=analysis for a specific feature. Add --check to verify existing output without writing files.

Stable-only generation covers the generated bindings; the client package itself currently requires experimental Analysis types.

See experimental features for compatibility rules and instructions for adding features.