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.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
feat: support serving a gallery of notebooks (#8056)
Péter Gyarmati33ebb52c4910
diff --git a/frontend/src/components/pages/gallery-page.tsx b/frontend/src/components/pages/gallery-page.tsxnew file mode 100644index 0000000000..0e952ff84a--- /dev/null+++ b/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;diff --git a/frontend/src/core/MarimoApp.tsx b/frontend/src/core/MarimoApp.tsxindex a89c4e449f..ad51e96a7c 100644--- a/frontend/src/core/MarimoApp.tsx+++ b/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} />;}diff --git a/frontend/src/core/mode.ts b/frontend/src/core/mode.tsindex b16a0869d9..80cfa5cdca 100644--- a/frontend/src/core/mode.ts+++ b/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";diff --git a/frontend/src/core/run-app.tsx b/frontend/src/core/run-app.tsxindex 1006f5fe7b..990e47672a 100644--- a/frontend/src/core/run-app.tsx+++ b/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 (<AppContainerconnection={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>);diff --git a/frontend/src/mount.tsx b/frontend/src/mount.tsxindex 3aadf1ae7a..07ffdb3193 100644--- a/frontend/src/mount.tsx+++ b/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*/diff --git a/marimo/_cli/cli.py b/marimo/_cli/cli.pyindex 4269fc1acc..453d9260af 100644--- a/marimo/_cli/cli.py+++ b/marimo/_cli/cli.py@@ -6,10 +6,12 @@ import jsonimport osimport sysimport tempfile+from dataclasses import dataclassfrom pathlib import Pathfrom typing import Any, Optionalimport click+from click.core import ParameterSourceimport marimo._cli.cli_validators as validatorsfrom marimo import _loggers@@ -33,7 +35,9 @@ from marimo._cli.utils import ()from marimo._config.settings import GLOBAL_SETTINGSfrom marimo._lint import run_check-from marimo._server.file_router import AppFileRouter+from marimo._server.file_router import AppFileRouter, flatten_files+from marimo._server.files.directory_scanner import DirectoryScanner+from marimo._server.models.home import MarimoFilefrom marimo._server.start import startfrom marimo._session.model import SessionModefrom marimo._tutorials import (@@ -41,6 +45,7 @@ from marimo._tutorials import (create_temp_tutorial_file,tutorial_order,) # type: ignore+from marimo._utils.http import HTTPException, HTTPStatusfrom marimo._utils.marimo_path import MarimoPath, create_temp_notebook_filefrom marimo._utils.platform import is_windowsfrom marimo._version import __version__@@ -783,6 +788,91 @@ def new()+@dataclass(frozen=True)+class _CollectedRunFiles:+ files: list[MarimoFile]+ root_dir: str | None+++def _split_run_paths_and_args(+ name: str, args: tuple[str, ...]+) -> tuple[list[str], tuple[str, ...]]:+ paths = [name]+ for index, arg in enumerate(args):+ if arg == "--":+ return paths, args[index + 1 :]+ if arg.startswith("-"):+ return paths, args[index:]+ paths.append(arg)+ return paths, ()+++def _resolve_root_dir(+ directories: list[str], files: list[MarimoFile]+) -> str | None:+ # Choose a "root" directory for gallery links when there is an obvious+ # shared base directory. This lets us use relative `?file=` keys (and+ # avoids leaking absolute paths) when possible.+ if len(directories) == 1:+ directory = Path(directories[0]).absolute()+ if not files:+ return str(directory)+ # Only use this directory root if it contains all selected files.+ if all(+ Path(file.path).absolute().is_relative_to(directory)+ for file in files+ ):+ return str(directory)+ return None++ if not directories:+ if not files:+ return None+ parent = Path(files[0].path).absolute().parent+ # Only use a parent root when all files are siblings.+ if all(Path(file.path).absolute().parent == parent for file in files):+ return str(parent)++ return None+++def _collect_marimo_files(paths: list[str]) -> _CollectedRunFiles:+ directories: list[str] = []+ files_by_path: dict[str, MarimoFile] = {}++ for path in paths:+ if Path(path).is_dir():+ directories.append(path)+ directory = Path(path).absolute()+ scanner = DirectoryScanner(path, include_markdown=True)+ try:+ file_infos = scanner.scan()+ except HTTPException as exc:+ if exc.status_code != HTTPStatus.REQUEST_TIMEOUT:+ raise+ file_infos = scanner.partial_results+ for file_info in flatten_files(file_infos):+ if not file_info.is_marimo_file:+ continue+ absolute_path = str(directory / file_info.path)+ files_by_path[absolute_path] = MarimoFile(+ name=file_info.name,+ path=absolute_path,+ last_modified=file_info.last_modified,+ )+ else:+ marimo_path = MarimoPath(path)+ files_by_path[marimo_path.absolute_name] = MarimoFile(+ name=marimo_path.relative_name,+ path=marimo_path.absolute_name,+ last_modified=marimo_path.last_modified,+ )++ files = sorted(files_by_path.values(), key=lambda file: file.path)+ root_dir = _resolve_root_dir(directories, files)+ return _CollectedRunFiles(files=files, root_dir=root_dir)++@main.command(help="""Run a notebook as an app in read-only mode.@@ -791,6 +881,8 @@ If NAME is a url, the notebook will be downloaded to a temporary file.Example:marimo run notebook.py+ marimo run folder another_folder+ marimo run app.py -- --arg value""")@click.option(@@ -938,6 +1030,7 @@ Example:hidden=True,help="Custom asset URL for loading static resources. Can include {version} placeholder.",)[email protected]_context@click.argument("name",required=True,@@ -945,6 +1038,7 @@ Example:)@click.argument("args", nargs=-1, type=click.UNPROCESSED)def run(+ ctx: click.Context,port: Optional[int],host: str,proxy: Optional[str],@@ -973,11 +1067,15 @@ def run(run_in_sandbox,)- if prompt_run_in_docker_container(name, trusted=trusted):+ paths, notebook_args = _split_run_paths_and_args(name, args)++ if len(paths) == 1 and prompt_run_in_docker_container(+ paths[0], trusted=trusted+ ):from marimo._cli.run_docker import run_in_dockerrun_in_docker(- name,+ paths[0],"run",port=port,debug=GLOBAL_SETTINGS.DEVELOPMENT_MODE,@@ -988,31 +1086,77 @@ def run(# The second return value is an optional temporary directory. It is unused,# but must be kept around because its lifetime on disk is bound to the life# of the Python object- name, _ = validate_name(name, allow_new_file=False, allow_directory=False)+ validated_paths: list[str] = []+ temp_dirs: list[tempfile.TemporaryDirectory[str]] = []+ for path in paths:+ validated_path, temp_dir = validate_name(+ path, allow_new_file=False, allow_directory=True+ )+ if temp_dir is not None:+ temp_dirs.append(temp_dir)+ validated_paths.append(validated_path)- # correctness check - don't start the server if we can't import the module- check_app_correctness(name)- file = MarimoPath(name)- if check:- from marimo._lint import collect_messages+ has_directory = any(Path(path).is_dir() for path in validated_paths)+ is_multi = has_directory or len(validated_paths) > 1- linter, message = collect_messages(file.absolute_name)- if linter.errored:- raise click.ClickException(- red("Failure")- + ": The notebook has errors, fix them before running.\n"- + message.strip()- )+ check_source = ctx.get_parameter_source("check")+ check_explicit = check_source not in (+ ParameterSource.DEFAULT,+ ParameterSource.DEFAULT_MAP,+ )++ if is_multi and check and check_explicit:+ raise click.UsageError(+ "--check is only supported when running a single notebook file."+ )+ if is_multi and sandbox:+ raise click.UsageError(+ "--sandbox is not supported with gallery runs yet."+ )++ # 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)+ if check and not has_directory:+ from marimo._lint import collect_messages++ file = MarimoPath(path)+ linter, message = collect_messages(file.absolute_name)+ if linter.errored:+ raise click.ClickException(+ red("Failure")+ + ": The notebook has errors, fix them before running.\n"+ + message.strip()+ )# We check this after name validation, because this will convert# URLs into local file paths- # For run command, only single-file sandbox is possible (no directory support)- if resolve_sandbox_mode(sandbox=sandbox, name=name) is SandboxMode.SINGLE:- run_in_sandbox(sys.argv[1:], name=name)- return+ if is_multi:+ sandbox_mode = None+ else:+ sandbox_mode = resolve_sandbox_mode(+ sandbox=sandbox, name=validated_paths[0]+ )+ if sandbox_mode is SandboxMode.SINGLE:+ run_in_sandbox(sys.argv[1:], name=validated_paths[0])+ return++ if is_multi:+ marimo_files = _collect_marimo_files(validated_paths)+ file_router = AppFileRouter.from_files(+ marimo_files.files,+ directory=marimo_files.root_dir,+ allow_single_file_key=False,+ allow_dynamic=False,+ )+ else:+ file_router = AppFileRouter.from_filename(+ MarimoPath(validated_paths[0])+ )start(- file_router=AppFileRouter.from_filename(file),+ file_router=file_router,development_mode=GLOBAL_SETTINGS.DEVELOPMENT_MODE,quiet=GLOBAL_SETTINGS.QUIET,host=host,@@ -1026,8 +1170,8 @@ def run(skew_protection=skew_protection,base_url=base_url,allow_origins=allow_origins,- cli_args=parse_args(args),- argv=list(args),+ cli_args=parse_args(notebook_args),+ argv=list(notebook_args),auth_token=resolve_token(token,token_password=token_password,@@ -1036,6 +1180,7 @@ def run(redirect_console_to_browser=redirect_console_to_browser,server_startup_command=server_startup_command,asset_url=asset_url,+ sandbox_mode=sandbox_mode,)diff --git a/marimo/_server/api/endpoints/assets.py b/marimo/_server/api/endpoints/assets.pyindex 6763d91076..36af00134e 100644--- a/marimo/_server/api/endpoints/assets.py+++ b/marimo/_server/api/endpoints/assets.py@@ -136,6 +136,7 @@ async def index(request: Request) -> HTMLResponse:user_config=app_state.config_manager.get_user_config(),config_overrides=app_state.config_manager.get_config_overrides(),server_token=app_state.skew_protection_token,+ mode=app_state.mode,asset_url=app_state.asset_url,)else:diff --git a/marimo/_server/api/endpoints/home.py b/marimo/_server/api/endpoints/home.pyindex b42c8ec3c4..bb71e85022 100644--- a/marimo/_server/api/endpoints/home.py+++ b/marimo/_server/api/endpoints/home.py@@ -15,7 +15,9 @@ from marimo._server.api.deps import AppStatefrom marimo._server.api.utils import parse_requestfrom marimo._server.file_router import (LazyListOfFilesAppFileRouter,+ ListOfFilesAppFileRouter,count_files,+ flatten_files,)from marimo._server.files.directory_scanner import DirectoryScannerfrom marimo._server.models.home import (@@ -28,7 +30,7 @@ from marimo._server.models.home import (WorkspaceFilesResponse,)from marimo._server.router import APIRouter-from marimo._session.model import ConnectionState+from marimo._session.model import ConnectionState, SessionModefrom marimo._tutorials import create_temp_tutorial_file # type: ignorefrom marimo._utils.paths import pretty_path@@ -69,7 +71,7 @@ async def read_code(@router.post("/workspace_files")-@requires("edit")+@requires("read")async def workspace_files(*,request: Request,@@ -91,6 +93,22 @@ async def workspace_files(body = await parse_request(request, cls=WorkspaceFilesRequest)session_manager = AppState(request).session_manager+ if session_manager.mode == SessionMode.RUN:+ files = await asyncio.to_thread(+ lambda: session_manager.file_router.files+ )+ marimo_files = [+ file for file in flatten_files(files) if file.is_marimo_file+ ]+ file_count = len(marimo_files)+ has_more = file_count >= MAX_FILES+ return WorkspaceFilesResponse(+ files=marimo_files,+ root=session_manager.file_router.directory or "",+ has_more=has_more,+ file_count=file_count,+ )+# Maybe enable markdownroot = ""if isinstance(session_manager.file_router, LazyListOfFilesAppFileRouter):@@ -228,6 +246,12 @@ async def tutorial(app_state.session_manager.file_router, LazyListOfFilesAppFileRouter):app_state.session_manager.file_router.register_temp_dir(temp_dir.name)+ elif isinstance(+ app_state.session_manager.file_router, ListOfFilesAppFileRouter+ ):+ app_state.session_manager.file_router.register_allowed_file(+ path.absolute_name+ )return MarimoFile(name=os.path.basename(path.absolute_name),diff --git a/marimo/_server/file_router.py b/marimo/_server/file_router.pyindex 3410d9d20e..c57ddf382c 100644--- a/marimo/_server/file_router.py+++ b/marimo/_server/file_router.py@@ -4,7 +4,7 @@ from __future__ import annotationsimport abcimport osfrom pathlib import Path-from typing import Optional+from typing import TYPE_CHECKING, Optionalfrom marimo import _loggersfrom marimo._server.app_defaults import AppDefaults@@ -15,6 +15,10 @@ from marimo._server.models.home import MarimoFilefrom marimo._session.notebook import AppFileManagerfrom marimo._utils.http import HTTPException, HTTPStatusfrom marimo._utils.marimo_path import MarimoPath+from marimo._utils.paths import normalize_path++if TYPE_CHECKING:+ from collections.abc import IteratorLOGGER = _loggers.marimo_logger()@@ -53,15 +57,26 @@ class AppFileRouter(abc.ABC):last_modified=file.last_modified,)]- return ListOfFilesAppFileRouter(files)+ return ListOfFilesAppFileRouter(files, allow_dynamic=True)@staticmethoddef from_directory(directory: str) -> AppFileRouter:return LazyListOfFilesAppFileRouter(directory, include_markdown=False)@staticmethod- def from_files(files: list[MarimoFile]) -> AppFileRouter:- return ListOfFilesAppFileRouter(files)+ def from_files(+ files: list[MarimoFile],+ *,+ directory: str | None = None,+ allow_single_file_key: bool = True,+ allow_dynamic: bool = False,+ ) -> AppFileRouter:+ return ListOfFilesAppFileRouter(+ files,+ directory=directory,+ allow_single_file_key=allow_single_file_key,+ allow_dynamic=allow_dynamic,+ )@staticmethoddef new_file() -> AppFileRouter:@@ -132,8 +147,24 @@ class NewFileAppFileRouter(AppFileRouter):class ListOfFilesAppFileRouter(AppFileRouter):- def __init__(self, files: list[MarimoFile]) -> None:+ def __init__(+ self,+ files: list[MarimoFile],+ directory: str | None = None,+ allow_single_file_key: bool = True,+ allow_dynamic: bool = False,+ ) -> None:self._files = files+ self._directory = directory+ self._allow_single_file_key = allow_single_file_key+ self._allow_dynamic = allow_dynamic+ self._allowed_paths = {+ MarimoPath(file.path).absolute_name for file in files+ }++ @property+ def directory(self) -> str | None:+ return self._directory@propertydef files(self) -> list[FileInfo]:@@ -149,21 +180,61 @@ class ListOfFilesAppFileRouter(AppFileRouter):for file in self._files]+ def get_file_manager(+ self,+ key: MarimoFileKey,+ defaults: Optional[AppDefaults] = None,+ ) -> AppFileManager:+ defaults = defaults or AppDefaults()++ if key.startswith(AppFileRouter.NEW_FILE):+ if self._allow_single_file_key:+ return AppFileManager(None, defaults=defaults)+ raise HTTPException(+ status_code=HTTPStatus.NOT_FOUND,+ detail=f"File {key} not found",+ )++ filepath = Path(key)+ if not filepath.is_absolute() and self._directory:+ filepath = Path(self._directory) / filepath+ normalized_path = normalize_path(filepath)+ absolute_path = str(normalized_path)+ if absolute_path not in self._allowed_paths:+ raise HTTPException(+ status_code=HTTPStatus.NOT_FOUND,+ detail=f"File {key} not found",+ )++ if normalized_path.exists():+ return AppFileManager(absolute_path, defaults=defaults)++ raise HTTPException(+ status_code=HTTPStatus.NOT_FOUND,+ detail=f"File {key} not found",+ )+def get_unique_file_key(self) -> Optional[MarimoFileKey]:- if len(self.files) == 1:- return self.files[0].path+ if self._allow_single_file_key and len(self._files) == 1:+ return self._files[0].pathreturn Nonedef maybe_get_single_file(self) -> Optional[MarimoFile]:- if len(self.files) == 1:- file = self.files[0]- return MarimoFile(- name=file.name,- path=file.path,- last_modified=file.last_modified,- )+ if self._allow_single_file_key and len(self._files) == 1:+ return self._files[0]return None+ def register_allowed_file(self, filepath: str) -> None:+ """Allow a file path in this router.++ This extends the allowlist for files that were not part of the original+ collection and may live outside the router's base directory (for+ example, files created at runtime in a separate location).+ """+ if not self._allow_dynamic:+ return+ self._allowed_paths.add(MarimoPath(filepath).absolute_name)+class LazyListOfFilesAppFileRouter(AppFileRouter):def __init__(self, directory: str, include_markdown: bool) -> None:@@ -291,3 +362,14 @@ def count_files(file_list: list[FileInfo]) -> int:if item.children:count += count_files(item.children)return count+++def flatten_files(files: list[FileInfo]) -> Iterator[FileInfo]:+ """Iterate over files, skipping directories."""+ stack = files.copy()+ while stack:+ file = stack.pop()+ if file.is_directory:+ stack.extend(file.children)+ else:+ yield filediff --git a/marimo/_server/session_manager.py b/marimo/_server/session_manager.pyindex 9fb0eb186d..6cb9db852d 100644--- a/marimo/_server/session_manager.py+++ b/marimo/_server/session_manager.py@@ -20,7 +20,12 @@ from marimo._runtime.commands import (SerializedQueryParams,)from marimo._server.app_defaults import AppDefaults-from marimo._server.file_router import AppFileRouter, MarimoFileKey+from marimo._server.file_router import (+ AppFileRouter,+ ListOfFilesAppFileRouter,+ MarimoFileKey,+ flatten_files,+)from marimo._server.lsp import LspServerfrom marimo._server.recents import RecentFilesManagerfrom marimo._server.resume_strategies import create_resume_strategy@@ -96,8 +101,17 @@ class SessionManager:def _get_code() -> str:defaults = AppDefaults.from_config_manager(config_manager)- app = file_router.get_single_app_file_manager(defaults).app- return "".join(code for code in app.cell_manager.codes())+ if file_router.get_unique_file_key() is not None:+ app = file_router.get_single_app_file_manager(defaults).app+ return "".join(code for code in app.cell_manager.codes())++ files = list(flatten_files(file_router.files))+ entries = [+ f"{file.path}:{file.last_modified or 0.0}"+ for file in files+ if file.is_marimo_file+ ]+ return "\n".join(sorted(entries))source_code = None if mode == SessionMode.EDIT else _get_code()self._token_manager = TokenManager(@@ -137,6 +151,12 @@ class SessionManager:def app_manager(self, key: MarimoFileKey) -> AppFileManager:"""Get the app manager for the given key."""defaults = AppDefaults.from_config_manager(self._config_manager)+ if (+ self.mode is SessionMode.EDIT+ and isinstance(self.file_router, ListOfFilesAppFileRouter)+ and not key.startswith(AppFileRouter.NEW_FILE)+ ):+ self.file_router.register_allowed_file(key)return self.file_router.get_file_manager(key, defaults)def create_session(@@ -157,6 +177,12 @@ class SessionManager:# Get app file managerdefaults = AppDefaults.from_config_manager(self._config_manager)+ if (+ self.mode is SessionMode.EDIT+ and isinstance(self.file_router, ListOfFilesAppFileRouter)+ and not file_key.startswith(AppFileRouter.NEW_FILE)+ ):+ self.file_router.register_allowed_file(file_key)app_file_manager = self.file_router.get_file_manager(file_key, defaults)diff --git a/marimo/_server/templates/templates.py b/marimo/_server/templates/templates.pyindex dec4a4cd6f..68cf482065 100644--- a/marimo/_server/templates/templates.py+++ b/marimo/_server/templates/templates.py@@ -45,7 +45,7 @@ def json_script(data: Any) -> str:def _get_mount_config(*,filename: Optional[str],- mode: Literal["edit", "home", "read"],+ mode: Literal["edit", "home", "read", "gallery"],server_token: SkewProtectionToken,user_config: MarimoConfig,config_overrides: PartialMarimoConfig,@@ -100,6 +100,7 @@ def home_page_template(user_config: MarimoConfig,config_overrides: PartialMarimoConfig,server_token: SkewProtectionToken,+ mode: SessionMode,asset_url: Optional[str] = None,) -> str:html = html.replace("{{ base_url }}", base_url)@@ -115,11 +116,14 @@ def home_page_template(html = _replace_asset_urls(html, asset_url)+ app_mode: Literal["home", "gallery"] = (+ "home" if mode == SessionMode.EDIT else "gallery"+ )html = html.replace(MOUNT_CONFIG_TEMPLATE,_get_mount_config(filename=None,- mode="home",+ mode=app_mode,server_token=server_token,user_config=user_config,config_overrides=config_overrides,diff --git a/tests/_cli/test_cli.py b/tests/_cli/test_cli.pyindex caca374523..e23defe359 100644--- a/tests/_cli/test_cli.py+++ b/tests/_cli/test_cli.py@@ -25,6 +25,7 @@ import pytestfrom marimo._ast import codegenfrom marimo._ast.cell import CellConfig+from marimo._cli.cli import _collect_marimo_filesfrom marimo._dependencies.dependencies import DependencyManagerfrom marimo._server.templates.templates import get_versionfrom marimo._utils.platform import is_windows@@ -609,6 +610,101 @@ def test_cli_run(temp_marimo_file: str) -> None:_check_contents(p, f'"version": "{get_version()}"'.encode(), contents)+def test_cli_run_directory_gallery() -> None:+ directory = tempfile.TemporaryDirectory()+ _temp_run_file(directory)+ port = _get_port()+ p = subprocess.Popen(+ ["marimo", "run", directory.name, "-p", str(port), "--headless"]+ )+ contents = _try_fetch(port)+ _check_contents(p, b'"mode": "gallery"', contents)+++def test_cli_run_directory_gallery_rejects_sandbox() -> None:+ directory = tempfile.TemporaryDirectory()+ _temp_run_file(directory)+ result = subprocess.run(+ ["marimo", "run", directory.name, "--sandbox"],+ capture_output=True,+ text=True,+ )+ output = result.stderr + result.stdout+ assert result.returncode != 0+ assert "--sandbox is not supported with gallery runs yet." in output+++def test_cli_run_directory_gallery_rejects_check() -> None:+ directory = tempfile.TemporaryDirectory()+ _temp_run_file(directory)+ result = subprocess.run(+ ["marimo", "run", directory.name, "--check"],+ capture_output=True,+ text=True,+ )+ output = result.stderr + result.stdout+ assert result.returncode != 0+ assert (+ "--check is only supported when running a single notebook file."+ in output+ )+++def test_cli_run_directory_gallery_can_open_file() -> None:+ directory = tempfile.TemporaryDirectory()+ _temp_run_file(directory)+ port = _get_port()+ p = subprocess.Popen(+ ["marimo", "run", directory.name, "-p", str(port), "--headless"]+ )+ try:+ contents = _try_fetch(port)+ assert contents is not None+ assert b'"mode": "gallery"' in contents++ url = f"http://localhost:{port}/?file=run.py"+ notebook_contents = urllib.request.urlopen(url).read()+ assert b'"mode": "read"' in notebook_contents+ finally:+ p.kill()+++def test_cli_run_multiple_files_gallery() -> None:+ directory = tempfile.TemporaryDirectory()+ filecontents = codegen.generate_filecontents(+ codes=["import marimo as mo"],+ names=["one"],+ cell_configs=[CellConfig()],+ )+ file_one = Path(directory.name) / "one.py"+ file_two = Path(directory.name) / "two.py"+ file_one.write_text(filecontents, encoding="utf-8")+ file_two.write_text(filecontents, encoding="utf-8")+ port = _get_port()+ p = subprocess.Popen(+ [+ "marimo",+ "run",+ str(file_one),+ str(file_two),+ "-p",+ str(port),+ "--headless",+ ]+ )+ contents = _try_fetch(port)+ _check_contents(p, b'"mode": "gallery"', contents)+++def test_collect_marimo_files_includes_markdown(+ tmp_path: Path,+) -> None:+ md_file = tmp_path / "notebook.md"+ md_file.write_text("---\nmarimo-version: 0.1.0\n---\n", encoding="utf-8")+ collected = _collect_marimo_files([str(tmp_path)])+ assert str(md_file) in {file.path for file in collected.files}++def test_cli_run_with_show_code(temp_marimo_file: str) -> None:port = _get_port()p = subprocess.Popen(diff --git a/tests/_server/api/endpoints/test_assets.py b/tests/_server/api/endpoints/test_assets.pyindex a1fc6a83ad..692d81a99e 100644--- a/tests/_server/api/endpoints/test_assets.py+++ b/tests/_server/api/endpoints/test_assets.py@@ -12,6 +12,7 @@ from marimo._server.api.deps import AppStatefrom marimo._server.api.endpoints.assets import _inject_service_workerfrom marimo._server.api.utils import parse_titlefrom marimo._server.file_router import AppFileRouter+from marimo._session.model import SessionModefrom tests._server.mocks import token_header, with_file_routerif TYPE_CHECKING:@@ -87,6 +88,19 @@ def test_index_with_directory(client: TestClient) -> None:assert "<title>marimo</title>" in content+@with_file_router(AppFileRouter.from_directory(TEMP_DIR.name))+def test_index_with_directory_run_mode(client: TestClient) -> None:+ app_state = AppState.from_app(cast(Any, client.app))+ app_state.session_manager.mode = SessionMode.RUN++ response = client.get("/", headers=token_header())+ assert response.status_code == 200, response.text+ content = response.text+ assert "<marimo-filename" in content+ assert '"mode": "gallery"' in content+ assert "<title>marimo</title>" in content++def test_favicon(client: TestClient) -> None:response = client.get("/favicon.ico")assert response.status_code == 200, response.textdiff --git a/tests/_server/api/endpoints/test_home.py b/tests/_server/api/endpoints/test_home.pyindex f882751e3c..16a26b9664 100644--- a/tests/_server/api/endpoints/test_home.py+++ b/tests/_server/api/endpoints/test_home.py@@ -5,10 +5,14 @@ import inspectimport osimport sysimport tempfile+from pathlib import Pathfrom typing import TYPE_CHECKINGimport pytest+from marimo._server.file_router import AppFileRouter+from marimo._server.models.home import MarimoFile+from marimo._session.model import SessionModefrom tests._server.conftest import get_session_managerfrom tests._server.mocks import token_header, with_session@@ -111,6 +115,96 @@ def test_cant_open_non_tutorial(client: TestClient) -> None:assert response.json() == {"detail": "Tutorial not found"}+@with_session(SESSION_ID)+def test_workspace_files_in_run_mode(client: TestClient) -> None:+ session_manager = get_session_manager(client)+ session_manager.mode = SessionMode.RUN++ with tempfile.TemporaryDirectory() as temp_dir:+ marimo_file = Path(temp_dir) / "notebook.py"+ marimo_file.write_text("import marimo\napp = marimo.App()")++ non_marimo_file = Path(temp_dir) / "text.txt"+ non_marimo_file.write_text("This is not a marimo file")++ session_manager.file_router = AppFileRouter.from_directory(temp_dir)++ response = client.post(+ "/api/home/workspace_files",+ headers=HEADERS,+ json={"include_markdown": False},+ )+ body = response.json()+ files = body["files"]++ assert len(files) == 1+ assert body["root"] == temp_dir+ assert files[0]["path"] == marimo_file.name+++@with_session(SESSION_ID)+def test_workspace_files_empty_directory(client: TestClient) -> None:+ session_manager = get_session_manager(client)+ session_manager.mode = SessionMode.RUN++ with tempfile.TemporaryDirectory() as temp_dir:+ session_manager.file_router = AppFileRouter.from_directory(temp_dir)++ response = client.post(+ "/api/home/workspace_files",+ headers=HEADERS,+ json={"include_markdown": False},+ )+ body = response.json()+ files = body["files"]++ assert len(files) == 0+++@with_session(SESSION_ID)+def test_workspace_files_run_mode_allowlist(client: TestClient) -> None:+ session_manager = get_session_manager(client)+ session_manager.mode = SessionMode.RUN++ with tempfile.TemporaryDirectory() as temp_dir:+ file_one = Path(temp_dir) / "one.py"+ file_one.write_text("import marimo\napp = marimo.App()")+ file_two = Path(temp_dir) / "two.py"+ file_two.write_text("import marimo\napp = marimo.App()")++ marimo_files = [+ MarimoFile(+ name=file_one.name,+ path=str(file_one),+ last_modified=file_one.stat().st_mtime,+ ),+ MarimoFile(+ name=file_two.name,+ path=str(file_two),+ last_modified=file_two.stat().st_mtime,+ ),+ ]+ session_manager.file_router = AppFileRouter.from_files(+ marimo_files,+ directory=temp_dir,+ allow_single_file_key=False,+ )++ response = client.post(+ "/api/home/workspace_files",+ headers=HEADERS,+ json={"include_markdown": False},+ )+ body = response.json()+ files = body["files"]++ assert body["root"] == temp_dir+ assert {file["path"] for file in files} == {+ str(file_one),+ str(file_two),+ }++@with_session(SESSION_ID)def test_tutorial_file_accessible_after_open(client: TestClient) -> None:"""Test that a tutorial file can be accessed after being opened.diff --git a/tests/_server/templates/test_templates.py b/tests/_server/templates/test_templates.pyindex aad259c4b6..f62367b582 100644--- a/tests/_server/templates/test_templates.py+++ b/tests/_server/templates/test_templates.py@@ -317,6 +317,7 @@ class TestHomePageTemplate(unittest.TestCase):self.user_config,self.config_overrides,self.server_token,+ SessionMode.EDIT,)assert self.base_url not in result@@ -338,6 +339,7 @@ class TestHomePageTemplate(unittest.TestCase):self.user_config,self.config_overrides,self.server_token,+ SessionMode.EDIT,asset_url=asset_url,)@@ -347,6 +349,19 @@ class TestHomePageTemplate(unittest.TestCase):assert 'crossorigin="anonymous"' in result_assert_no_leftover_replacements(result)+ def test_home_page_template_run_mode(self) -> None:+ result = templates.home_page_template(+ self.html,+ self.base_url,+ self.user_config,+ self.config_overrides,+ self.server_token,+ SessionMode.RUN,+ )++ assert "gallery" in result+ _assert_no_leftover_replacements(result)+class TestStaticNotebookTemplate(unittest.TestCase):def setUp(self) -> None:diff --git a/tests/_server/test_file_router.py b/tests/_server/test_file_router.pyindex 74c818e0d2..90bc4735e6 100644--- a/tests/_server/test_file_router.py+++ b/tests/_server/test_file_router.py@@ -10,10 +10,12 @@ import pytestfrom marimo._server.file_router import (AppFileRouter,+ FileInfo,LazyListOfFilesAppFileRouter,ListOfFilesAppFileRouter,NewFileAppFileRouter,count_files,+ flatten_files,)from marimo._server.files.directory_scanner import is_marimo_appfrom marimo._server.files.path_validator import PathValidator@@ -138,6 +140,46 @@ class TestAppFileRouter(unittest.TestCase):files = router.filesassert len(files) == 4+ def test_list_of_files_restricts_access(self):+ files = [+ MarimoFile(+ name="test.py",+ path=self.test_file1.name,+ last_modified=os.path.getmtime(self.test_file1.name),+ )+ ]+ router = ListOfFilesAppFileRouter(files)+ with pytest.raises(HTTPException) as exc:+ router.get_file_manager(self.test_file2.name)+ assert exc.value.status_code == HTTPStatus.NOT_FOUND++ def test_list_of_files_disallows_dynamic_allowlist(self):+ files = [+ MarimoFile(+ name="test.py",+ path=self.test_file1.name,+ last_modified=os.path.getmtime(self.test_file1.name),+ )+ ]+ router = ListOfFilesAppFileRouter(files, allow_dynamic=False)+ router.register_allowed_file(self.test_file2.name)+ with pytest.raises(HTTPException) as exc:+ router.get_file_manager(self.test_file2.name)+ assert exc.value.status_code == HTTPStatus.NOT_FOUND++ def test_list_of_files_disallows_new_file_key(self):+ files = [+ MarimoFile(+ name="test.py",+ path=self.test_file1.name,+ last_modified=os.path.getmtime(self.test_file1.name),+ )+ ]+ router = ListOfFilesAppFileRouter(files, allow_single_file_key=False)+ with pytest.raises(HTTPException) as exc:+ router.get_file_manager(AppFileRouter.NEW_FILE)+ assert exc.value.status_code == HTTPStatus.NOT_FOUND+def test_lazy_list_of_get_app_file_manager(self):router = LazyListOfFilesAppFileRouter(self.test_dir, include_markdown=False@@ -160,6 +202,68 @@ class TestAppFileRouter(unittest.TestCase):assert "nested" in file_manager.filename+def test_flatten_files() -> None:+ root = FileInfo(+ id="root",+ path="root",+ name="root",+ is_directory=True,+ is_marimo_file=False,+ children=[+ FileInfo(+ id="file1",+ path="root/file1.py",+ name="file1.py",+ is_directory=False,+ is_marimo_file=True,+ children=[],+ ),+ FileInfo(+ id="dir1",+ path="root/dir1",+ name="dir1",+ is_directory=True,+ is_marimo_file=False,+ children=[+ FileInfo(+ id="file2",+ path="root/dir1/file2.py",+ name="file2.py",+ is_directory=False,+ is_marimo_file=True,+ children=[],+ ),+ FileInfo(+ id="dir2",+ path="root/dir1/dir2",+ name="dir2",+ is_directory=True,+ is_marimo_file=False,+ children=[+ FileInfo(+ id="file3",+ path="root/dir1/dir2/file3.py",+ name="file3.py",+ is_directory=False,+ is_marimo_file=True,+ children=[],+ ),+ ],+ ),+ ],+ ),+ ],+ )++ flattened = list(flatten_files([root]))+ paths = {file.path for file in flattened}+ assert paths == {+ "root/file1.py",+ "root/dir1/file2.py",+ "root/dir1/dir2/file3.py",+ }++class TestValidateInsideDirectory(unittest.TestCase):def setUp(self):# Create a temporary directory structure