Skip to content

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.

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.md
new file mode 100644
index 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 environments
diff --git a/docs/guides/package_management/inlining_dependencies.md b/docs/guides/package_management/inlining_dependencies.md
index 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 own
dependencies are easy to share — just send the `.py` file. (2) Isolating a
notebook 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:
```console
diff --git a/mkdocs.yml b/mkdocs.yml
index 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