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.
@marimo-team/client
Connect to a marimo host to find notebooks, read their state, and request
edits or execution. A host serves notebooks through the
host protocol. Client works with the host's
catalog. NotebookClient works with one notebook.
Connect to a host
Give Client the host's API base URL and token. These can come from your
application's configuration or the host's
local discovery record.
import { Client } from "@marimo-team/client";
const client = new Client("http://127.0.0.1:2718/api/marimo/v1", {
token: "your-token",
});
Requests use HTTP and event streams use server-sent events. Pass fetch
alongside token to customize requests.
Find notebooks
The catalog stream describes the host's notebooks, projects, runtimes, and attachments. It also reports the host's capabilities. This example prints the notebooks the host currently knows about.
for await (const event of client.events({ types: ["notebook"] })) {
if (event.event === "notebook") {
console.log(event.data.notebook.id, event.data.notebook.name);
}
if (event.event === "ready") break;
}
ready ends the initial snapshot. Breaking out closes the stream. Projects
may still be indexing when ready arrives, so more notebooks can appear
afterward.
Discover local hosts in Node.js
discoverHosts() performs local discovery
on macOS and Linux (requires procps on Linux). This example lists the notebooks
each discovered host currently knows about:
import { Client } from "@marimo-team/client";
import { discoverHosts } from "@marimo-team/client/node";
for await (const host of discoverHosts()) {
const client = new Client(host.url, { token: host.token });
for await (const event of client.events({ types: ["notebook"] })) {
if (event.event === "ready") break;
if (event.event === "notebook") {
console.log(event.data.notebook.id, event.data.notebook.name);
}
}
}
Work with a notebook
Use an id or a notebook record from the catalog to get a NotebookClient.
This example reads the document, prints its cell count, and asks the host
to save it. It assumes the notebook supports notebook.save.
import type { DocumentOutput } from "@marimo-team/client/protocol";
const notebook = client.notebook("n1");
let document: DocumentOutput | undefined;
for await (const event of notebook.events({ types: ["document"] })) {
if (event.event === "document") document = event.data.document;
if (event.event === "reset") document = undefined;
if (event.event === "ready") break;
}
if (document === undefined) throw new Error("The host did not send a document");
console.log(`${document.order.length} cells`);
const result = await notebook.save({ ifMatch: document.etag });
if (result.ok) {
console.log("Saved", result.data.document.etag);
} else {
console.error(result.problem);
}
ifMatch makes the document's etag a precondition. If the document changes
before the save, the host returns a conflict problem. Other actions, such
as edit and run, use the same result shape. The notebook's advertised
operations describe which actions it permits. Invalid request data,
invalid responses, and connection failures throw.
You can also construct a NotebookClient directly when you already know
the notebook's URL.
Follow changes
Keep iterating after ready to follow changes. Streams reconnect and resume
from their last cursor. If they cannot resume, they deliver reset followed
by a new snapshot. Discard accumulated state on reset before applying the
snapshot.
To maintain a notebook list or document state from events, see the reducer guide.
To follow events over a WebSocket or another connection, see the custom transport guide.
Contributing
The host protocol explains the model and
behavior. OpenAPI defines the routes and
payloads. @marimo-team/client/protocol exports the TypeScript types and Zod
schemas generated from it.
Run these commands from the repository root. See CONTRIBUTING.md for setup.
The package is consumed from dist. Build it once, or watch for changes
while developing.
pnpm --dir packages/client build
pnpm --dir packages/client build --watch
After changing OpenAPI, regenerate the protocol types, schemas, and
operation definitions. codegen:check checks that generated files match
the specification. Generation requires uv as well as the Node toolchain:
both language generators use the same Python overlay composer. The checked-in
client includes experimental features, including Analysis.
pnpm --dir packages/client codegen
pnpm --dir packages/client codegen:check
The package commands opt into all experimental features so Turbo builds retain
the APIs the handwritten client consumes. Use codegen:stable for stable-only
bindings, using
--output-dir to keep them separate from the client's checked-in bindings. Use
--include-experimental=analysis to select a feature. This selects generated
contracts; it does not create a separate stable build of the client package.
See the host protocol tooling for details.
Run the package's tests and typecheck. Omit --run to watch tests while
developing.
pnpm --dir packages/client test --run
pnpm --dir packages/client typecheck