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: include a page on home and sandboxed home (#7856)
Dylan Madisetti297ae86c31b4
diff --git a/docs/guides/editor_features/home.md b/docs/guides/editor_features/home.mdnew file mode 100644index 0000000000..d8d7b9f5c1--- /dev/null+++ b/docs/guides/editor_features/home.md@@ -0,0 +1,95 @@+# Home page++Running `marimo edit` without a filename opens the home page, which lets you+browse and manage notebooks in a directory.++## Usage++```bash+# Open home page for current directory+marimo edit++# Open home page for a specific folder+marimo edit folder/+```++The home page shows all marimo notebooks in the directory, letting you:++- Open existing notebooks+- Create new notebooks+- See notebook metadata++## Sandboxed Home++You can run the home page in sandbox mode (called "Sandboxed Home"), where+each notebook gets its own isolated environment:++```bash+marimo edit --sandbox folder/+```++When using Sandboxed Home:++1. Each notebook runs in its own isolated environment+2. Dependencies are read from each notebook's [inline script metadata](../package_management/inlining_dependencies.md) (PEP 723)+3. Environments are created on-demand when you open a notebook++This is useful when you have a collection of notebooks with different+dependencies and want to keep them isolated from each other.++!!! note "Additional dependencies required"++ Sandboxed Home requires additional packages:++ ```bash+ uv add 'marimo[sandbox]'+ ```++ This installs `pyzmq` (for inter-process communication) and `uv`+ (for environment management).++### Using custom virtual environments++When using Sandboxed Home, you can specify an existing virtual environment+for a notebook instead of having marimo create one automatically.+This is configured using `[tool.marimo.venv]` in your script metadata:++```python+# /// script+# [tool.marimo.venv]+# path = "path/to/venv" # relative or absolute path+# writable = false # optional, default is false+# ///+```++!!! note "Sandboxed Home only"++ The `[tool.marimo.venv]` configuration only applies when using+ Sandboxed Home (`marimo edit --sandbox folder/`). For single notebooks,+ activate your virtual environment before running marimo:++ ```bash+ source path/to/venv/bin/activate+ marimo edit notebook.py+ ```++#### Configuration options++| Option | Description |+|--------|-------------|+| `path` | Path to the virtual environment (relative or absolute) |+| `writable` | Whether marimo can install packages into the venv (default: `false`) |++#### Behavior++| `writable` | marimo installed? | What happens |+|:-----------|:------------------|:-------------|+| `true` | - | marimo installs itself and required dependencies into the venv |+| `false` | Yes | Uses the venv as-is (warns if marimo version differs) |+| `false` | No | Injects `PYTHONPATH` for marimo (requires matching Python version) |++This is useful when:++- You have a conda or poetry environment you want to reuse+- You're working in a team with a shared environment+- You want notebooks in a folder to use different pre-configured environmentsdiff --git a/docs/guides/package_management/inlining_dependencies.md b/docs/guides/package_management/inlining_dependencies.mdindex 37e3361558..e624948870 100644--- a/docs/guides/package_management/inlining_dependencies.md+++ b/docs/guides/package_management/inlining_dependencies.md@@ -37,6 +37,12 @@ marimo's sandbox provides two key benefits. (1) Notebooks that carry their owndependencies are easy to share — just send the `.py` file. (2) Isolating anotebook from other installed packages prevents obscure bugs.+!!! tip "Sandboxed Home"++ You can also use `--sandbox` when editing a folder of notebooks. Each+ notebook gets its own isolated environment. See+ [Sandboxed Home](../editor_features/home.md#sandboxed-home).+You can also run sandboxed notebooks as scripts:```consolediff --git a/mkdocs.yml b/mkdocs.ymlindex 6434875e9a..7b3081f024 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -114,6 +114,7 @@ nav:- Editor features:- Editor features: guides/editor_features/index.md- Editor overview: guides/editor_features/overview.md+ - Home page: guides/editor_features/home.md- Understanding dataflow: guides/editor_features/dataflow.md- Module autoreloading: guides/editor_features/module_autoreloading.md- Hotkeys: guides/editor_features/hotkeys.md