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.

docs: outline deployment with skypilot (#7400)

Dylan Madisettie845bde4724d
diff --git a/docs/guides/deploying/deploying_kubernetes.md b/docs/guides/deploying/deploying_kubernetes.md
new file mode 100644
index 0000000000..6ddfc5c260
--- /dev/null
+++ b/docs/guides/deploying/deploying_kubernetes.md
@@ -0,0 +1,246 @@
+# Deploy with Kubernetes
+
+The [marimo-operator](https://github.com/marimo-team/marimo-operator) is a
+Kubernetes operator that manages marimo notebook deployments. It handles
+persistent storage, resource allocation, and lifecycle management for notebooks
+running on Kubernetes clusters.
+
+!!! tip "Quick start"
+ For the fastest path to running notebooks on Kubernetes, use the `kubectl-marimo` CLI plugin.
+ It handles manifest generation, port forwarding, and file synchronization automatically.
+
+## Prerequisites
+
+- Kubernetes cluster (v1.25+)
+- `kubectl` configured with cluster access
+- Python 3.9+ with `pip` or `uv`
+- Cluster admin permissions (for initial operator installation)
+
+## Install the operator
+
+Install the marimo operator on your cluster:
+
+```bash
+kubectl apply -f https://raw.githubusercontent.com/marimo-team/marimo-operator/main/deploy/install.yaml
+```
+
+Verify the operator is running:
+
+```bash
+kubectl get pods -n marimo-operator-system
+```
+
+The output should show the operator pod running:
+
+```
+NAME READY STATUS RESTARTS AGE
+marimo-operator-controller-manager-xxxxx 1/1 Running 0 30s
+```
+
+## Quickstart with kubectl-marimo
+
+The `kubectl-marimo` plugin is the recommended way to deploy notebooks from local files.
+
+### Install the plugin
+
+```bash
+# With uv (recommended)
+uv tool install kubectl-marimo
+
+# Or with pip
+pip install kubectl-marimo
+```
+
+### Run a notebook
+
+Edit a notebook interactively on the cluster:
+
+```bash
+kubectl marimo edit notebook.py
+```
+
+This command:
+
+1. Uploads your notebook to the cluster
+2. Creates persistent storage for your changes
+3. Starts the marimo server
+4. Sets up port forwarding to your local machine
+
+When you stop the command (`Ctrl+C`), it syncs changes back to your local file and tears down the pod.
+
+To run a notebook as a read-only application:
+
+```bash
+kubectl marimo run notebook.py
+```
+
+### Configure resources
+
+Configure your notebook's Kubernetes resources using frontmatter in your notebook file.
+
+**Python notebooks (.py):**
+
+```python
+# /// script
+# requires-python = ">=3.12"
+# dependencies = ["marimo", "pandas", "numpy"]
+#
+# [tool.marimo.k8s]
+# image = "ghcr.io/marimo-team/marimo:latest"
+# storage = "5Gi"
+# [tool.marimo.k8s.resources]
+# requests.cpu = "500m"
+# requests.memory = "2Gi"
+# limits.cpu = "2"
+# limits.memory = "8Gi"
+# ///
+```
+
+**Markdown notebooks (.md):**
+
+```yaml
+---
+title: my-analysis
+image: ghcr.io/marimo-team/marimo:latest
+storage: 5Gi
+resources:
+ requests:
+ cpu: "500m"
+ memory: "2Gi"
+ limits:
+ cpu: "2"
+ memory: "8Gi"
+---
+```
+
+### Configuration fields
+
+| Field | Description | Default |
+|-------|-------------|---------|
+| `title` | Resource name in Kubernetes | filename |
+| `image` | Container image | `ghcr.io/marimo-team/marimo:latest` |
+| `port` | Server port | 2718 |
+| `storage` | Persistent volume size | none (ephemeral) |
+| `resources` | CPU, memory, GPU requests/limits | none |
+| `auth` | Set to `"none"` to disable authentication | token auth |
+| `env` | Environment variables | none |
+
+### Manage deployments
+
+```bash
+# Sync changes back to local file
+kubectl marimo sync notebook.py
+
+# Delete deployment
+kubectl marimo delete notebook.py
+
+# List active deployments
+kubectl marimo status
+```
+
+## GPU workloads
+
+Specify GPU resources in your notebook frontmatter:
+
+**Python notebooks:**
+
+```python
+# /// script
+# [tool.marimo.k8s.resources]
+# limits."nvidia.com/gpu" = 1
+# ///
+```
+
+**Markdown notebooks:**
+
+```yaml
+---
+resources:
+ limits:
+ nvidia.com/gpu: 1
+---
+```
+
+The Kubernetes scheduler will place your notebook on an appropriate GPU node.
+
+## Cloud storage integration
+
+The marimo operator supports mounting cloud storage (S3-compatible buckets, SSHFS, rsync) in your notebooks. See the [operator documentation](https://github.com/marimo-team/marimo-operator) for mount configuration details.
+
+## Deploy with manifests
+
+For advanced users who need fine-grained control, you can create `MarimoNotebook` resources directly.
+
+### Basic manifest
+
+```yaml
+apiVersion: marimo.io/v1alpha1
+kind: MarimoNotebook
+metadata:
+ name: my-notebook
+spec:
+ source: https://github.com/marimo-team/examples.git
+ storage:
+ size: 1Gi
+```
+
+Apply the manifest:
+
+```bash
+kubectl apply -f notebook.yaml
+```
+
+Check the status:
+
+```bash
+kubectl get marimos
+```
+
+Port forward to access:
+
+```bash
+kubectl port-forward svc/my-notebook 2718:2718
+```
+
+### With GPU and sidecars
+
+```yaml
+apiVersion: marimo.io/v1alpha1
+kind: MarimoNotebook
+metadata:
+ name: gpu-notebook
+spec:
+ source: https://github.com/your-org/notebooks.git
+ storage:
+ size: 5Gi
+ resources:
+ requests:
+ memory: 4Gi
+ limits:
+ memory: 16Gi
+ nvidia.com/gpu: 1
+ sidecars:
+ - name: ssh
+ image: linuxserver/openssh-server:latest
+ exposePort: 2222
+```
+
+## Clean up
+
+```bash
+# Via plugin (syncs changes first)
+kubectl marimo delete notebook.py
+
+# Via kubectl (does not sync)
+kubectl delete marimo my-notebook
+```
+
+!!! warning "Sync before deleting"
+ Using `kubectl delete` directly will **not** sync your changes back to your local file. Use `kubectl marimo delete` to automatically sync before deletion.
+
+## Learn more
+
+- [marimo-operator on GitHub](https://github.com/marimo-team/marimo-operator)
+- [SkyPilot deployment](./deploying_skypilot.md) - For multi-cloud VM deployment without Kubernetes
+- [Docker deployment](./deploying_docker.md) - For container basics
+- [Inlining dependencies](../package_management/inlining_dependencies.md) - For reproducible notebooks
diff --git a/docs/guides/deploying/deploying_skypilot.md b/docs/guides/deploying/deploying_skypilot.md
new file mode 100644
index 0000000000..ba2a91201d
--- /dev/null
+++ b/docs/guides/deploying/deploying_skypilot.md
@@ -0,0 +1,162 @@
+# Deploy with SkyPilot
+
+[SkyPilot](https://skypilot.readthedocs.io/) is an open-source framework that allows you to run workloads on any cloud (AWS, GCP, Azure, Coreweave, and more) with a unified interface. It's particularly well-suited for running marimo notebooks on GPU instances for machine learning and data science workloads.
+
+!!! tip "New to SkyPilot?"
+ If you haven't used SkyPilot before, start with their [getting started guide](https://skypilot.readthedocs.io/en/latest/getting-started/installation.html) to install SkyPilot and set up cloud credentials.
+
+marimo notebooks work exceptionally well with SkyPilot because they are stored as pure Python scripts and can be run both interactively and as batch jobs. With marimo's built-in `uv` integration, your notebooks are fully reproducible across different environments.
+
+## Interactive Development
+
+For interactive development with marimo on a SkyPilot cluster, you can launch a cluster and connect to it with SSH port forwarding.
+
+### Launch a cluster
+
+First, create a cluster with your desired resources, ([see the guide](https://docs.skypilot.co/en/latest/getting-started/installation.html#set-up-kubernetes-or-clouds)):
+
+```bash
+sky launch --gpus V100:1 -c dev
+```
+
+### Connect with port forwarding
+
+Connect to the cluster and forward the port that marimo will use:
+
+```bash
+ssh -L 8080:localhost:8080 dev
+```
+
+### Start marimo
+
+Inside the cluster, install `uv` and start marimo with the `--sandbox` flag for isolated dependencies:
+
+```bash
+pip install uv
+uvx marimo edit --sandbox demo.py --port 8080 --token-password=supersecret
+```
+
+!!! note "Sandboxed environments"
+ The `uvx` command runs marimo without installing it in your environment, and the `--sandbox` flag ensures that notebook dependencies are installed in a separate environment. This makes your development fully reproducible and isolated. See [inlining dependencies](../package_management/inlining_dependencies.md) for more on creating reproducible notebooks.
+
+You can now access your marimo notebook at `localhost:8080` in your local browser and authenticate with the password you set.
+
+## Running as Batch Jobs
+
+Because marimo notebooks are Python scripts, they can be submitted as managed SkyPilot jobs. This is useful for training models, running experiments, or processing data without needing an interactive session.
+
+### Create a job-compatible notebook
+
+marimo notebooks can accept command-line arguments using `mo.cli_args()`. Here's an example notebook that demonstrates this:
+
+```python
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+# "marimo",
+# ]
+# ///
+
+import marimo
+
+__generated_with = "0.18.1"
+app = marimo.App()
+
+
+def _():
+ import marimo as mo
+ return (mo,)
+
+
+def _(mo):
+ # Parse command-line arguments
+ args = mo.cli_args()
+ print(f"Running with arguments: {args}")
+ return
+
+
+if __name__ == "__main__":
+ app.run()
+```
+
+You can test this locally:
+
+```bash
+uv run demo.py --hello world --demo works --lr 0.01
+```
+
+This will print:
+
+```
+{'hello': 'world', 'demo': 'works', 'lr': '0.01'}
+```
+
+### Create a SkyPilot job configuration
+
+Create a YAML file to configure your job:
+
+```yaml
+# marimo-job.yaml
+name: marimo-demo
+
+# Specify resources for this job
+resources:
+ accelerators: V100:1
+
+# Point to the folder containing your marimo notebook
+workdir: .
+
+# Environment variables (e.g., for W&B, HuggingFace)
+envs:
+ WANDB_API_KEY: ${WANDB_API_KEY}
+
+# Install uv
+setup: pip install uv
+
+# Run the notebook with arguments
+run: uv run demo.py --hello world --demo works --lr 0.01
+```
+
+### Launch the job
+
+Submit the job to SkyPilot:
+
+```bash
+sky jobs launch -n marimo-demo marimo-job.yaml
+```
+
+SkyPilot will provision cloud resources, run your notebook, and automatically tear down the resources after the job completes (with a configurable idle timeout).
+
+### Monitor job progress
+
+You can monitor your job using:
+
+```bash
+# View logs
+sky jobs logs marimo-demo
+
+# Check job status
+sky jobs queue
+
+# Launch dashboard
+sky jobs dashboard
+```
+
+## Benefits of marimo + SkyPilot
+
+- **Reproducible**: marimo's `uv` integration ensures consistent dependency management
+- **Cost-effective**: SkyPilot finds the cheapest resources across clouds and automatically terminates idle instances
+- **Flexible**: Use the same notebook interactively or as a batch job
+- **Cloud-agnostic**: Run on any cloud provider without changing your code
+
+## Multi-cloud setup
+
+SkyPilot supports AWS, GCP, Azure, Lambda Labs, and more. See their [cloud setup guide](https://skypilot.readthedocs.io/en/latest/getting-started/installation.html#cloud-account-setup) to configure credentials for your preferred cloud providers.
+
+## Learn more
+
+- [SkyPilot documentation](https://skypilot.readthedocs.io/)
+- [SkyPilot managed jobs guide](https://skypilot.readthedocs.io/en/latest/examples/managed-jobs.html)
+- [marimo CLI arguments](../../api/cli_args.md)
diff --git a/docs/guides/deploying/index.md b/docs/guides/deploying/index.md
index 344ca02722..59d4a212a6 100644
--- a/docs/guides/deploying/index.md
+++ b/docs/guides/deploying/index.md
@@ -26,8 +26,9 @@ Here are a few ways to deploy an edit server on a remote instance:
1. With [ssh-port forwarding](../../faq.md#faq-remote), using `marimo edit --headless`.
2. Via docker and our [prebuilt containers](prebuilt_containers.md).
3. Via a deployment service [such as Railway](deploying_railway.md).
-4. [On Slurm/HPC clusters](deploying_slurm.md).
-5. [Behind JupyterHub](../../faq.md#faq-jupyter-hub).
+4. Via [SkyPilot](deploying_skypilot.md).
+5. [On Slurm/HPC clusters](deploying_slurm.md).
+6. [Behind JupyterHub](../../faq.md#faq-jupyter-hub).
## Deploying as read-only apps
diff --git a/mkdocs.yml b/mkdocs.yml
index 0dc49a284b..bd99186cb4 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -146,6 +146,9 @@ nav:
- Deploy notebooks: guides/deploying/index.md
- Authentication: guides/deploying/authentication.md
- Docker: guides/deploying/deploying_docker.md
+ - Kubernetes: guides/deploying/deploying_kubernetes.md
+ - SkyPilot: guides/deploying/deploying_skypilot.md
+ - Slurm: guides/deploying/deploying_slurm.md
- HuggingFace: guides/deploying/deploying_hugging_face.md
- Public gallery: guides/deploying/deploying_public_gallery.md
- Railway: guides/deploying/deploying_railway.md