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.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
docs: outline deployment with skypilot (#7400)
Dylan Madisettie845bde4724d
diff --git a/docs/guides/deploying/deploying_kubernetes.md b/docs/guides/deploying/deploying_kubernetes.mdnew file mode 100644index 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 notebooksdiff --git a/docs/guides/deploying/deploying_skypilot.md b/docs/guides/deploying/deploying_skypilot.mdnew file mode 100644index 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.mdindex 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 appsdiff --git a/mkdocs.yml b/mkdocs.ymlindex 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