marimo notebook Cards

Choose Add Card → marimo notebook on Mac or Web. The starting point is an ordinary Python Card containing editable src/notebook.py, its small src/main.py adapter, default.nix, and a typed output schema. The implementation uses the pinned ps.marimo package through the existing Python SDK. Add notebook dependencies in default.nix; no package installation happens when opening a result.

One committed invocation

Connect a typed value to data. The default binding maps inputs.data.value to the notebook variable source, and param.factor to the notebook variable factor. The notebook computes result; the adapter returns a mapping with that finite numeric value on value and the saved notebook Directory on report: {"value": {"value": value}, "report": {"value": str(folder)}}. This follows the ordinary Card form main(inputs[, report[, run]]) -> outputs; the SDK encodes the mapping using the output schema. Edit the schema and returned mapping for other result types.

The adapter reads generated input and parameter types. Bindings can pass scalar values, row/column structures, or a File/Directory’s value path. The mapping must provide all variables defined by an overridden configuration cell: this is the behavior of marimo’s public App.run(defs=…) API. Put unrelated configuration in separate cells. Notebook source and the adapter remain editable in the normal Card source editor.

Each invocation copies its source into a private working directory and starts a fresh Python child process. After it succeeds, the worker copies the completed snapshot to the invocation’s output directory. It calls App.run() once, obtains the returned cell outputs and definitions, and writes a static snapshot. The adapter publishes typed outputs only after that process succeeds. It does not call marimo export afterward: the export command runs the notebook again, which could repeat side effects. Notebook reactive dependencies determine the order of cells inside that one execution; they never directly emit Card messages or start downstream Cards.

The scaffold sets reuseWorker: false. Its child remains in the worker’s process group. On failure, cancellation, deadline, project shutdown, and normal completion, the scheduler owns termination of that worker and anything it started. There is no detached session, browser, listening socket or interactive notebook server in this scaffold. Changing params and running again produces a new invocation and artifact, without rewriting a previous result.

Saved results and source

The report Directory is retained as an artifact and includes:

• index.html: the static cell outputs, selected values and source-cell names/line numbers;
• assets/: saved PNG figures, also embedded as data images in HTML;
• result.json, bindings.json, metadata.json: selected definitions, supplied values and run/Card/invocation identity;
• source/: the exact notebook and adapter source copied for that invocation.

The static HTML includes ordinary Markdown/HTML, text and Matplotlib figures. It needs no JavaScript, CDN or running kernel. Frontend-only custom widgets are replaced by a note pointing to the saved source; this is a snapshot, not marimo’s complete interactive frontend. The shared static HTML preview displays this self-contained HTML in both clients with scripts disabled. A saved result can be reopened from history after restarting the project. Editing the downloaded HTML does not change recorded results or send downstream messages.

A notebook error fails the Card and emits no typed result. Logs list source-cell names and source lines before execution, then retain the Python/marimo traceback. The failure diagnostic names the notebook; the source editor opens that saved or current .py file. Graph errors, missing bindings, absent selected variables and nonnumeric selected values are errors rather than partial successful reports.

In the bilingual marimo notebook → typed result demo, the upstream Card scales a measurement of 7 by factor = 2. The notebook visualizes the original and scaled values and sends the selected value of 14 to an ordinary Bash Card that logs and displays it. Change factor on the upstream Card to 3 and rerun it to get 21 and a new snapshot.