Add Marimo Notebook Support

[sephib]

Checks

• I have searched the existing issues.
• My request is related to one of the components in the kubeflow/notebooks repository.

Motivation

Kubeflow Notebooks currently supports JupyterLab, RStudio, and VS Code (code-server). I propose adding Marimo as a fourth notebook type to address critical gaps in the ML/AI development workflow.

What is Marimo?

Marimo is an open-source reactive Python notebook that addresses several pain points in traditional notebook development:

• Reactive Execution: Cells automatically re-execute when dependencies change, eliminating stale outputs and ensuring state consistency
• Git-Friendly Storage: Notebooks are stored as pure Python (.py) files, not JSON - enabling meaningful code reviews and clean git diffs
• Reproducibility by Design: No hidden state, no out-of-order execution - notebooks are deterministic and reproducible
• Production Ready: Notebooks can be executed as scripts or deployed as web apps without modification

Why Add Marimo?

Adding Marimo fills critical gaps for teams who:

• Struggle with version control: Jupyter's JSON format creates merge conflicts and unreadable diffs
• Face reproducibility issues: Out-of-order cell execution leads to "works on my machine" problems
• Want ML engineering best practices: Need to apply proper code review and CI/CD to notebook-based development
• Need seamless notebook-to-production: Jupyter notebooks require conversion; Marimo notebooks are already Python scripts

Key Benefits:

For Users:

• Git diffs show actual code changes, not JSON structure
• Automatic reactive execution ensures outputs match current code
• Notebooks integrate directly with CI/CD pipelines
• No more debugging hidden state issues

Implementation

Following the pattern from #904 (RStudio/Code-Server WorkspaceKind samples), implementation would include:

Files Required:

1. marimo_v1beta1_workspacekind.yaml in workspaces/controller/manifests/kustomize/samples/
2. Update kustomization.yaml to include the new resource

Technical Specifications:

Marimo WorkspaceKind:

• Image: ghcr.io/kubeflow/kubeflow/notebook-servers/marimo:v1.0.0 (to be built)
• Port: 8888 (Marimo default)
• Path Handling: removePathPrefix: false (Marimo handles base paths via environment variables)
• Protocol: HTTP/WebSocket for reactive updates

Container Image Details:

• Base: Python 3.X+ TBD
• Installation: uv add marimo
• Entry point: marimo edit --host 0.0.0.0 --port 8888
• ML libraries: numpy, pandas, scikit-learn, etc.
• Authentication: Integrates with Kubeflow RBAC

Shared Configuration (similar to JupyterLab/RStudio/Code-Server):

• default-editor ServiceAccount
• dshm volume (/dev/shm) for shared memory
• Activity probe: exec with exit 0 (until proper probes are developed)
• Default pod config: small_cpu (1 CPU, 2Gi RAM)

Sample WorkspaceKind YAML Structure:

apiVersion: kubeflow.org/v1beta1
kind: WorkspaceKind
metadata:
  name: marimo
spec:
  displayName: Marimo
  description: Reactive Python notebooks with git-friendly storage
  podConfig:
    spec:
      serviceAccountName: default-editor
      containers:
        - name: marimo
          image: ghcr.io/kubeflow/kubeflow/notebook-servers/marimo:v1.0.0
          ports:
            - containerPort: 8888
              name: notebook-port
              protocol: TCP
          env:
            - name: MARIMO_HOSTNAME
              value: "0.0.0.0"
            - name: MARIMO_PORT
              value: "8888"
          volumeMounts:
            - mountPath: /dev/shm
              name: dshm
            - mountPath: /home/jovyan
              name: workspace
          resources:
            requests:
              cpu: "1"
              memory: "2Gi"
      volumes:
        - name: dshm
          emptyDir:
            medium: Memory
  web:
    port: 8888
    path: "/"
    removePathPrefix: false
  activityProbe:
    exec:
      command: ["sh", "-c", "exit 0"]
    periodSeconds: 5

Compatibility:

• ✅ Uses same RBAC model as existing notebook types
• ✅ Integrates with Kubeflow Profiles for multi-tenancy
• ✅ Respects namespace resource quotas
• ✅ Compatible with existing PVC infrastructure
• ✅ Works with current networking/ingress setup

Are you willing & able to help?

• I am able to submit a PR!
• I can help test the feature!
• I can provide documentation and examples

Additional Context:

Full proposal document with detailed analysis, risk assessment, and success metrics is available upon request. This follows the same pattern as the recently-merged RStudio/Code-Server support (PR #906), demonstrating feasibility and community acceptance of expanding notebook type options.

References:

• Marimo: https://marimo.io/
• Marimo GitHub: https://github.com/marimo-team/marimo
• Marimo Docs: https://docs.marimo.io/
• Related PR: feat: update WorkspaceKind samples, add codeserver and rstudio #906 (RStudio/Code-Server WorkspaceKind)

[christian-heusel]

Hey, thanks for proposing this addition! 🤗

From my side I don't see any issue in adding marimo to the WSK samples, however the idea really is that those are samples, it's not a requirement for support, i.e. cluster admins can add arbitrarily differnt WSK types to the clusters that they maintain. 😄

Would you be interested in coming up with a contribution for this? Also is this both about notebooks v1 and notebooks v2? 😃

[sephib]

Yes - I'm interested .

1. Can you point me to a similar PR?
2. I thought only for v2, but if you think it is valuable also for v1 we can add it at a second stage.

@christian-heusel please advise

[christian-heusel]

Did you already have success adding Marimo support in a downstream image (outside of our examples)? 🤗

1. You can find the examples and instructions in how to build / add new images here (notebooks v2 currently just re-uses these images in the WSK samples): https://github.com/kubeflow/notebooks/tree/notebooks-v1/components/example-notebook-servers
2. I'll perhaps need to revise on my previous statement: Most likely the Working Group will not be able to maintain an ever growing collection of images, we'll need to think about a way of how those can be referenced into a community maintained or how the overall setup could look like 🤔

[sephib]

1. THx for the reference.
2. Please update once you have reconsidered the strategy - so the example will be able to be incorporated into a relevant repo.