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: Sandboxed gallery (#8076)

Dylan Madisettia5eccf8d2ec3
diff --git a/frontend/src/components/editor/renderers/vertical-layout/vertical-layout.tsx b/frontend/src/components/editor/renderers/vertical-layout/vertical-layout.tsx
index ddcd6fd7d4..6c713cf9fc 100644
--- a/frontend/src/components/editor/renderers/vertical-layout/vertical-layout.tsx
+++ b/frontend/src/components/editor/renderers/vertical-layout/vertical-layout.tsx
@@ -7,6 +7,7 @@ import {
CodeIcon,
FolderDownIcon,
ImageIcon,
+ Loader2Icon,
MoreHorizontalIcon,
} from "lucide-react";
import type React from "react";
@@ -32,6 +33,7 @@ import { MarkdownLanguageAdapter } from "@/core/codemirror/language/languages/ma
import { useResolvedMarimoConfig } from "@/core/config/config";
import { CSSClasses, KnownQueryParams } from "@/core/constants";
import type { OutputMessage } from "@/core/kernel/messages";
+import { kernelStateAtom } from "@/core/kernel/state";
import { showCodeInRunModeAtom } from "@/core/meta/state";
import { isErrorMime } from "@/core/mime";
import { type AppMode, kioskModeAtom } from "@/core/mode";
@@ -63,6 +65,7 @@ const VerticalLayoutRenderer: React.FC<VerticalLayoutProps> = ({
}) => {
const { invisible } = useDelayVisibility(cells.length, mode);
const kioskMode = useAtomValue(kioskModeAtom);
+ const kernelState = useAtomValue(kernelStateAtom);
const [userConfig] = useResolvedMarimoConfig();
const showCodeInRunModePreference = useAtomValue(showCodeInRunModeAtom);
@@ -140,6 +143,15 @@ const VerticalLayoutRenderer: React.FC<VerticalLayoutProps> = ({
}
if (cells.length === 0 && !invisible) {
+ // If kernel is not yet instantiated, show loading state
+ if (!kernelState.isInstantiated) {
+ return (
+ <div className="flex-1 flex flex-col items-center justify-center py-8">
+ <Loader2Icon className="w-8 h-8 animate-spin text-muted-foreground" />
+ </div>
+ );
+ }
+ // Kernel is ready but no cells - truly empty notebook
return (
<div className="flex-1 flex flex-col items-center justify-center py-8">
<Alert variant="info">
diff --git a/marimo/_cli/cli.py b/marimo/_cli/cli.py
index 453d9260af..9b81154523 100644
--- a/marimo/_cli/cli.py
+++ b/marimo/_cli/cli.py
@@ -1109,10 +1109,6 @@ def run(
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:
@@ -1133,7 +1129,8 @@ def run(
# We check this after name validation, because this will convert
# URLs into local file paths
if is_multi:
- sandbox_mode = None
+ # Gallery mode: use MULTI sandbox (IPC kernels) or None
+ sandbox_mode = SandboxMode.MULTI if sandbox else None
else:
sandbox_mode = resolve_sandbox_mode(
sandbox=sandbox, name=validated_paths[0]
@@ -1142,6 +1139,18 @@ def run(
run_in_sandbox(sys.argv[1:], name=validated_paths[0])
return
+ # Multi-file sandbox: use IPC kernels with per-notebook sandboxed venvs
+ if sandbox_mode is SandboxMode.MULTI:
+ # Check for pyzmq dependency
+ from marimo._dependencies.dependencies import DependencyManager
+
+ if not DependencyManager.zmq.has():
+ raise click.UsageError(
+ "pyzmq is required when running a gallery with --sandbox.\n"
+ "Install it with: pip install 'marimo[sandbox]'\n"
+ "Or: pip install pyzmq"
+ )
+
if is_multi:
marimo_files = _collect_marimo_files(validated_paths)
file_router = AppFileRouter.from_files(
diff --git a/marimo/_ipc/launch_kernel.py b/marimo/_ipc/launch_kernel.py
index 3386629c15..1ac8315831 100644
--- a/marimo/_ipc/launch_kernel.py
+++ b/marimo/_ipc/launch_kernel.py
@@ -45,15 +45,13 @@ def main() -> None:
# Virtual files require a web server to serve file URLs. Since we're
# not running one, content must be embedded as data URLs instead.
virtual_files_supported=False,
- # NB: Unique parameter combination required for ZeroMQ. The `stream_queue`
- # and `socket_addr` are mutually exclusive. Normally RUN mode doesn't
- # redirect console, while EDIT mode does. Our ZeroMQ proxy needs both
- # `stream_queue` AND console redirection, but also other behavior of
- # EDIT, so we require this combination.
+ # NB: IPC kernels are always subprocesses (is_ipc=True) but may be
+ # edit or run mode based on is_edit_mode.
stream_queue=queue_manager.stream_queue,
socket_addr=None,
- is_edit_mode=True,
- redirect_console_to_browser=True,
+ is_edit_mode=not args.is_run_mode,
+ is_ipc=True,
+ redirect_console_to_browser=args.redirect_console_to_browser,
)
diff --git a/marimo/_ipc/types.py b/marimo/_ipc/types.py
index 71d1f49894..92211a32da 100644
--- a/marimo/_ipc/types.py
+++ b/marimo/_ipc/types.py
@@ -34,6 +34,8 @@ class KernelArgs(msgspec.Struct):
log_level: int
profile_path: typing.Union[str, None]
connection_info: ConnectionInfo
+ # Whether to use run-mode config (autorun) vs edit-mode config (lazy)
+ is_run_mode: bool = False
# Runtime behavior flags
virtual_files_supported: bool = True
redirect_console_to_browser: bool = True
diff --git a/marimo/_runtime/runtime.py b/marimo/_runtime/runtime.py
index e904b0284b..c53d872699 100644
--- a/marimo/_runtime/runtime.py
+++ b/marimo/_runtime/runtime.py
@@ -3153,11 +3153,18 @@ def launch_kernel(
interrupt_queue: QueueType[bool] | None = None,
profile_path: Optional[str] = None,
log_level: int | None = None,
+ is_ipc: bool = False,
) -> None:
if log_level is not None:
_loggers.set_level(log_level)
LOGGER.debug("Launching kernel")
- if is_edit_mode:
+
+ # Determine behavior:
+ # - is_subprocess: edit mode uses Process, IPC uses subprocess - both can receive signals
+ # - Run mode (not edit) uses autorun config regardless of IPC
+ is_subprocess = is_edit_mode or is_ipc
+
+ if is_subprocess:
restore_signals()
profiler = None
@@ -3261,7 +3268,10 @@ def launch_kernel(
# completions only provided in edit mode
kernel.start_completion_worker(completion_queue)
- # In edit mode, kernel runs in its own process so it's interruptible.
+ if is_subprocess:
+ # Subprocess kernels (EDIT and IPC_RUN) can receive signals and need
+ # their own formatter registration since they don't share state with
+ # the host process.
from marimo._output.formatters.formatters import register_formatters
# TODO: Windows workaround -- find a way to make the process
@@ -3272,8 +3282,7 @@ def launch_kernel(
# Ctrl+C in particular.
os.setsid()
- # kernels are processes in edit mode, and each process needs to
- # install the formatter import hooks
+ # Each subprocess kernel needs to install the formatter import hooks
register_formatters(theme=user_config["display"]["theme"])
signal.signal(signal.SIGINT, handlers.construct_interrupt_handler(ctx))
@@ -3313,7 +3322,9 @@ def launch_kernel(
# triggered on Windows when quit with Ctrl+C
LOGGER.debug("kernel queue.get() failed %s", e)
break
- LOGGER.debug("Received control request: %s", request)
+ LOGGER.debug(
+ "Received control request: %s", type(request).__name__
+ )
if isinstance(request, StopKernelCommand):
break
elif isinstance(request, UpdateUIElementCommand):
diff --git a/marimo/_server/api/endpoints/assets.py b/marimo/_server/api/endpoints/assets.py
index 36af00134e..fe3dfab96c 100644
--- a/marimo/_server/api/endpoints/assets.py
+++ b/marimo/_server/api/endpoints/assets.py
@@ -24,6 +24,7 @@ from marimo._server.templates.templates import (
inject_script,
notebook_page_template,
)
+from marimo._session.model import SessionMode
from marimo._utils.async_path import AsyncPath
from marimo._utils.paths import marimo_package_path, normalize_path
@@ -148,10 +149,12 @@ async def index(request: Request) -> HTMLResponse:
app_config = app_manager.app.config
# Pre-compute notebook snapshot for faster initial render
- # Only in SandboxMode.MULTI where each notebook gets its own IPC kernel
+ # Only in EDIT + SandboxMode.MULTI where each notebook gets its own IPC
+ # kernel.
notebook_snapshot = None
if (
app_state.session_manager.sandbox_mode is SandboxMode.MULTI
+ and app_state.mode == SessionMode.EDIT
and app_manager.filename
):
from marimo._convert.converters import MarimoConvert
diff --git a/marimo/_session/managers/ipc.py b/marimo/_session/managers/ipc.py
index 8c61cd8e88..e05bb54ff2 100644
--- a/marimo/_session/managers/ipc.py
+++ b/marimo/_session/managers/ipc.py
@@ -171,6 +171,7 @@ class IPCKernelManagerImpl(KernelManager):
log_level=GLOBAL_SETTINGS.LOG_LEVEL,
profile_path=None,
connection_info=self.connection_info,
+ is_run_mode=self.mode == SessionMode.RUN,
virtual_files_supported=self.virtual_files_supported,
redirect_console_to_browser=self.redirect_console_to_browser,
)
diff --git a/tests/_cli/test_cli.py b/tests/_cli/test_cli.py
index e23defe359..2ee249436c 100644
--- a/tests/_cli/test_cli.py
+++ b/tests/_cli/test_cli.py
@@ -621,17 +621,25 @@ def test_cli_run_directory_gallery() -> None:
_check_contents(p, b'"mode": "gallery"', contents)
-def test_cli_run_directory_gallery_rejects_sandbox() -> None:
[email protected](not HAS_UV, reason="uv is required for sandbox tests")
+def test_cli_run_directory_gallery_with_sandbox() -> None:
+ """Test that gallery mode works with --sandbox flag."""
directory = tempfile.TemporaryDirectory()
_temp_run_file(directory)
- result = subprocess.run(
- ["marimo", "run", directory.name, "--sandbox"],
- capture_output=True,
- text=True,
+ port = _get_port()
+ p = subprocess.Popen(
+ [
+ "marimo",
+ "run",
+ directory.name,
+ "--sandbox",
+ "-p",
+ str(port),
+ "--headless",
+ ]
)
- output = result.stderr + result.stdout
- assert result.returncode != 0
- assert "--sandbox is not supported with gallery runs yet." in output
+ contents = _try_fetch(port)
+ _check_contents(p, b'"mode": "gallery"', contents)
def test_cli_run_directory_gallery_rejects_check() -> None:
@@ -696,6 +704,66 @@ def test_cli_run_multiple_files_gallery() -> None:
_check_contents(p, b'"mode": "gallery"', contents)
[email protected](not HAS_UV, reason="uv is required for sandbox tests")
+def test_cli_run_directory_gallery_sandbox_can_open_file() -> None:
+ """Test that individual notebooks can be opened from gallery in sandbox mode."""
+ directory = tempfile.TemporaryDirectory()
+ _temp_run_file(directory)
+ port = _get_port()
+ p = subprocess.Popen(
+ [
+ "marimo",
+ "run",
+ directory.name,
+ "--sandbox",
+ "-p",
+ str(port),
+ "--headless",
+ ]
+ )
+ try:
+ contents = _try_fetch(port)
+ assert contents is not None
+ assert b'"mode": "gallery"' in contents
+
+ # Open a specific notebook from gallery
+ 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()
+
+
[email protected](not HAS_UV, reason="uv is required for sandbox tests")
+def test_cli_run_multiple_files_gallery_sandbox() -> None:
+ """Test gallery mode with multiple explicit files and --sandbox."""
+ 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),
+ "--sandbox",
+ "-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: