Run marimo notebooks on CKS

Documentation Index

Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt

Use this file to discover all available pages before exploring further.

1. Install the marimo operator on your CKS cluster (for cluster administrators)
2. Run notebooks with the CLI plugin (recommended for researchers)
3. Connect to CoreWeave Object Storage to access data from your notebooks
4. Deploy with manifests for advanced configuration

​

Install the marimo operator

1. Install the operator:
   $ kubectl apply -f https://raw.githubusercontent.com/marimo-team/marimo-operator/main/deploy/install.yaml
   
2. Verify the operator is running:
   $ kubectl get pods -n marimo-operator-system
   
   The output should show the operator pod in a Running state:
   NAME                                        READY   STATUS    RESTARTS   AGE
   marimo-operator-controller-manager-xxxxx    1/1     Running   0          30s
   

​

Install the marimo CLI plugin

1. Install kubectl-marimo:
   # With uv (recommended)
   $ uv tool install kubectl-marimo
   
   # Or with pip
   $ pip install kubectl-marimo
   

​

Run a marimo notebook on CKS

CPU notebook

$ curl -O https://raw.githubusercontent.com/marimo-team/marimo-operator/main/plugin/examples/getting-started.py
$ kubectl marimo edit getting-started.py

GPU notebook

$ curl -O https://raw.githubusercontent.com/marimo-team/marimo-operator/main/plugin/examples/gpu-getting-started.py
$ kubectl marimo edit gpu-getting-started.py

1. Run and edit a notebook interactively by running the following command:
   $ kubectl marimo edit EXAMPLE_NOTEBOOK.py
   
   • Note: Replace EXAMPLE_NOTEBOOK.py with the path to a marimo notebook. If you don’t have a marimo notebook, you can create a file with a .py extension to use as a starting point. You can also use one of the pre-written notebooks mentioned above, such as the CPU or GPU notebook.
   This command does the following:
   • Uploads your notebook to the cluster
   • Creates persistent storage for your changes
   • Starts the marimo server
   • Provides a URL where you can access your notebook. Your notebook opens at http://localhost:<port>, which runs until you close the connection with ctrl-C.
   After closing the connection with ctrl-C and selecting to delete the pod, the plugin:
   • Syncs changes you made to your notebook back to your local machine
   • Tears down your pod
2. To edit a notebook without storage sync and management, run the following command:
   $ kubectl marimo edit --headless notebook.py
   
   To run a notebook as a read-only application (useful for dashboards), use kubectl marimo run --headless notebook.py instead.

​

Specifying resources

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

---
title: my-analysis
image: ghcr.io/marimo-team/marimo:latest
storage: 5Gi
mounts:
  - cw://[BUCKET-NAME]/data
env:
  DEBUG: "true"
---

​

Configuration fields

​

Resource requests and limits

# /// script
# [tool.marimo.k8s.resources]
# requests.cpu = "500m"
# requests.memory = "2Gi"
# limits.cpu = "2"
# limits.memory = "8Gi"
# limits."nvidia.com/gpu" = 1
# ///

---
resources:
  requests:
    cpu: "500m"
    memory: "2Gi"
  limits:
    cpu: "2"
    memory: "8Gi"
    nvidia.com/gpu: 1
---

• GPU workloads. For GPU workloads on CoreWeave, specifying nvidia.com/gpu in limits is typically sufficient. The scheduler will place your notebook on an appropriate GPU Node. For advanced scheduling (specific GPU types, Node affinity), use manifest-based deployment.
• CRD information. For the full CRD specification including advanced features like podOverrides, sidecars, and custom authentication, see the marimo-operator documentation.

​

Mount URI schemes

​

Local and bi-directional syncing

​

Connect to CoreWeave AI Object Storage

1. Login to the CoreWeave Intelligent CLI to use cwic commands:
   $ cwic auth login
   
   The following prompt appears and a browser opens the CoreWeave Console:
   Opening browser for authentication...
   Please visit: https://console.coreweave.com/tokens
   Please enter the token from the browser:
   
2. In the Console, create a new token by selecting Create Token and provide a name and expiration.
3. Paste the token secret into the cwic prompt here:
   Please enter the token from the browser:
   
4. Use cwic to create an access token for creating AI Object Storage buckets:
   $ cwic cwobject token create --name TOKEN_NAME --duration Permanent
   
   • Note: Replace TOKEN_NAME with your token name, for example, marimo-bucket-token.
   • Save the Access Key ID and Secret Key from the output.
5. Configure your local AI Object Storage credentials (one-time setup). We’re creating an .s3cfg file because cwic uses S3cmd for creating buckets.
   $ cat >> ~/.s3cfg << EOF
   [marimo]
   access_key = CWXXXXXXXXXX
   secret_key = cwXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   host_base = cwobject.com
   host_bucket = %(bucket)s.cwobject.com
   use_https = True
   bucket_location = AVAILABILITY_ZONE
   EOF
   
   • Note: Replace the access_key and secret_key values with your actual Access Key ID and Secret Key. Replace AVAILABILITY_ZONE with the your zone, for example, US-EAST-04A.
6. Create a bucket.
   $ cwic cwobject mb BUCKET_NAME
   
   • Note: Replace BUCKET_NAME with your bucket name, for example, my-notebook-data.
7. Create a file and add it to the bucket:
   $ touch some-data.txt
   $ s3cmd put ./some-data.txt s3://BUCKET_NAME/
   
   • Note: Replace BUCKET_NAME with your bucket name.
8. Deploy with storage mounted:
   $ kubectl marimo edit --source=cw://BUCKET_NAME NOTEBOOK_NAME.py
   
   • Note: Replace BUCKET_NAME and NOTEBOOK_NAME.py with the names of your bucket and notebook.
   The plugin automatically creates the Kubernetes secret from your ~/.s3cfg file - no manual kubectl create secret required.
9. Access your data in the notebook: Files are mounted at /home/marimo/notebooks/mounts/cw-0/: In the marimo notebook, access the mounted storage from the files menu under mounts > cw-0: You can also add this script to the notebook as an example of accessing the mounted storage:
   import os
   
   mount_path = "/home/marimo/notebooks/mounts/cw-0"
   
   # List files in the bucket
   files = os.listdir(mount_path)
   print(f"Files: {files}")
   
   The mount supports full read/write access. Any files you create or modify in the mount directory are saved to your S3-compatible bucket.

​

Manually syncing and managing deployments

kubectl marimo sync NOTEBOOK.py

• Note: Replace NOTEBOOK.py with your notebook name.

kubectl marimo delete NOTEBOOK.py

• Note: Replace NOTEBOOK.py with your notebook name.

kubectl marimo status

​

CLI plugin reference

​

Commands

​

edit

kubectl marimo edit [OPTIONS] FILE

kubectl marimo edit notebook.py

kubectl marimo edit --source=cw://[BUCKET-NAME]/data notebook.py

kubectl marimo edit -n staging --headless notebook.py

​

run

kubectl marimo run [OPTIONS] FILE

​

sync

kubectl marimo sync [OPTIONS] FILE

​

delete

kubectl marimo delete [OPTIONS] FILE

​

status

kubectl marimo status

​

Deploy with manifests

​

Basic manifest

1. Create a file named notebook.yaml:
   notebook.yaml

   apiVersion: marimo.io/v1alpha1
   kind: MarimoNotebook
   metadata:
     name: my-notebook
   spec:
     source: https://github.com/marimo-team/examples.git # Must be a valid .git repository path.
     storage:
       size: 1Gi
   
2. Apply the manifest:
   $ kubectl apply -f notebook.yaml
   
3. Check the status:
   $ kubectl get marimos
   
   The output shows your notebook and its status:
   NAME          PHASE     URL                           AGE
   my-notebook   Running   http://my-notebook:2718       45s
   
4. To access the notebook, set up port forwarding:
   $ kubectl port-forward service/my-notebook 2718:2718
   
5. Get the URL with the access token by getting the Pod’s logs:
   $ kubectl logs MARIMO_NAME
   
   • Note: Replace MARIMO_NAME with the manifest name.
6. Copy the URL with the access token and paste it into your browser. You should now see the notebook defined the manifest’s source field.

​

With storage (manual setup)

1. Create the credentials secret:
   $ kubectl create secret generic cw-credentials \
     --from-literal=AWS_ACCESS_KEY_ID=CWXXXXXXXXXX \
     --from-literal=AWS_SECRET_ACCESS_KEY=cwXXXXXXXXXXXXXX
   
2. Add mounts to your manifest:
   apiVersion: marimo.io/v1alpha1
   kind: MarimoNotebook
   metadata:
     name: my-notebook
   spec:
     source: https://github.com/marimo-team/examples.git # Must be a valid .git repository path.
     storage:
       size: 5Gi
     mounts:
       - cw://my-notebook-data
   

​

With GPU resources

apiVersion: marimo.io/v1alpha1
kind: MarimoNotebook
metadata:
  name: gpu-notebook
spec:
  source: https://github.com/your-org/notebooks.git # Must be a valid .git repository path.
  storage:
    size: 5Gi
  resources:
    requests:
      cpu: "500m"
      memory: 4Gi
    limits:
      cpu: "4"
      memory: 16Gi
      nvidia.com/gpu: 1

apiVersion: marimo.io/v1alpha1
kind: MarimoNotebook
metadata:
  name: gpu-notebook
spec:
  source: https://github.com/your-org/notebooks.git # Must be a valid .git repository path.
  storage:
    size: 5Gi
  resources:
    requests:
      cpu: "500m"
      memory: 4Gi
    limits:
      cpu: "4"
      memory: 16Gi
      nvidia.com/gpu: 1
  podOverrides:
    nodeSelector:
      gpu.nvidia.com/class: Quadro_RTX_4000
    tolerations:
      - key: nvidia.com/gpu
        operator: Exists
        effect: NoSchedule

​

Clean up

kubectl delete marimo MARIMO_NAME

• Note: Replace MARIMO_NAME with the name in the manifest.

​

Additional resources

• marimo documentation
• marimo-operator on GitHub
• CoreWeave Object Storage