feat: support serving a gallery of notebooks (#8056)

## 📝 Summary

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

```shell
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:

<img width="1047" height="983" alt="Screenshot 2026-01-29 at 19 24 02"
src="https://github.com/user-attachments/assets/bb6b949c-52f8-4e34-b675-8628e22e0dc4"
/>

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

- [x] I have read the [contributor
guidelines](https://github.com/marimo-team/marimo/blob/main/CONTRIBUTING.md).
- [x] For large changes, or changes that affect the public API: this
change was discussed or approved through an issue, on
[Discord](https://marimo.io/discord?ref=pr), or the community
[discussions](https://github.com/marimo-team/marimo/discussions) (Please
provide a link if applicable).
- [x] Tests have been added for the changes made.
- [x] Documentation has been updated where applicable, including
docstrings for API changes.
- [x] Pull request title is a good summary of the changes - it will be
used in the [release
notes](https://github.com/marimo-team/marimo/releases).

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: peter-gy

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

@@ -0,0 +1,158 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { SearchIcon } from "lucide-react";
+import type React from "react";
+import { Suspense, useMemo, useState } from "react";
+import { ErrorBoundary } from "@/components/editor/boundary/ErrorBoundary";
+import { Spinner } from "@/components/icons/spinner";
+import { Card, CardContent } from "@/components/ui/card";
+import { Input } from "@/components/ui/input";
+import { getSessionId } from "@/core/kernel/session";
+import { useRequestClient } from "@/core/network/requests";
+import { useAsyncData } from "@/hooks/useAsyncData";
+import { Banner } from "@/plugins/impl/common/error-banner";
+import { prettyError } from "@/utils/errors";
+import { PathBuilder, Paths } from "@/utils/paths";
+import { asURL } from "@/utils/url";
+
+const capitalize = (word: string): string => {
+  return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
+};
+
+const titleCase = (path: string): string => {
+  const delimiter = PathBuilder.guessDeliminator(path).deliminator;
+  return path
+    .replace(/\.[^./]+$/, "")
+    .split(delimiter)
+    .filter(Boolean)
+    .map((part) => part.split(/[_-]/).map(capitalize).join(" "))
+    .join(" > ");
+};
+
+const tabTarget = (path: string): string => {
+  return `${getSessionId()}-${encodeURIComponent(path)}`;
+};
+
+const SEARCH_THRESHOLD = 10;
+
+const GalleryPage: React.FC = () => {
+  const { getWorkspaceFiles } = useRequestClient();
+  const [searchQuery, setSearchQuery] = useState("");
+  const response = useAsyncData(
+    () => getWorkspaceFiles({ includeMarkdown: false }),
+    [],
+  );
+  const workspace = response.data;
+  const files = workspace?.files ?? [];
+  const root = workspace?.root ?? "";
+
+  const formattedFiles = useMemo(() => {
+    return files
+      .filter((file) => !file.isDirectory)
+      .map((file) => {
+        const relativePath =
+          root && Paths.isAbsolute(file.path) && file.path.startsWith(root)
+            ? Paths.rest(file.path, root)
+            : file.path;
+        const title = titleCase(Paths.basename(relativePath));
+        const subtitle = titleCase(Paths.dirname(relativePath));
+        return {
+          ...file,
+          relativePath,
+          title,
+          subtitle,
+        };
+      })
+      .sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+  }, [files, root]);
+
+  const filteredFiles = useMemo(() => {
+    if (!searchQuery) {
+      return formattedFiles;
+    }
+    const query = searchQuery.toLowerCase();
+    return formattedFiles.filter((file) =>
+      file.title.toLowerCase().includes(query),
+    );
+  }, [formattedFiles, searchQuery]);
+
+  if (response.isPending) {
+    return <Spinner centered={true} size="xlarge" className="mt-6" />;
+  }
+
+  if (response.error) {
+    return (
+      <Banner kind="danger" className="rounded p-4">
+        {prettyError(response.error)}
+      </Banner>
+    );
+  }
+
+  if (!workspace) {
+    return <Spinner centered={true} size="xlarge" className="mt-6" />;
+  }
+
+  return (
+    <Suspense>
+      <div className="flex flex-col gap-6 max-w-6xl container pt-5 pb-20 z-10">
+        <img src="logo.png" alt="marimo logo" className="w-48 mb-2" />
+        <ErrorBoundary>
+          <div className="flex flex-col gap-2">
+            {workspace.hasMore && (
+              <Banner kind="warn" className="rounded p-4">
+                Showing first {workspace.fileCount} files. Your workspace has
+                more files.
+              </Banner>
+            )}
+            {formattedFiles.length > SEARCH_THRESHOLD && (
+              <Input
+                id="search"
+                value={searchQuery}
+                icon={<SearchIcon className="h-4 w-4" />}
+                onChange={(event) => setSearchQuery(event.target.value)}
+                placeholder="Search"
+                rootClassName="mb-3"
+                className="mb-0 border-border"
+              />
+            )}
+            {filteredFiles.length === 0 ? (
+              <Banner kind="warn" className="rounded p-4">
+                No marimo apps found.
+              </Banner>
+            ) : (
+              <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
+                {filteredFiles.map((file) => (
+                  <a
+                    key={file.path}
+                    href={asURL(
+                      `?file=${encodeURIComponent(file.relativePath)}`,
+                    ).toString()}
+                    target={tabTarget(file.path)}
+                    className="no-underline"
+                  >
+                    <Card className="h-full hover:bg-accent/20 transition-colors">
+                      <CardContent className="p-6">
+                        <div className="flex flex-col gap-1">
+                          {file.subtitle && (
+                            <div className="text-sm font-semibold text-muted-foreground">
+                              {file.subtitle}
+                            </div>
+                          )}
+                          <div className="text-lg font-medium">
+                            {file.title}
+                          </div>
+                        </div>
+                      </CardContent>
+                    </Card>
+                  </a>
+                ))}
+              </div>
+            )}
+          </div>
+        </ErrorBoundary>
+      </div>
+    </Suspense>
+  );
+};
+
+export default GalleryPage;

frontend/src/core/MarimoApp.tsx

@@ -34,10 +34,15 @@ const LazyRunPage = reactLazyWithPreload(
 const LazyEditPage = reactLazyWithPreload(
   () => import("@/components/pages/edit-page"),
 );
+const LazyGalleryPage = reactLazyWithPreload(
+  () => import("@/components/pages/gallery-page"),
+);
 
 export function preloadPage(mode: string) {
   if (mode === "home") {
     LazyHomePage.preload();
+  } else if (mode === "gallery") {
+    LazyGalleryPage.preload();
   } else if (mode === "read") {
     LazyRunPage.preload();
   } else {
@@ -58,6 +63,9 @@ export const MarimoApp: React.FC = memo(() => {
     if (initialMode === "home") {
       return <LazyHomePage.Component />;
     }
+    if (initialMode === "gallery") {
+      return <LazyGalleryPage.Component />;
+    }
     if (initialMode === "read") {
       return <LazyRunPage.Component appConfig={appConfig} />;
     }

frontend/src/core/mode.ts

@@ -13,8 +13,9 @@ import { store } from "./state/jotai";
  * - `edit`: A user is editing the notebook. Can switch to present mode.
  * - `present`: A user is presenting the notebook, it looks like read mode but with some editing features. Cannot switch to present mode.
  * - `home`: A user is in the home page.
+ * - `gallery`: A user is in the gallery page.
  */
-export type AppMode = "read" | "edit" | "present" | "home";
+export type AppMode = "read" | "edit" | "present" | "home" | "gallery";
 
 export function getInitialAppMode(): Exclude<AppMode, "present"> {
   const initialMode = store.get(initialModeAtom);
@@ -28,8 +29,8 @@ export function getInitialAppMode(): Exclude<AppMode, "present"> {
 
 export function toggleAppMode(mode: AppMode): AppMode {
   // Can't switch to present mode.
-  if (mode === "read") {
-    return "read";
+  if (mode === "read" || mode === "home" || mode === "gallery") {
+    return mode;
   }
 
   return mode === "edit" ? "present" : "edit";

frontend/src/core/run-app.tsx

@@ -56,13 +56,38 @@ export const RunApp: React.FC<AppProps> = ({ appConfig }) => {
     return <CellsRenderer appConfig={appConfig} mode="read" />;
   };
 
+  const galleryHref = (() => {
+    if (typeof window === "undefined") {
+      return null;
+    }
+    const url = new URL(window.location.href);
+    if (!url.searchParams.has("file")) {
+      return null;
+    }
+    url.searchParams.delete("file");
+    const search = url.searchParams.toString();
+    return search ? `${url.pathname}?${search}` : url.pathname;
+  })();
+
   return (
     <AppContainer
       connection={connection}
       isRunning={isRunning}
       width={appConfig.width}
     >
-      <AppHeader connection={connection} className={"sm:pt-8"} />
+      <AppHeader connection={connection} className={"sm:pt-8"}>
+        {galleryHref && (
+          <div className="flex items-center px-6 pt-4">
+            <a
+              href={galleryHref}
+              aria-label="Back to gallery"
+              className="inline-flex items-center"
+            >
+              <img src="logo.png" alt="marimo logo" className="h-6 w-auto" />
+            </a>
+          </div>
+        )}
+      </AppHeader>
       {renderCells()}
     </AppContainer>
   );

frontend/src/mount.tsx

@@ -153,14 +153,16 @@ const mountOptionsSchema = z.object({
     .nullish()
     .transform((val) => val ?? "unknown"),
   /**
-   * 'edit' or 'read'/'run' or 'home'
+   * 'edit' or 'read'/'run' or 'home' or 'gallery'
    */
-  mode: z.enum(["edit", "read", "home", "run"]).transform((val): AppMode => {
-    if (val === "run") {
-      return "read";
-    }
-    return val;
-  }),
+  mode: z
+    .enum(["edit", "read", "home", "run", "gallery"])
+    .transform((val): AppMode => {
+      if (val === "run") {
+        return "read";
+      }
+      return val;
+    }),
   /**
    * marimo config
    */