fix: isolation when running multiple notebooks in an app server (marimo-team#8611)

**Summary.** This PR introduces process-level isolation when serving
multiple apps from the same server (`marimo run directory/`,
`create_asgi_app()`); clients of any given app are still run in threads
in the app's process for efficiency. This fixes a critical bug in which
different apps shared the same Python globals, leading to undefined
behavior such as collisions in `sys.modules. It does make multi-app
servers consume slightly more RAM.

Process isolation also applies to multi-app servers started with
`--sandbox`. (This PR also fixes a bug in which `--sandbox` run servers
silently dropped stdout/stderr.)

**Dependency on pyzmq.** The proposed implementation also adds a
dependency on `pyzmq` for multi-app servers, to pave the way for
allowing sandboxed multi-app servers . It would be possible to design a
different solution that used multiprocessing instead of `pyzmq`, at the
cost of not supporting package sandboxes. It is perhaps worth discussing
whether we are okay with making pyzmq a required dependency of marimo.

**Feature flag.** App isolation is feature-flagged, currently opt-in.

**Context.** When marimo was originally designed, `marimo run` only ever
served a single notebook. A single process could safely serve multiple
clients of the same notebook since they all share the same code.

When multiple app serving was introduced, we continued serving all
clients from a single process, even though the clients were potentially
running different programs. When two notebooks both `import utils` but
expect different implementations from different directories, whichever
app loads first wins, and the second app silently gets the wrong module.
Similar problems may exist for other Python globals.

**This PR.** This PR fixes the problem by running each app in its own OS
process. Multiple clients of the *same* app still share a process (as
kernel threads), which allows for fast and cheap sessions. The isolation
boundary is per-app, not per-client.

```
Before (shared process — sys.modules collisions):

  ┌──────────────── Main Process ─────────────────┐
  │                                               │
  │   Kernel(app1, client A)    ← all kernels     │
  │   Kernel(app1, client B)      share one       │
  │   Kernel(app2, client C)      sys.modules     │
  │   Kernel(app2, client D)                      │
  └───────────────────────────────────────────────┘

After (per-app process isolation):

  ┌──────────────── Main Process ─────────────────┐
  │           (HTTP, WebSocket, routing)           │
  └──────────────────┬──────────────┬──────────────┘
                     │ ZMQ          │ ZMQ
       ┌─────────────▼──┐   ┌──────▼──────────────┐
       │  App Process    │   │  App Process        │
       │  (app1.py)      │   │  (app2.py)          │
       │                 │   │                     │
       │  Kernel: cl. A  │   │  Kernel: cl. C      │
       │  Kernel: cl. B  │   │  Kernel: cl. D      │
       └─────────────────┘   └─────────────────────┘
        isolated sys.modules  isolated sys.modules
```


**IPC.** Each app process communicates with the main process over 4
shared ZeroMQ sockets (not per-client). Kernel commands and stream
output are multiplexed over these shared channels using session ID
tagging:

```
IPC channels (4 shared ZMQ sockets per app process):

  Main Process                             App Subprocess
  ────────────                             ──────────────
  mgmt     [PUSH] ─────────────────────▶ [PULL]  mgmt loop
  response [PULL] ◀───────────────────── [PUSH]  (create/stop kernel)
  cmd      [PUSH] ──[sid, channel, msg]─▶ [PULL]  dispatcher ──▶ kernel queues
  stream   [PULL] ◀──[sid, msg]───────── [PUSH]  collector  ◀── kernel output
```

```
Per session (main-process side):

  AppProcessQueueManager
    control_queue    ──┐
    ui_element_queue ──┤──▶ cmd socket (tagged with session_id)
    completion_queue ──┤
    input_queue      ──┘
    stream_queue     ◀──── stream receiver thread (regular Queue)
```

**When this path is activated.**

- `create_asgi_app()`: always enables process isolation (the whole point
is multi-app)
- `marimo run app1.py app2.py` / directory serving: auto-enables when
multiple files detected
- `marimo run app.py` (single file): no change, uses existing
thread-based kernels
- `marimo edit`: no change, uses existing process-based kernels

---------

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

Author: 2 people

marimo/_cli/cli.py

@@ -1189,6 +1189,14 @@ def run(
                 "pyzmq is required when running a gallery with --sandbox.",
                 "marimo[sandbox]",
             )
+    elif is_multi:
+        from marimo._dependencies.dependencies import DependencyManager
+
+        if not DependencyManager.zmq.has():
+            raise MarimoCLIMissingDependencyError(
+                "pyzmq is required for running multiple notebooks.",
+                "pyzmq",
+            )
 
     file_router = _create_run_file_router(validated_paths, watch=watch)
 

marimo/_config/config.py

@@ -568,6 +568,7 @@ class ExperimentalConfig(TypedDict, total=False):
     markdown: bool  # Used in playground (community cloud)
     wasm_layouts: bool  # Used in playground (community cloud)
     rtc_v2: bool
+    isolate_apps: bool
 
     # Internal features
     cache: CacheConfig

marimo/_ipc/connection.py

@@ -194,5 +194,7 @@ def close(self) -> None:
         if self._receiver_thread.is_alive():
             self._receiver_thread.join(timeout=1)
 
-        # Close all associated sockets (and finally terminate)
-        self.context.destroy()
+        # Close all sockets and terminate the context.
+        # linger=0 drops any unsent messages immediately, preventing
+        # hangs during shutdown when the remote end is already gone.
+        self.context.destroy(linger=0)

marimo/_server/asgi.py

@@ -462,6 +462,12 @@ async def root():
     else:
         auth_token = AuthToken(token)
 
+    from marimo._dependencies.dependencies import DependencyManager
+
+    DependencyManager.zmq.require(
+        "for running multiple notebooks with create_asgi_app()"
+    )
+
     # We call the entrypoint `root` instead of `filename` incase we want to
     # support directories or code in the future
     class Builder(ASGIAppBuilder):
@@ -521,6 +527,9 @@ def _create_app_for_file(base_url: str, file_path: str) -> ASGIApp:
                 auth_token=auth_token,
                 redirect_console_to_browser=redirect_console_to_browser,
                 ttl_seconds=session_ttl,
+                isolate_apps=config_reader.experimental.get(
+                    "isolate_apps", False
+                ),
             )
             enable_auth = not AuthToken.is_empty(auth_token)
             app = create_starlette_app(

marimo/_server/session_manager.py

@@ -32,6 +32,7 @@
 from marimo._server.session.listeners import RecentsTrackerListener
 from marimo._server.token_manager import TokenManager
 from marimo._server.tokens import AuthToken, SkewProtectionToken
+from marimo._session.app_host import AppHostContext, AppHostPool
 from marimo._session.consumer import SessionConsumer
 from marimo._session.events import SessionEventBus
 from marimo._session.extensions.types import SessionExtension
@@ -83,6 +84,7 @@ def __init__(
         ttl_seconds: Optional[int],
         watch: bool = False,
         sandbox_mode: SandboxMode | None = None,
+        isolate_apps: bool = False,
     ) -> None:
         # Core configuration
         self.file_router = file_router
@@ -97,6 +99,15 @@ def __init__(
         self._config_manager = config_manager
         self.sandbox_mode = sandbox_mode
 
+        # When running multiple apps, each app runs in an isolated  host
+        # process, to avoid collisions in sys.modules and other Python global
+        # structures. These processes are managed by an AppHostPool.
+        self._app_host_pool: AppHostPool | None = None
+        if isolate_apps and mode == SessionMode.RUN:
+            self._app_host_pool = AppHostPool(
+                sandbox=sandbox_mode is SandboxMode.MULTI,
+            )
+
         self._repository = SessionRepository()
 
         def _get_code() -> str:
@@ -222,6 +233,11 @@ def create_session(
             auto_instantiate=auto_instantiate,
             extensions=extensions,
             sandbox_mode=self.sandbox_mode,
+            app_host_context=AppHostContext(
+                pool=self._app_host_pool, session_id=session_id
+            )
+            if self._app_host_pool
+            else None,
         )
 
         # Add to repository
@@ -393,6 +409,8 @@ def shutdown(self) -> None:
         """Shutdown the session manager and stop all file watchers."""
         LOGGER.debug("Shutting down")
         self.close_all_sessions()
+        if self._app_host_pool is not None:
+            self._app_host_pool.shutdown()
         self.lsp_server.stop()
         self._watcher_manager.stop_all()
 

marimo/_server/start.py

@@ -248,6 +248,11 @@ def start(
             }
         )
 
+    is_multi = file_router.get_unique_file_key() is None
+    isolate_apps = is_multi and config_reader.experimental.get(
+        "isolate_apps", False
+    )
+
     session_manager = SessionManager(
         file_router=file_router,
         mode=mode,
@@ -262,6 +267,7 @@ def start(
         redirect_console_to_browser=redirect_console_to_browser,
         watch=watch,
         sandbox_mode=sandbox_mode,
+        isolate_apps=isolate_apps,
     )
 
     log_level = "info" if development_mode else "error"

marimo/_session/app_host/__init__.py

@@ -0,0 +1,18 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""App isolation for serving multiple notebooks.
+
+Each notebook is hosted in an AppHost, which isolates the notebook from other
+running notebooks. Sessions for the same notebook are routed to a single
+AppHost.
+
+AppHosts are created and managed by an AppHostPool.
+"""
+
+from marimo._session.app_host.host import AppHost
+from marimo._session.app_host.pool import AppHostContext, AppHostPool
+
+__all__ = [
+    "AppHost",
+    "AppHostContext",
+    "AppHostPool",
+]

marimo/_session/app_host/commands.py

@@ -0,0 +1,116 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Commands and responses."""
+
+from __future__ import annotations
+
+import enum
+import typing
+
+import msgspec
+import msgspec.json
+
+from marimo._ast.cell import CellConfig
+from marimo._config.config import MarimoConfig
+from marimo._runtime.commands import AppMetadata
+from marimo._types.ids import CellId_t
+
+
+# ---------------- Management commands ---------------------
+class CreateKernelCmd(msgspec.Struct, tag=True):
+    """Request the app host to create a new kernel thread."""
+
+    session_id: str
+    configs: dict[CellId_t, CellConfig]
+    app_metadata: AppMetadata
+    user_config: MarimoConfig
+    virtual_files_supported: bool
+    redirect_console_to_browser: bool
+    log_level: int
+
+
+class StopKernelCmd(msgspec.Struct, tag=True):
+    """Request the app host to stop a kernel thread."""
+
+    session_id: str
+
+
+class ShutdownAppHostCmd(msgspec.Struct, tag=True):
+    """Request the app host to shut down entirely."""
+
+
+# ---------------- Management responses ---------------------
+class AppHostReadyResponse(msgspec.Struct, tag=True):
+    """Signals that the app host has started and is ready."""
+
+
+class KernelCreatedResponse(msgspec.Struct, tag=True):
+    """Confirms a kernel was created (or reports failure)."""
+
+    session_id: str
+    success: bool
+    error: str | None = None
+
+
+# ---------------- Management encoders and decoders ---------------------
+MgmtCommand = typing.Union[CreateKernelCmd, StopKernelCmd, ShutdownAppHostCmd]
+MgmtResponse = typing.Union[AppHostReadyResponse, KernelCreatedResponse]
+
+_cmd_decoder = msgspec.json.Decoder(MgmtCommand)
+_resp_decoder = msgspec.json.Decoder(MgmtResponse)
+
+
+def encode_mgmt_command(cmd: MgmtCommand) -> bytes:
+    return msgspec.json.encode(cmd)
+
+
+def decode_mgmt_command(data: bytes) -> MgmtCommand:
+    result: MgmtCommand = _cmd_decoder.decode(data)
+    return result
+
+
+def encode_mgmt_response(resp: MgmtResponse) -> bytes:
+    return msgspec.json.encode(resp)
+
+
+def decode_mgmt_response(data: bytes) -> MgmtResponse:
+    result: MgmtResponse = _resp_decoder.decode(data)
+    return result
+
+
+# ---------------- AppHost initialization ----------------
+class AppHostArgs(msgspec.Struct):
+    """Args sent to the AppHost process."""
+
+    # ZMQ PULL address for receiving management commands
+    mgmt_addr: str
+    # ZMQ PUSH address for sending management responses
+    response_addr: str
+    # ZMQ PULL address for receiving kernel commands
+    cmd_addr: str
+    # ZMQ PUSH address for sending kernel output
+    stream_addr: str
+    # Notebook file path, for debug logs
+    file_path: str
+    log_level: int
+
+    def encode_json(self) -> bytes:
+        return msgspec.json.encode(self)
+
+    @classmethod
+    def decode_json(cls, buf: bytes) -> AppHostArgs:
+        return msgspec.json.decode(buf, type=cls)
+
+
+# ---------------- Kernel ----------------
+class Channel(enum.Enum):
+    """Command channels."""
+
+    CONTROL = b"control"
+    UI_ELEMENT = b"ui_element"
+    COMPLETION = b"completion"
+    INPUT = b"input"
+
+
+# Sentinel sent on the stream channel when a kernel thread exits.
+class KernelExited:
+    """Signals that a kernel thread has exited."""

marimo/_session/app_host/connection.py

@@ -0,0 +1,87 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""ZMQ connection management for IPC between an app host and its process."""
+
+from __future__ import annotations
+
+import dataclasses
+from typing import TYPE_CHECKING
+
+from marimo._config.settings import GLOBAL_SETTINGS
+from marimo._session.app_host.commands import AppHostArgs
+
+if TYPE_CHECKING:
+    import zmq
+
+_BIND_ADDR = "tcp://127.0.0.1"
+
+
+@dataclasses.dataclass
+class AppHostConnection:
+    """Manages all ZeroMQ sockets for an AppHost."""
+
+    context: zmq.Context[zmq.Socket[bytes]]
+
+    # PUSH — single frame: encode_mgmt_command(MgmtCommand)
+    mgmt: zmq.Socket[bytes]
+    # PULL — single frame: decode_mgmt_response(bytes) -> MgmtResponse
+    response: zmq.Socket[bytes]
+
+    # TODO(akshayka): Consider moving to something less fragile than pickle
+    # PUSH — 3-frame multipart: [session_id, channel, pickle(payload)]
+    cmd: zmq.Socket[bytes]
+    # PULL — 2-frame multipart: [session_id, pickle(KernelMessage | KernelExited)]
+    stream: zmq.Socket[bytes]
+
+    @classmethod
+    def create(
+        cls, file_path: str, log_level: int | None = None
+    ) -> tuple[AppHostConnection, AppHostArgs]:
+        """Bind all sockets, return connection and args for subprocess."""
+        import zmq
+
+        if log_level is None:
+            log_level = GLOBAL_SETTINGS.LOG_LEVEL
+
+        context = zmq.Context()
+        try:
+            mgmt = context.socket(zmq.PUSH)
+            mgmt_port = mgmt.bind_to_random_port(_BIND_ADDR)
+
+            response = context.socket(zmq.PULL)
+            response_port = response.bind_to_random_port(_BIND_ADDR)
+
+            cmd = context.socket(zmq.PUSH)
+            cmd_port = cmd.bind_to_random_port(_BIND_ADDR)
+
+            stream = context.socket(zmq.PULL)
+            stream_port = stream.bind_to_random_port(_BIND_ADDR)
+        except Exception:
+            context.destroy(linger=0)
+            raise
+
+        conn = cls(
+            context=context,
+            mgmt=mgmt,
+            response=response,
+            cmd=cmd,
+            stream=stream,
+        )
+
+        args = AppHostArgs(
+            mgmt_addr=f"{_BIND_ADDR}:{mgmt_port}",
+            response_addr=f"{_BIND_ADDR}:{response_port}",
+            cmd_addr=f"{_BIND_ADDR}:{cmd_port}",
+            stream_addr=f"{_BIND_ADDR}:{stream_port}",
+            file_path=file_path,
+            log_level=log_level,
+        )
+
+        return conn, args
+
+    def close(self) -> None:
+        """Close all sockets and destroy context."""
+        self.mgmt.close(linger=0)
+        self.response.close(linger=0)
+        self.cmd.close(linger=0)
+        self.stream.close(linger=0)
+        self.context.destroy(linger=0)