kubectl-marimo 0.2.1

kubectl plugin for deploying marimo notebooks to Kubernetes

kubectl-marimo

Deploy marimo notebooks to Kubernetes.

Installation

# With uv (recommended)
uv tool install kubectl-marimo

# With uvx (no install)
uvx kubectl-marimo edit notebook.py

# With pip
pip install kubectl-marimo

Quick Start

# Edit a notebook interactively
kubectl marimo edit notebook.py

# Run as read-only app
kubectl marimo run notebook.py

# With cloud storage
kubectl marimo edit --source=cw://my-bucket/data notebook.py

# Sync changes back
kubectl marimo sync notebook.py

# Delete deployment
kubectl marimo delete notebook.py

# List active deployments
kubectl marimo status

Commands

edit

Create or edit notebooks in the cluster (interactive mode).

kubectl marimo edit [OPTIONS] [FILE]

Options:

• -n, --namespace - Kubernetes namespace (default: "default")
• --source - Data source URI (cw://, sshfs://, rsync://)
• --dry-run - Print YAML without applying
• -f, --force - Overwrite without prompting

Examples:

# Edit existing notebook
kubectl marimo edit notebook.py

# Edit with S3 data mounted
kubectl marimo edit --source=cw://bucket/data notebook.py

# Edit in staging namespace
kubectl marimo edit -n staging notebook.py

run

Run a notebook as a read-only application.

kubectl marimo run [OPTIONS] FILE

Options: Same as edit

Examples:

# Run notebook as app
kubectl marimo run dashboard.py

# Run with data source
kubectl marimo run --source=cw://bucket/reports dashboard.py

sync

Pull changes from pod back to local file.

kubectl marimo sync [OPTIONS] FILE

Options:

• -n, --namespace - Kubernetes namespace
• -f, --force - Overwrite local file without prompting

delete

Delete notebook deployment from cluster.

kubectl marimo delete [OPTIONS] FILE

Options:

• -n, --namespace - Kubernetes namespace
• --delete-pvc - Also delete PersistentVolumeClaim (PVC is preserved by default)
• --no-sync - Delete without syncing changes back

status

List active notebook deployments.

kubectl marimo status [DIRECTORY]

Configuration

Configure deployments via frontmatter in your notebook.

Markdown (.md)

---
title: my-analysis
image: ghcr.io/marimo-team/marimo:latest
storage: 5Gi
env:
  DEBUG: "true"
  API_KEY:
    secret: my-secret
    key: api-key
mounts:
  - cw://my-bucket/data
---

Python (.py)

# /// script
# dependencies = ["marimo", "pandas"]
# ///
# [tool.marimo.k8s]
# image = "ghcr.io/marimo-team/marimo:latest"
# storage = "5Gi"
#
# [tool.marimo.k8s.env]
# DEBUG = "true"

Frontmatter Fields

Field	Description	Default
title	Resource name	filename
image	Container image	ghcr.io/marimo-team/marimo:latest
port	Server port	2718
storage	PVC size	none (ephemeral)
auth	Set to "none" to disable	token auth
env	Environment variables	none
mounts	Data source URIs	none

Environment Variables

Inline values:

env:
  DEBUG: "true"
  LOG_LEVEL: "info"

From Kubernetes secrets:

env:
  API_KEY:
    secret: my-secret
    key: api-key
  DB_PASSWORD:
    secret: db-credentials
    key: password

Mount URIs

Scheme	Description	Example
cw://	CoreWeave Object Storage	cw://bucket/path
sshfs://	SSH filesystem mount	sshfs://user@host:/path
rsync://	Local directory sync	rsync://./data:/notebooks

Local rsync:// URIs sync a directory to the pod via kubectl cp. Remote URIs (rsync://user@host:/path) create a sidecar for continuous sync.

Requirements

• Kubernetes cluster with marimo-operator installed
• kubectl configured to access the cluster