Skip to content

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.

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.tsx
new file mode 100644
index 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.tsx
index 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.ts
index 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.tsx
index 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 (
<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>
);
diff --git a/frontend/src/mount.tsx b/frontend/src/mount.tsx
index 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.py
index 4269fc1acc..453d9260af 100644
--- a/marimo/_cli/cli.py
+++ b/marimo/_cli/cli.py
@@ -6,10 +6,12 @@ import json
import os
import sys
import tempfile
+from dataclasses import dataclass
from pathlib import Path
from typing import Any, Optional
import click
+from click.core import ParameterSource
import marimo._cli.cli_validators as validators
from marimo import _loggers
@@ -33,7 +35,9 @@ from marimo._cli.utils import (
)
from marimo._config.settings import GLOBAL_SETTINGS
from 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 MarimoFile
from marimo._server.start import start
from marimo._session.model import SessionMode
from 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, HTTPStatus
from marimo._utils.marimo_path import MarimoPath, create_temp_notebook_file
from marimo._utils.platform import is_windows
from 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.",
)
@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_docker
run_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.py
index 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.py
index 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 AppState
from marimo._server.api.utils import parse_request
from marimo._server.file_router import (
LazyListOfFilesAppFileRouter,
+ ListOfFilesAppFileRouter,
count_files,
+ flatten_files,
)
from marimo._server.files.directory_scanner import DirectoryScanner
from 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, SessionMode
from marimo._tutorials import create_temp_tutorial_file # type: ignore
from 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 markdown
root = ""
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.py
index 3410d9d20e..c57ddf382c 100644
--- a/marimo/_server/file_router.py
+++ b/marimo/_server/file_router.py
@@ -4,7 +4,7 @@ from __future__ import annotations
import abc
import os
from pathlib import Path
-from typing import Optional
+from typing import TYPE_CHECKING, Optional
from marimo import _loggers
from marimo._server.app_defaults import AppDefaults
@@ -15,6 +15,10 @@ from marimo._server.models.home import MarimoFile
from marimo._session.notebook import AppFileManager
from marimo._utils.http import HTTPException, HTTPStatus
from marimo._utils.marimo_path import MarimoPath
+from marimo._utils.paths import normalize_path
+
+if TYPE_CHECKING:
+ from collections.abc import Iterator
LOGGER = _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)
@staticmethod
def 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,
+ )
@staticmethod
def 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
@property
def 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].path
return None
def 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 file
diff --git a/marimo/_server/session_manager.py b/marimo/_server/session_manager.py
index 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 LspServer
from marimo._server.recents import RecentFilesManager
from 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 manager
defaults = 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.py
index 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.py
index caca374523..e23defe359 100644
--- a/tests/_cli/test_cli.py
+++ b/tests/_cli/test_cli.py
@@ -25,6 +25,7 @@ import pytest
from marimo._ast import codegen
from marimo._ast.cell import CellConfig
+from marimo._cli.cli import _collect_marimo_files
from marimo._dependencies.dependencies import DependencyManager
from marimo._server.templates.templates import get_version
from 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.py
index 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 AppState
from marimo._server.api.endpoints.assets import _inject_service_worker
from marimo._server.api.utils import parse_title
from marimo._server.file_router import AppFileRouter
+from marimo._session.model import SessionMode
from tests._server.mocks import token_header, with_file_router
if 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.text
diff --git a/tests/_server/api/endpoints/test_home.py b/tests/_server/api/endpoints/test_home.py
index f882751e3c..16a26b9664 100644
--- a/tests/_server/api/endpoints/test_home.py
+++ b/tests/_server/api/endpoints/test_home.py
@@ -5,10 +5,14 @@ import inspect
import os
import sys
import tempfile
+from pathlib import Path
from typing import TYPE_CHECKING
import pytest
+from marimo._server.file_router import AppFileRouter
+from marimo._server.models.home import MarimoFile
+from marimo._session.model import SessionMode
from tests._server.conftest import get_session_manager
from 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.py
index 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.py
index 74c818e0d2..90bc4735e6 100644
--- a/tests/_server/test_file_router.py
+++ b/tests/_server/test_file_router.py
@@ -10,10 +10,12 @@ import pytest
from marimo._server.file_router import (
AppFileRouter,
+ FileInfo,
LazyListOfFilesAppFileRouter,
ListOfFilesAppFileRouter,
NewFileAppFileRouter,
count_files,
+ flatten_files,
)
from marimo._server.files.directory_scanner import is_marimo_app
from marimo._server.files.path_validator import PathValidator
@@ -138,6 +140,46 @@ class TestAppFileRouter(unittest.TestCase):
files = router.files
assert 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