fix: isolation when running multiple notebooks in an app server

[akshayka]

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.

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.

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

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
marimo-docs	Error		Mar 12, 2026 9:54pm

[mscolnick]

I'm starting to think maybe pyzmq should be a required dep. at least in recommended, if not already.