aws-sagemaker-marimo 0.2.0

Run marimo reactive notebooks on Amazon SageMaker Studio Lab and SageMaker Studio

marimo on Amazon SageMaker

Run marimo, the reactive Python notebook, on Amazon SageMaker Studio and Studio Lab.

---

⚡ One-Command Setup

For SageMaker Studio Lab (free, no AWS account required):

curl -fsSL https://raw.githubusercontent.com/scttfrdmn/aws-sagemaker-marimo/main/bootstrap.sh | bash

Then start marimo:

~/start-marimo.sh

📖 Full Bootstrap Guide | ⚙️ Manual Setup

---

⚠️ Known Limitation: WebSocket on SageMaker Studio Lab

marimo's home page loads but notebooks show blank cells or "connecting" status.

This is a known limitation of SageMaker Studio Lab's gateway/ALB infrastructure. HTTP proxying through jupyter-server-proxy works correctly — you can browse marimo's file list — but WebSocket connections (which marimo requires for cell execution) are dropped by the SageMaker gateway on /proxy/PORT/ paths. This affects all WebSocket-dependent proxied applications, not just marimo.

What works:

• ✅ marimo home page / file browser via /proxy/2718/
• ✅ HTTP API requests through the proxy
• ✅ jupyter-server-proxy 4.4.0 (conda default) — no downgrade needed

What doesn't work (without the shim):

• ❌ Interactive notebook editing (requires WebSocket)
• ❌ Cell execution and reactive updates (requires WebSocket)

Workaround included: This repo uses ws-sse-proxy to translate WebSocket to SSE, making marimo fully functional on Studio Lab. See WEBSOCKET-STATUS.md for details, or just run:

bash start-marimo-shim.sh
# Then access at /proxy/2719/

Tracking: marimo-jupyter-extension #8 and marimo #8060

---

🚀 Quick Start (5 Minutes)

Want to try marimo right now?

👉 Start with the Quick Start Guide - Get marimo running in 5 minutes on SageMaker Studio Lab (free!) or Studio.

📚 What's Included

This repository provides:

1. 📖 Complete Blog Post (~2000 words)

   • Deep dive into marimo's features
   • Why use marimo on SageMaker
   • Architecture overview
   • Deployment strategies
   • Best practices and troubleshooting

2. ⚡ Quick Start Guide

   • 5-minute setup for Studio Lab (free)
   • Easy installation for Studio
   • Sample notebooks
   • Troubleshooting tips

3. 🔧 Infrastructure as Code

   • terraform/ - Complete Terraform deployment
   • cdk/ - AWS CDK (Python) deployment
   • Lifecycle configurations
   • Sample notebooks

4. 🎓 Demo Notebook

   • Complete ML workflow
   • Interactive data exploration
   • Model training with reactive parameters
   • SageMaker integration examples

🎯 Choose Your Path

Path 1: Just Try It (Fastest)

Perfect for: Learning, experimenting, quick demos

1. Get free SageMaker Studio Lab account
2. Follow QUICKSTART.md
3. Try the sample notebook
4. Total time: ~10 minutes

Path 2: Manual Setup on Studio/Studio Lab

Perfect for: Individual users, existing Studio environment

1. Open SageMaker Studio or Studio Lab
2. Run pip install marimo jupyter-server-proxy
3. Start with marimo edit --host 0.0.0.0 --port 2718 --no-token --headless
4. See QUICKSTART.md for details
5. Note: On Studio Lab, WebSocket connections are blocked by the gateway — see known limitation

Path 3: Production Deployment

Perfect for: Teams, production workloads, persistent setup

1. Read the blog post for architecture understanding
2. Choose Terraform or CDK
3. Deploy with one command
4. Get automated, persistent marimo installation

💡 Why marimo?

Traditional Jupyter notebooks have well-known issues:

• ❌ Hidden state from out-of-order execution
• ❌ JSON format causes Git conflicts
• ❌ ~75% of notebooks on GitHub don't run
• ❌ Hard to reproduce research

marimo solves these problems:

• ✅ Reactive execution - cells auto-update when dependencies change
• ✅ Stored as pure Python - Git-friendly, executable as scripts
• ✅ No hidden state - deterministic, reproducible
• ✅ Interactive UI widgets - no callbacks needed
• ✅ Three tools in one - notebook, script, and web app

🏗️ Architecture

┌─────────────────────────────────────┐
│   SageMaker Studio / Studio Lab     │
│  ┌───────────────────────────────┐  │
│  │  JupyterLab Environment       │  │
│  │  ┌─────────────────────────┐  │  │
│  │  │ jupyter-server-proxy    │  │  │
│  │  │         ↓                │  │  │
│  │  │ marimo server (:2718)   │  │  │
│  │  └─────────────────────────┘  │  │
│  └───────────────────────────────┘  │
└─────────────────────────────────────┘

📦 Repository Structure

.
├── README.md                    # This file
├── QUICKSTART.md               # 5-minute setup guide
├── BOOTSTRAP.md                # One-command bootstrap guide
├── STUDIO-LAB-SETUP.md         # Automated Studio Lab setup
├── BADGES.md                   # Badge options for READMEs
├── WEBSOCKET-STATUS.md         # WebSocket proxy status & research
├── CONTRIBUTING.md             # Contribution guidelines
├── CHANGELOG.md                # Version history (Keep a Changelog)
├── LICENSE                     # MIT License
├── VERSION                     # Semantic version (0.1.0)
├── blog-post.md                # Full blog post (~2000 words)
├── sagemaker_ml_demo.py        # Complete demo notebook
├── bootstrap.sh                # One-command setup script
├── start-marimo-shim.sh        # Start marimo with WebSocket shim
├── studio-lab-setup.sh         # Setup script with conda env
├── terraform/                  # Terraform IaC (coming soon)
├── cdk/                        # AWS CDK IaC (coming soon)
└── notebooks/                  # Sample notebooks (coming soon)

🎓 Sample Notebooks

Quick Demo

import marimo as mo

# Interactive slider
slider = mo.ui.slider(0, 100, value=50)

# Automatically updates when slider changes!
result = slider.value ** 2
mo.md(f"Value: {slider.value}, Squared: {result}")

SageMaker Integration

import marimo as mo
import boto3

sagemaker = boto3.client('sagemaker')

# List training jobs
jobs = sagemaker.list_training_jobs(MaxResults=10)

# Interactive table
mo.ui.table(jobs['TrainingJobSummaries'])

See sagemaker_ml_demo.py for a complete, production-ready example.

🚢 Deployment Options

Option 1: Terraform

cd terraform
terraform init
terraform apply

Creates:

• SageMaker Studio Domain
• VPC and security groups
• IAM roles
• Lifecycle configuration for marimo
• S3 bucket for artifacts

Option 2: AWS CDK

cd cdk
pip install -r requirements.txt
cdk deploy

Same infrastructure as Terraform, using Python CDK constructs.

Option 3: Manual (Quickest)

See QUICKSTART.md - just pip install marimo and go!

💰 Cost Comparison

Option	Cost	Best For
Studio Lab	$0 (100% free)	Learning, small projects
Studio (manual)	~$0.05-2/hour	Individual use, testing
Studio (IaC)	~$1-5/hour	Teams, production

marimo's lightweight architecture means minimal overhead costs.

🔧 Maintenance

Updating marimo

Studio Lab / Manual:

pip install --upgrade marimo

With Lifecycle Config: Update the version in install-marimo.sh and redeploy lifecycle configuration.

Cleanup

Terraform:

terraform destroy

CDK:

cdk destroy

Manual: Just stop using it - no infrastructure to clean up!

🤝 Use Cases

marimo on SageMaker is perfect for:

• 🔬 Reproducible Research - Pure Python format, no hidden state
• 👥 Team Collaboration - Git-friendly, version-controlled notebooks
• 📊 Interactive Dashboards - Reactive UI updates, deploy as web apps
• 🚀 MLOps Pipelines - Run notebooks as scripts in CI/CD
• 🎓 Teaching & Demos - Predictable execution, professional output
• 🔍 Data Exploration - Interactive filtering and visualization

🆚 marimo vs Jupyter

When to use marimo:

• ✅ Building dashboards or interactive apps
• ✅ Need reproducible, version-controlled research
• ✅ Want reactive, automatic updates
• ✅ Creating reusable modules or pipelines
• ✅ Teaching or presenting (no hidden state issues)

When to use Jupyter:

• ✅ Quick ad-hoc exploration
• ✅ Team heavily invested in Jupyter ecosystem
• ✅ Need specific Jupyter extensions

Best practice: Use both! Convert between formats as needed with marimo convert.

❓ Troubleshooting

Common issues and solutions are in QUICKSTART.md.

Quick fixes:

• Can't access UI: Check proxy URL path
• Port in use: Use different port (--port 8889)
• Proxy not working: Run jupyter serverextension enable --py jupyter_server_proxy

🎯 Next Steps

1. ✅ Try the Quick Start (5 minutes)
2. ✅ Read the blog post for deep dive
3. ✅ Run the demo notebook
4. ✅ Convert your Jupyter notebooks: marimo convert notebook.ipynb
5. ✅ Deploy with infrastructure-as-code for production use

🌟 Features Showcase

Reactive Execution

# Change slider, everything updates automatically
slider = mo.ui.slider(0, 100)
filtered_data = data[data['value'] > slider.value]
plot = create_plot(filtered_data)  # Auto-updates!

Git-Friendly

# Clean diffs, no JSON
git diff notebook.py

# Run as script
python notebook.py

# Deploy as app
marimo run notebook.py

Interactive UI

# No callbacks needed!
dropdown = mo.ui.dropdown(['A', 'B', 'C'])
table = mo.ui.table(dataframe)
plot = mo.ui.plotly(figure)

📄 License

This repository: MIT License

marimo: Apache 2.0 License

🙏 Acknowledgments

• marimo team - for building an amazing reactive notebook platform
• AWS SageMaker team - for creating a flexible ML platform
• Community - for feedback and contributions

📬 Support

• Issues: Open an issue in this repository
• marimo Discord: https://marimo.io/discord
• AWS Support: https://aws.amazon.com/support/

---

📚 Documentation

• Quick Start Guide - Get running in 5 minutes
• Bootstrap Guide - One-command automated setup
• Studio Lab Setup - Persistent conda environment
• WebSocket Status - WebSocket limitation details
• Blog Post - Complete guide (~2000 words)
• Badge Options - Add badges to your own projects
• Contributing - How to contribute
• Changelog - Version history

📝 Project Info

• Version: 0.1.0 (Semantic Versioning)
• License: MIT
• Copyright: © 2026 Scott Friedman
• Changelog: Keep a Changelog format

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

To contribute:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

See CHANGELOG.md for version history.

---

Ready to get started?

👉 One command: curl -fsSL https://raw.githubusercontent.com/scttfrdmn/aws-sagemaker-marimo/main/bootstrap.sh | bash

👉 Or manual: QUICKSTART.md

👉 Deep dive: Full blog post

Happy reactive coding! 🚀