feat: support serving a gallery of notebooks by peter-gy · Pull Request #8056 · marimo-team/marimo

peter-gy · 2026-01-29T19:57:41Z

📝 Summary

Enables running multiple marimo notebook files as a gallery of apps in the below style:

marimo run folder
marimo run folder another_folder
marimo run file_a.py file_b.py folder

When pointed to a local clone of https://github.com/marimo-team/learn this gives us:

Closes #3257

🔍 Description of Changes

I based this work on #4961, borrowing the idea of reusing the existing home page infrastructure used in marimo edit mode and adding gallery as a new frontend view in marimo run mode.

Gallery item links are encoded through /?file=<encoded> to avoid introducing new routing / mounting logic
Navigation is restricted so that we don't accept arbitrary /?file=<encoded> values
- extended marimo._server.file_router.ListOfFilesAppFileRouter to behave like an allowlist router
Preserved existing marimo run app.py -- --arg value behavior working while enabling marimo run file_a.py file_b.py folder and still allowing notebook args to be explicitly separated
Added a root directory heuristic for nicer URLs and less path leakage (via marimo._cli.cli.py._resolve_root_dir)
- e.g. if I run uv run marimo run /Users/petergy/Projects/opensource/marimo-team/learn. the learn repo is recognized as gallery root, so opening /Users/petergy/Projects/opensource/marimo-team/learn/functional_programming/05_functors.py will be available under http://localhost:2720/?file=functional_programming%2F05_functors.py
Gallery entries have auto-generated title and subtitle for now (notebook dir and file name piped through titleCase)

TODO before undrafting this

define --sandbox semantics
- per-notebook or per-gallery venv?
- should we create sandbox eagerly (we create all the venvs at cmd execution time) or lazily (create venv only on notebook visit)?

📋 Checklist

I have read the contributor guidelines.
For large changes, or changes that affect the public API: this change was discussed or approved through an issue, on Discord, or the community discussions (Please provide a link if applicable).
Tests have been added for the changes made.
Documentation has been updated where applicable, including docstrings for API changes.
Pull request title is a good summary of the changes - it will be used in the release notes.

vercel · 2026-01-29T19:57:46Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
marimo-docs	Ready	Preview, Comment	Jan 30, 2026 11:41am

for more information, see https://pre-commit.ci

frontend/src/components/pages/gallery-page.tsx

marimo/_server/file_router.py

marimo/_server/api/endpoints/home.py

mscolnick · 2026-01-29T21:36:30Z

cc @dmadisetti, its still in draft but can you check out the Sandbox semantics here

dmadisetti

I think this is a great start. Followups that might be useful:

return to home from an app page
thumbnails

As is, gallery sandbox falls back to ipc sandbox, which I think is fine. It provides consistency in experience.

We do need to fail fast if pyzmq is not installed like in sandboxed home.

But as is, even with pyzmq- this doesn't seem to work for --sandbox (at least locally, I'm getting blank screens for things that should otherwise work) and also --check.

I'd be OK raising an error for these flags, and following up in another PR. I think marimo run --sandbox falls under some of my wheelhouse so I can grab it if you'd like

marimo/_cli/cli.py

dmadisetti · 2026-01-29T21:53:25Z

marimo/_cli/cli.py

+    # correctness check - don't start the server if we can't import the module
+    for path in validated_paths:
+        if Path(path).is_file():
+            check_app_correctness(path)


We maybe want to do this on launch and not stop the server itself from spawning?

I think about this is more of a UX tradeoff than a purely technical one. Based on #3257 my understanding is that in gallery mode we're aiming at potentially non‑technical end users, so I lean toward fail‑fast at launch: if an app check fails, I'd rather surface that to the developer than risk an end user launching a broken app. Happy to discuss alternatives ofc. Maybe we add a CLI flag to toggle between lazy and eager checks?

dmadisetti · 2026-01-29T21:54:33Z

marimo/_server/api/endpoints/home.py

+        ]
+        file_count = len(marimo_files)
+        has_more = file_count >= MAX_FILES
+        return WorkspaceFilesResponse(


Not sure if we should dynamically load more apps? Torn on this (see comment above)

I see value in loading more apps dynamically but also see the associated concerns. Maybe let's consider adding a CLI flag to control this?

marimo/_server/file_router.py

marimo/_cli/cli.py

peter-gy · 2026-01-30T10:09:03Z

Thanks for the feedback @dmadisetti

I think this is a great start. Followups that might be useful:

return to home from an app page

For now I added a clickable marimo logo to go back.

Alternatively, we could go with a back arrow + "Gallery" text maybe or "Gallery / " breadcrumbs with Gallery clickable. I am not convinced though that everyone who deploys a multi-app env will want to call it "Gallery" (hence I just went with the logo for now)

thumbnails

That's exactly what we started to discuss with Myles. We'd want to generate OpenGraph content on the fly, (allowing users to overwrite it e.g. as PEP 723 metadata and add marimo tools thumbnails generate using playwright to snapshot the HTML output of a notebook and place it under __marimo__ folder. The developer experience around the metadata generation could be inspired by Next.js' generateMetadata: https://nextjs.org/docs/app/api-reference/functions/generate-metadata

As is, gallery sandbox falls back to ipc sandbox, which I think is fine. It provides consistency in experience.

We do need to fail fast if pyzmq is not installed like in sandboxed home.

But as is, even with pyzmq- this doesn't seem to work for --sandbox (at least locally, I'm getting blank screens for things that should otherwise work) and also --check.

I'd be OK raising an error for these flags, and following up in another PR. I think marimo run --sandbox falls under some of my wheelhouse so I can grab it if you'd like

That would be great. This way I can focus in this PR on better aesthetics through thumbnail (+ Partial<OpenGraph>) metadata generation. I modified the CLI to raise error on --sandbox and --check for now when running multiple apps.

peter-gy · 2026-01-30T13:38:52Z

This CI error does not seem to be related to changes made in this PR: https://github.com/marimo-team/marimo/actions/runs/21514574296/job/61989661450?pr=8056

mscolnick

amazing stuff! great work

github-actions · 2026-01-30T13:55:20Z

🚀 Development release published. You may be able to view the changes at https://marimo.app?v=0.19.8-dev1

@manzt

## 📝 Summary Adds notebook-level OpenGraph metadata (PEP 723 + [Next.js-inspired](https://nextjs.org/docs/app/api-reference/functions/generate-metadata) optional generator hook) with thumbnail generation plumbing. As a first use case, wired it up to improve gallery cards in `marimo run <dir>`. Follow-up of #8056. ## 🔍 Description of Changes - Introduced `OpenGraphMetadata` for notebooks via PEP 723: `[tool.marimo.opengraph]` with `title`, `description`, `image`, and optional `generator` - `image` supports either an HTTPS URL or a notebook-relative path - Added Next.js-style merge semantics for generators: static PEP 723 fields are the base; generator can override only the fields it returns - Added a canonical thumbnail endpoint: `GET /api/home/thumbnail?file=...` - redirects to HTTPS images - serves notebook-relative images only from the notebook’s `__marimo__/` directory - falls back to a branded placeholder SVG when no image exists - Inject OG tags into notebook pages (`og:title`, `og:description`, `og:image`) - Gallery cards now prefer `FileInfo.opengraph` (title/description/image) and fall back to the existing title-casing behavior - Added `marimo tools thumbnails generate ...` to write thumbnails to `__marimo__/assets/<stem>/opengraph.png` - default is `--no-execute` (fast; no cell outputs) - opt-in `--execute` to include outputs - opt-in `--sandbox` (only applies with `--execute`) ## 📸 Thumbnails > in the examples below `marimo-team/learn` is a local clone of https://github.com/marimo-team/learn ### Auto-generated thumbnails without `playwright` No file gets written to disk. The `/thumbnail` API endpoint calls `DEFAULT_OPENGRAPH_PLACEHOLDER_IMAGE_GENERATOR` to construct an SVG dynamically and serves it. <img width="1111" height="1314" alt="Screenshot 2026-02-03 at 14 36 25" src="https://github.com/user-attachments/assets/73cdaa8c-ba4a-4c4e-a27d-cb48163b17b5" /> ### Auto-generated thumbnails with `playwright`, but without notebook execution Renders code blocks without outputs, similar to Observable, as suggested by @manzt. ``` marimo tools thumbnails generate marimo-team/learn marimo run marimo-team/learn ``` <img width="1111" height="1314" alt="Screenshot 2026-02-03 at 14 40 50" src="https://github.com/user-attachments/assets/d02611bd-e094-4031-ac7b-fec82330960a" /> ### Auto-generated thumbnails with `playwright`, with sandboxed notebook execution for cell outputs > If you have generated thumbnails, pass ` --overwrite` to `marimo tools thumbnails` to ensure they get replaced. ``` marimo tools thumbnails generate marimo-team/learn --execute --sandbox marimo run marimo-team/learn ``` <img width="1111" height="1314" alt="Screenshot 2026-02-03 at 14 49 52" src="https://github.com/user-attachments/assets/9d6e0ea4-3845-436f-9ab5-9defd274cdc6" /> ## ⚡️ Generators Users can define custom functions to return OG metadata based on bespoke logic. Below an example of a notebook (1) defining `generator = "generate_opengraph"` in PEP 723 then (2) implementing `def generate_opengraph(context, parent):` as `@app.function` to return the metadata dynamically, yielding a custom card from with image from https://placehold.co/1200x630/png. <img width="374" height="345" alt="Screenshot 2026-02-03 at 14 58 42" src="https://github.com/user-attachments/assets/478af1c1-e6f3-4fc7-a79f-e604f39b591d" /> ```python # /// script # dependencies = [ # "marimo>=0.19.0", # "pyzmq>=27.1.0", # ] # [tool.marimo.opengraph] # description = "The description is static, but the title and image have been computed dynamically using a generator function defined within the notebook." # generator = "generate_opengraph" # /// import marimo __generated_with = "0.19.7" app = marimo.App(width="medium") @app.cell(hide_code=True) def _(mo): mo.md(""" # Dynamic OpenGraph Image """) return @app.function def generate_opengraph(context, parent): import datetime as dt from pathlib import Path from urllib.parse import quote_plus # Merge behavior: we return `title` and `image`, so static PEP 723 description # remains intact, as `description` is already present in `parent` label = quote_plus(dt.datetime.now().isoformat()) return { "title": f"Dynamic OpenGraph", "image": f"https://placehold.co/1200x630/png?text={label}" } @app.cell(hide_code=True) def _(): import marimo as mo return (mo,) if __name__ == "__main__": app.run() ```

## 📝 Summary Docs for #8056 and #8097. --------- Co-authored-by: Akshay Agrawal <akshaykagrawal7@gmail.com>

peter-gy added 3 commits January 29, 2026 20:43

feat: add gallery mode page

d85b917

feat: support multi-target run with allowlisted gallery

eea7118

test: cover run gallery routing

f8c8d4d

vercel bot deployed to Preview January 29, 2026 19:58 View deployment

[pre-commit.ci] auto fixes from pre-commit.com hooks

150cc75

for more information, see https://pre-commit.ci

vercel bot deployed to Preview January 29, 2026 20:00 View deployment

mscolnick reviewed Jan 29, 2026

View reviewed changes

frontend/src/components/pages/gallery-page.tsx Show resolved Hide resolved

mscolnick reviewed Jan 29, 2026

View reviewed changes

marimo/_server/file_router.py Show resolved Hide resolved

mscolnick reviewed Jan 29, 2026

View reviewed changes

marimo/_server/api/endpoints/home.py Show resolved Hide resolved

mscolnick requested a review from dmadisetti January 29, 2026 21:36

dmadisetti reviewed Jan 29, 2026

View reviewed changes

dmadisetti added enhancement New feature or request release-highlight A feature or change to call out in upcoming release notes labels Jan 29, 2026

vercel bot deployed to Preview January 30, 2026 09:41 View deployment

peter-gy added 4 commits January 30, 2026 10:45

fix: normalize allowlist paths and stream flatten_files

bcde40c

fix: guard gallery runs from sandbox and check flags

928d952

test: add run-mode allowlist edge case

b674695

feat: include markdown notebooks in gallery scan

f8566b8

peter-gy force-pushed the ptr/notebook-gallery branch from 5fe2b13 to f8566b8 Compare January 30, 2026 09:45

vercel bot deployed to Preview January 30, 2026 09:46 View deployment

feat: navigate back to home from app

bd53b7c

vercel bot deployed to Preview January 30, 2026 10:11 View deployment

fix: allowlist edit sessions for gallery

f9d4d8b

vercel bot deployed to Preview January 30, 2026 10:17 View deployment

vercel bot deployed to Preview January 30, 2026 11:00 View deployment

peter-gy force-pushed the ptr/notebook-gallery branch from fb5521d to 5f19848 Compare January 30, 2026 11:07

vercel bot deployed to Preview January 30, 2026 11:08 View deployment

fix: disable dynamic allowlist in gallery run

f31df50

peter-gy force-pushed the ptr/notebook-gallery branch from 5f19848 to f31df50 Compare January 30, 2026 11:08

vercel bot deployed to Preview January 30, 2026 11:09 View deployment

fix: allow dynamic allowlist for single-file

b0faa3b

vercel bot deployed to Preview January 30, 2026 11:41 View deployment

peter-gy marked this pull request as ready for review January 30, 2026 13:37

peter-gy requested review from Light2Dark and manzt as code owners January 30, 2026 13:37

peter-gy requested a review from mscolnick January 30, 2026 13:38

mscolnick approved these changes Jan 30, 2026

View reviewed changes

mscolnick merged commit 33ebb52 into marimo-team:main Jan 30, 2026
39 of 46 checks passed

dmadisetti mentioned this pull request Jan 30, 2026

Feature Request: Marimo notebooks with app view marimo-team/marimo-jupyter-extension#4

Open

This was referenced Feb 3, 2026

feat: rich notebook previews through OpenGraph metadata #8097

Merged

feat: replace logo with back button for notebooks in gallery mode #8099

Merged

peter-gy mentioned this pull request Feb 4, 2026

docs: gallery + OpenGraph preview docs #8122

Merged

mscolnick pushed a commit that referenced this pull request Feb 10, 2026

docs: gallery + OpenGraph preview docs (#8122)

669b894

## 📝 Summary Docs for #8056 and #8097. --------- Co-authored-by: Akshay Agrawal <akshaykagrawal7@gmail.com>

Conversation

peter-gy commented Jan 29, 2026

📝 Summary

🔍 Description of Changes

TODO before undrafting this

📋 Checklist

Uh oh!

vercel bot commented Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mscolnick commented Jan 29, 2026

Uh oh!

dmadisetti left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

dmadisetti Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

peter-gy Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

dmadisetti Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

peter-gy Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

peter-gy commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

peter-gy commented Jan 30, 2026

Uh oh!

mscolnick left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot commented Jan 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vercel bot commented Jan 29, 2026 •

edited

Loading

peter-gy commented Jan 30, 2026 •

edited

Loading