{"id":51459803,"url":"https://github.com/scttfrdmn/aws-marimo-sagemaker","last_synced_at":"2026-07-06T04:30:37.657Z","repository":{"id":336371071,"uuid":"1134750342","full_name":"scttfrdmn/aws-marimo-sagemaker","owner":"scttfrdmn","description":"Run marimo reactive Python notebooks on AWS SageMaker Studio and Studio Lab — reproducible, git-friendly, zero hidden state","archived":false,"fork":false,"pushed_at":"2026-03-21T02:23:06.000Z","size":112,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-21T09:00:24.374Z","etag":null,"topics":["amazon-sagemaker-lab","aws","data-science","jupyter","jupyter-alternative","machine-learning","marimo","notebooks","python","reactive-programming","reproducible-research","sagemaker","sagemaker-studio"],"latest_commit_sha":null,"homepage":"https://github.com/scttfrdmn/aws-marimo","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/scttfrdmn.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-15T06:36:06.000Z","updated_at":"2026-03-21T02:23:09.000Z","dependencies_parsed_at":null,"dependency_job_id":"d4543176-8a42-4672-a7fd-85e1808e18a8","html_url":"https://github.com/scttfrdmn/aws-marimo-sagemaker","commit_stats":null,"previous_names":["scttfrdmn/aws-marimo"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/scttfrdmn/aws-marimo-sagemaker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scttfrdmn%2Faws-marimo-sagemaker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scttfrdmn%2Faws-marimo-sagemaker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scttfrdmn%2Faws-marimo-sagemaker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scttfrdmn%2Faws-marimo-sagemaker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scttfrdmn","download_url":"https://codeload.github.com/scttfrdmn/aws-marimo-sagemaker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scttfrdmn%2Faws-marimo-sagemaker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35178402,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-06T02:00:07.184Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amazon-sagemaker-lab","aws","data-science","jupyter","jupyter-alternative","machine-learning","marimo","notebooks","python","reactive-programming","reproducible-research","sagemaker","sagemaker-studio"],"created_at":"2026-07-06T04:30:36.681Z","updated_at":"2026-07-06T04:30:37.649Z","avatar_url":"https://github.com/scttfrdmn.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# marimo on Amazon SageMaker\n\nRun [marimo](https://marimo.io), the reactive Python notebook, on Amazon SageMaker Studio and Studio Lab.\n\n[![Setup on Studio Lab](https://img.shields.io/badge/Setup_on-SageMaker_Studio_Lab-orange?logo=amazon-aws\u0026logoColor=white)](BOOTSTRAP.md)\n[![5-Minute Setup](https://img.shields.io/badge/⚡_5--Minute-Setup_Guide-brightgreen)](QUICKSTART.md)\n[![Python](https://img.shields.io/badge/Python-3.9+-blue?logo=python\u0026logoColor=white)](https://www.python.org)\n[![marimo](https://img.shields.io/badge/marimo-0.21.1+-green?logo=python)](https://marimo.io)\n[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Version](https://img.shields.io/badge/version-0.1.0-blue)](VERSION)\n\n---\n\n## ⚡ One-Command Setup\n\nFor SageMaker Studio Lab (free, no AWS account required):\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/scttfrdmn/aws-marimo-sagemaker/main/bootstrap.sh | bash\n```\n\n**Then start marimo:**\n```bash\n~/start-marimo.sh\n```\n\n[📖 Full Bootstrap Guide](BOOTSTRAP.md) | [⚙️ Manual Setup](QUICKSTART.md)\n\n---\n\n## ⚠️ Known Limitation: WebSocket on SageMaker Studio Lab\n\n**marimo's home page loads but notebooks show blank cells or \"connecting\" status.**\n\nThis 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.\n\n**What works:**\n- ✅ marimo home page / file browser via `/proxy/2718/`\n- ✅ HTTP API requests through the proxy\n- ✅ jupyter-server-proxy 4.4.0 (conda default) — no downgrade needed\n\n**What doesn't work (without the shim):**\n- ❌ Interactive notebook editing (requires WebSocket)\n- ❌ Cell execution and reactive updates (requires WebSocket)\n\n**Workaround included:** This repo uses [ws-sse-proxy](https://github.com/scttfrdmn/ws-sse-proxy) to translate WebSocket to SSE, making marimo fully functional on Studio Lab. See [WEBSOCKET-STATUS.md](WEBSOCKET-STATUS.md) for details, or just run:\n```bash\nbash start-marimo-shim.sh\n# Then access at /proxy/2719/\n```\n\n**Tracking:** [marimo-jupyter-extension #8](https://github.com/marimo-team/marimo-jupyter-extension/issues/8) and [marimo #8060](https://github.com/marimo-team/marimo/issues/8060)\n\n---\n\n## 🚀 Quick Start (5 Minutes)\n\n**Want to try marimo right now?**\n\n👉 **[Start with the Quick Start Guide](QUICKSTART.md)** - Get marimo running in 5 minutes on SageMaker Studio Lab (free!) or Studio.\n\n## 📚 What's Included\n\nThis repository provides:\n\n1. **📖 [Complete Blog Post](blog-post.md)** (~2000 words)\n   - Deep dive into marimo's features\n   - Why use marimo on SageMaker\n   - Architecture overview\n   - Deployment strategies\n   - Best practices and troubleshooting\n\n2. **⚡ [Quick Start Guide](QUICKSTART.md)**\n   - 5-minute setup for Studio Lab (free)\n   - Easy installation for Studio\n   - Sample notebooks\n   - Troubleshooting tips\n\n3. **🔧 Infrastructure as Code**\n   - `terraform/` - Complete Terraform deployment\n   - `cdk/` - AWS CDK (Python) deployment\n   - Lifecycle configurations\n   - Sample notebooks\n\n4. **🎓 [Demo Notebook](sagemaker_ml_demo.py)**\n   - Complete ML workflow\n   - Interactive data exploration\n   - Model training with reactive parameters\n   - SageMaker integration examples\n\n## 🎯 Choose Your Path\n\n### Path 1: Just Try It (Fastest)\n**Perfect for**: Learning, experimenting, quick demos\n\n1. Get free SageMaker Studio Lab account\n2. Follow [QUICKSTART.md](QUICKSTART.md)\n3. Try the sample notebook\n4. Total time: ~10 minutes\n\n### Path 2: Manual Setup on Studio/Studio Lab\n**Perfect for**: Individual users, existing Studio environment\n\n1. Open SageMaker Studio or Studio Lab\n2. Run `pip install marimo jupyter-server-proxy`\n3. Start with `marimo edit --host 0.0.0.0 --port 2718 --no-token --headless`\n4. See [QUICKSTART.md](QUICKSTART.md) for details\n5. **Note:** On Studio Lab, WebSocket connections are blocked by the gateway — see [known limitation](#-known-limitation-websocket-on-sagemaker-studio-lab)\n\n### Path 3: Production Deployment\n**Perfect for**: Teams, production workloads, persistent setup\n\n1. Read the [blog post](blog-post.md) for architecture understanding\n2. Choose Terraform or CDK\n3. Deploy with one command\n4. Get automated, persistent marimo installation\n\n## 💡 Why marimo?\n\nTraditional Jupyter notebooks have well-known issues:\n- ❌ Hidden state from out-of-order execution\n- ❌ JSON format causes Git conflicts\n- ❌ ~75% of notebooks on GitHub don't run\n- ❌ Hard to reproduce research\n\n**marimo solves these problems:**\n- ✅ Reactive execution - cells auto-update when dependencies change\n- ✅ Stored as pure Python - Git-friendly, executable as scripts\n- ✅ No hidden state - deterministic, reproducible\n- ✅ Interactive UI widgets - no callbacks needed\n- ✅ Three tools in one - notebook, script, and web app\n\n## 🏗️ Architecture\n\n```\n┌─────────────────────────────────────┐\n│   SageMaker Studio / Studio Lab     │\n│  ┌───────────────────────────────┐  │\n│  │  JupyterLab Environment       │  │\n│  │  ┌─────────────────────────┐  │  │\n│  │  │ jupyter-server-proxy    │  │  │\n│  │  │         ↓                │  │  │\n│  │  │ marimo server (:2718)   │  │  │\n│  │  └─────────────────────────┘  │  │\n│  └───────────────────────────────┘  │\n└─────────────────────────────────────┘\n```\n\n## 📦 Repository Structure\n\n```\n.\n├── README.md                    # This file\n├── QUICKSTART.md               # 5-minute setup guide\n├── BOOTSTRAP.md                # One-command bootstrap guide\n├── STUDIO-LAB-SETUP.md         # Automated Studio Lab setup\n├── BADGES.md                   # Badge options for READMEs\n├── WEBSOCKET-STATUS.md         # WebSocket proxy status \u0026 research\n├── CONTRIBUTING.md             # Contribution guidelines\n├── CHANGELOG.md                # Version history (Keep a Changelog)\n├── LICENSE                     # MIT License\n├── VERSION                     # Semantic version (0.1.0)\n├── blog-post.md                # Full blog post (~2000 words)\n├── sagemaker_ml_demo.py        # Complete demo notebook\n├── bootstrap.sh                # One-command setup script\n├── start-marimo-shim.sh        # Start marimo with WebSocket shim\n├── studio-lab-setup.sh         # Setup script with conda env\n├── terraform/                  # Terraform IaC (coming soon)\n├── cdk/                        # AWS CDK IaC (coming soon)\n└── notebooks/                  # Sample notebooks (coming soon)\n```\n\n## 🎓 Sample Notebooks\n\n### Quick Demo\n```python\nimport marimo as mo\n\n# Interactive slider\nslider = mo.ui.slider(0, 100, value=50)\n\n# Automatically updates when slider changes!\nresult = slider.value ** 2\nmo.md(f\"Value: {slider.value}, Squared: {result}\")\n```\n\n### SageMaker Integration\n```python\nimport marimo as mo\nimport boto3\n\nsagemaker = boto3.client('sagemaker')\n\n# List training jobs\njobs = sagemaker.list_training_jobs(MaxResults=10)\n\n# Interactive table\nmo.ui.table(jobs['TrainingJobSummaries'])\n```\n\nSee [sagemaker_ml_demo.py](sagemaker_ml_demo.py) for a complete, production-ready example.\n\n## 🚢 Deployment Options\n\n### Option 1: Terraform\n\n```bash\ncd terraform\nterraform init\nterraform apply\n```\n\nCreates:\n- SageMaker Studio Domain\n- VPC and security groups\n- IAM roles\n- Lifecycle configuration for marimo\n- S3 bucket for artifacts\n\n### Option 2: AWS CDK\n\n```bash\ncd cdk\npip install -r requirements.txt\ncdk deploy\n```\n\nSame infrastructure as Terraform, using Python CDK constructs.\n\n### Option 3: Manual (Quickest)\n\nSee [QUICKSTART.md](QUICKSTART.md) - just `pip install marimo` and go!\n\n## 💰 Cost Comparison\n\n| Option | Cost | Best For |\n|--------|------|----------|\n| **Studio Lab** | **$0** (100% free) | Learning, small projects |\n| **Studio (manual)** | ~$0.05-2/hour | Individual use, testing |\n| **Studio (IaC)** | ~$1-5/hour | Teams, production |\n\nmarimo's lightweight architecture means minimal overhead costs.\n\n## 🔧 Maintenance\n\n### Updating marimo\n\n**Studio Lab / Manual:**\n```bash\npip install --upgrade marimo\n```\n\n**With Lifecycle Config:**\nUpdate the version in `install-marimo.sh` and redeploy lifecycle configuration.\n\n### Cleanup\n\n**Terraform:**\n```bash\nterraform destroy\n```\n\n**CDK:**\n```bash\ncdk destroy\n```\n\n**Manual:**\nJust stop using it - no infrastructure to clean up!\n\n## 🤝 Use Cases\n\nmarimo on SageMaker is perfect for:\n\n- 🔬 **Reproducible Research** - Pure Python format, no hidden state\n- 👥 **Team Collaboration** - Git-friendly, version-controlled notebooks\n- 📊 **Interactive Dashboards** - Reactive UI updates, deploy as web apps\n- 🚀 **MLOps Pipelines** - Run notebooks as scripts in CI/CD\n- 🎓 **Teaching \u0026 Demos** - Predictable execution, professional output\n- 🔍 **Data Exploration** - Interactive filtering and visualization\n\n## 🆚 marimo vs Jupyter\n\n**When to use marimo:**\n- ✅ Building dashboards or interactive apps\n- ✅ Need reproducible, version-controlled research\n- ✅ Want reactive, automatic updates\n- ✅ Creating reusable modules or pipelines\n- ✅ Teaching or presenting (no hidden state issues)\n\n**When to use Jupyter:**\n- ✅ Quick ad-hoc exploration\n- ✅ Team heavily invested in Jupyter ecosystem\n- ✅ Need specific Jupyter extensions\n\n**Best practice:** Use both! Convert between formats as needed with `marimo convert`.\n\n## ❓ Troubleshooting\n\nCommon issues and solutions are in [QUICKSTART.md](QUICKSTART.md#troubleshooting).\n\nQuick fixes:\n- **Can't access UI**: Check proxy URL path\n- **Port in use**: Use different port (`--port 8889`)\n- **Proxy not working**: Run `jupyter serverextension enable --py jupyter_server_proxy`\n\n## 🎯 Next Steps\n\n1. ✅ Try the [Quick Start](QUICKSTART.md) (5 minutes)\n2. ✅ Read the [blog post](blog-post.md) for deep dive\n3. ✅ Run the [demo notebook](sagemaker_ml_demo.py)\n4. ✅ Convert your Jupyter notebooks: `marimo convert notebook.ipynb`\n5. ✅ Deploy with infrastructure-as-code for production use\n\n## 🌟 Features Showcase\n\n### Reactive Execution\n```python\n# Change slider, everything updates automatically\nslider = mo.ui.slider(0, 100)\nfiltered_data = data[data['value'] \u003e slider.value]\nplot = create_plot(filtered_data)  # Auto-updates!\n```\n\n### Git-Friendly\n```bash\n# Clean diffs, no JSON\ngit diff notebook.py\n\n# Run as script\npython notebook.py\n\n# Deploy as app\nmarimo run notebook.py\n```\n\n### Interactive UI\n```python\n# No callbacks needed!\ndropdown = mo.ui.dropdown(['A', 'B', 'C'])\ntable = mo.ui.table(dataframe)\nplot = mo.ui.plotly(figure)\n```\n\n## 📄 License\n\nThis repository: MIT License\n\nmarimo: Apache 2.0 License\n\n## 🙏 Acknowledgments\n\n- **marimo team** - for building an amazing reactive notebook platform\n- **AWS SageMaker team** - for creating a flexible ML platform\n- **Community** - for feedback and contributions\n\n## 📬 Support\n\n- **Issues**: Open an issue in this repository\n- **marimo Discord**: https://marimo.io/discord\n- **AWS Support**: https://aws.amazon.com/support/\n\n---\n\n## 📚 Documentation\n\n- **[Quick Start Guide](QUICKSTART.md)** - Get running in 5 minutes\n- **[Bootstrap Guide](BOOTSTRAP.md)** - One-command automated setup\n- **[Studio Lab Setup](STUDIO-LAB-SETUP.md)** - Persistent conda environment\n- **[WebSocket Status](WEBSOCKET-STATUS.md)** - WebSocket limitation details\n- **[Blog Post](blog-post.md)** - Complete guide (~2000 words)\n- **[Badge Options](BADGES.md)** - Add badges to your own projects\n- **[Contributing](CONTRIBUTING.md)** - How to contribute\n- **[Changelog](CHANGELOG.md)** - Version history\n\n## 📝 Project Info\n\n- **Version**: 0.1.0 ([Semantic Versioning](https://semver.org/))\n- **License**: [MIT](LICENSE)\n- **Copyright**: © 2026 Scott Friedman\n- **Changelog**: [Keep a Changelog](https://keepachangelog.com/) format\n\n## 🤝 Contributing\n\nContributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\nTo contribute:\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Submit a pull request\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history.\n\n---\n\n**Ready to get started?**\n\n👉 One command: `curl -fsSL https://raw.githubusercontent.com/scttfrdmn/aws-marimo-sagemaker/main/bootstrap.sh | bash`\n\n👉 Or manual: [QUICKSTART.md](QUICKSTART.md)\n\n👉 Deep dive: [Full blog post](blog-post.md)\n\nHappy reactive coding! 🚀\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscttfrdmn%2Faws-marimo-sagemaker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscttfrdmn%2Faws-marimo-sagemaker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscttfrdmn%2Faws-marimo-sagemaker/lists"}