Add "Try it in Molab" Interactive Notebooks to Documentation

[NavarrePratt]

Summary

Add interactive notebook experiences to the aviato-client documentation using Marimo notebooks and Molab (Marimo's free hosted notebook platform). This follows the pattern popularized by ML projects like Unsloth, Hugging Face, and Ultralytics with their "Open in Colab" buttons, but uses Marimo's reactive notebook format and its mkdocs integration for a tighter docs experience.

Motivation

Interactive notebooks lower the barrier to trying a SDK. Projects like Unsloth drive adoption by letting users go from README to running code in one click. For aviato-client, this would:

• Let users try sandbox creation, exec, and file operations without local setup
• Provide a guided onboarding path beyond static code examples
• Serve as living documentation that stays testable

Proposed Scope

Phase 1 - Notebooks in repo

Add a notebooks/ directory with marimo .py notebooks covering core SDK paths:

Notebook	Content
quick_start.py	Install, create sandbox, run a command, read output
streaming_exec.py	Real-time stdout streaming with process.stdout iteration
remote_functions.py	@session.function() decorator for remote execution
session_management.py	Session-based multi-sandbox workflows, cleanup
file_operations.py	read_file / write_file round-trip

Each notebook should:

• Start with a markdown header explaining the feature and linking back to full docs
• Include an install cell (%pip install -q aviato) with pinned version
• Use AVIATO_API_KEY from environment (Molab supports env var configuration)
• Be self-contained and runnable top-to-bottom

Phase 2 - Molab badges in docs

Add "Open in Molab" badges to:

• README.md (quick start notebook)
• Relevant pages in docs/guides/ (contextual badges next to features they demonstrate)
• examples/README.md

Badge format:

[![Open in molab](https://marimo.io/molab-shield.svg)](https://molab.marimo.io/notebooks/nb_NOTEBOOK_ID)

Phase 3 - Inline docs embedding (stretch)

Evaluate mkdocs-marimo plugin for embedding interactive code blocks directly in docs pages. This would let users run aviato examples without leaving the documentation site. Requires evaluation of:

• Whether aviato SDK calls work in Molab's sandboxed environment (needs outbound network to atc.cwaviato.com)
• WASM playground limitations (may not support gRPC - Molab cloud execution likely required)
• Auth flow in hosted environments

Open Questions

1. Auth in Molab: How should users provide AVIATO_API_KEY in a hosted notebook? Molab supports environment variables - need to verify the UX.
2. Network access: Molab runs on Modal. Need to confirm notebooks can reach atc.cwaviato.com for gRPC calls.
3. Notebook location: Keep in main repo (notebooks/ dir) or separate repo? Given we'd likely have < 10 notebooks, same-repo in notebooks/ is simpler.
4. Version pinning strategy: Pin to latest release in install cells and update as part of the release process, or use unpinned installs?

References

• Marimo docs - Molab guide
• Molab badge generator
• mkdocs-marimo plugin
• Unsloth notebooks repo - exemplar for Colab-based approach
• HF notebooks repo - dual-repo approach at scale

[dmadisetti]

Cool. Comprehensive plan! Couple comments:

Phase 3 - Inline docs embedding (stretch)

It's probably better just to use an iframe over native + mkdocs (we do it in our docs e.g. https://docs.marimo.io/api/diagrams/)

<iframe allow="camera; geolocation; microphone; fullscreen; autoplay; encrypted-media; picture-in-picture; clipboard-read; clipboard-write" class="demo medium" frameborder="0" height="400px" src="<link>" style="display: block; margin: 0 auto;" width="100%"></iframe>

Auth in Molab: How should users provide AVIATO_API_KEY in a hosted notebook? Molab supports environment variables - need to verify the UX.

OAUTH flow could work here too. We still need to work out an ideal flow for secrets in molab (we can sync offline about maybe coupling aviato secret management and molab).

Network access: Molab runs on Modal. Need to confirm notebooks can reach atc.cwaviato.com for gRPC calls.

Yeah, this is fine (at least outbound)- and we'll actually run on aviato by end of quarter

Notebook location: Keep in main repo (notebooks/ dir) or separate repo? Given we'd likely have < 10 notebooks, same-repo in notebooks/ is simpler.

We can actually support direct from github (e.g. https://molab.marimo.io/github/SOLARIS-JHU/SciML-Course/blob/main/week_3/marimo/pinn_torch/pinn_pde_torch.py)

Version pinning strategy: Pin to latest release in install cells and update as part of the release process, or use unpinned installs?

We normally just provide a lower bound (marimo>=0.X.X), and if a release will break a notebook then we'll update it- with basic CI on the notebooks themselves as verification (it is just python)

---

Example of CF docs that just runs off static pages: https://notebooks.cloudflare.com/