> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/marimo-team/marimo/llms.txt
> Use this file to discover all available pages before exploring further.
# Deploy as Interactive App
> Run marimo notebooks as interactive web applications with marimo run
# Deploy as Interactive App
Deploy your marimo notebooks as read-only web applications that users can interact with. When running as an app, notebooks are presented in a clean interface optimized for end-users, with optional code visibility and built-in authentication.
## Running as an App
Use `marimo run` to launch your notebook as an interactive web application:
```bash Basic Usage theme={null}
marimo run notebook.py
```
```bash Custom Port and Host theme={null}
marimo run notebook.py --host 0.0.0.0 --port 8080
```
```bash Multiple Notebooks (Gallery) theme={null}
marimo run notebook1.py notebook2.py notebook3.py
marimo run notebooks/ # Serve all notebooks in directory
```
The app will be available at `http://localhost:2718` by default (or your specified port).
## App Mode Features
### Read-Only Interface
In app mode, users can:
* **Interact** with UI elements (sliders, dropdowns, buttons, etc.)
* **View** outputs and visualizations that update reactively
* **Navigate** between cells and sections
* **Download** outputs and data when enabled
Users cannot:
* Edit or add cells
* Modify code
* Access the notebook source (unless `--include-code` is used)
### Code Visibility
By default, code is hidden in app mode. Control code visibility with the `--include-code` flag:
```bash Hide Code (Default) theme={null}
marimo run notebook.py
```
```bash Show Code theme={null}
marimo run notebook.py --include-code
```
You can also hide code for specific cells using the cell decorator:
```python theme={null}
import marimo as mo
@app.cell(hide_code=True)
def __(mo):
# This cell's code will be hidden even with --include-code
mo.md("# Welcome to my app!")
return
```
### Live Reload
Enable automatic reload when notebook files change:
```bash theme={null}
marimo run notebook.py --watch
```
With `--watch`, the app automatically refreshes when you save changes to the notebook file. Great for development!
## Authentication and Access Control
### Token Authentication
Protect your app with password authentication:
```bash Auto-Generated Token theme={null}
marimo run notebook.py --token
```
```bash Custom Password theme={null}
marimo run notebook.py --token-password "your-secret-password"
```
```bash Password from File theme={null}
marimo run notebook.py --token-password-file /path/to/password.txt
```
```bash Password from stdin theme={null}
echo "your-secret-password" | marimo run notebook.py --token-password-file -
```
With `--token`, marimo generates a random password and displays it in the terminal. The app URL will include an access token for convenience.
### Authentication Methods
Users can authenticate in three ways:
1. **Login Page**: Browser users are redirected to a login page
2. **Query Parameter**: `http://localhost:2718?access_token=your-password`
3. **HTTP Basic Auth**: For programmatic access
```bash theme={null}
curl -u "user:your-password" http://localhost:2718/api/status
```
### Custom Authentication
For production deployments, implement custom authentication using ASGI middleware:
```python theme={null}
from fastapi import FastAPI
import marimo
# Create marimo app
server = marimo.create_asgi_app().with_app(path="", root="./app.py")
# Create FastAPI app with custom auth
app = FastAPI()
app.add_middleware(MyAuthMiddleware) # Your custom auth
app.mount("/", server.build())
```
See the [Authentication Guide](/guides/deploying/authentication) for detailed examples.
## Configuration Options
### Network Configuration
Specify where the app listens:
```bash theme={null}
marimo run app.py --host 0.0.0.0 --port 8080
```
Configure for deployment behind a proxy:
```bash theme={null}
marimo run app.py --proxy https://example.com
```
Mount app at a subpath:
```bash theme={null}
marimo run app.py --base-url /my-app
```
Allow specific origins:
```bash theme={null}
marimo run app.py --allow-origins https://example.com --allow-origins https://app.com
```
### Session Management
```bash theme={null}
# Set session timeout (seconds)
marimo run app.py --session-ttl 300
# Redirect console output to browser
marimo run app.py --redirect-console-to-browser
```
The default session TTL is 120 seconds. Sessions are closed after this duration of inactivity. Set a longer TTL for apps with long-running computations.
### Advanced Options
```bash Headless Mode theme={null}
# Don't open browser automatically
marimo run app.py --headless
```
```bash Skew Protection theme={null}
# Prevent version mismatches (enabled by default)
marimo run app.py --no-skew-protection
```
```bash Sandboxed Environment theme={null}
# Run in isolated environment with uv
marimo run app.py --sandbox
```
## Gallery Mode
Serve multiple notebooks from a single server:
```bash Multiple Files theme={null}
marimo run app1.py app2.py app3.py
```
```bash Directory theme={null}
marimo run notebooks/
```
```bash Mixed theme={null}
marimo run dashboard.py analytics/ reports.py
```
When running multiple notebooks, marimo creates a gallery index page where users can select which notebook to view.
## Command-Line Arguments
Pass arguments to your notebook at runtime:
```bash theme={null}
marimo run app.py -- --dataset sales --year 2024
```
Access arguments in your notebook:
```python theme={null}
import marimo as mo
import sys
# Using mo.cli_args() utility
args = mo.cli_args()
dataset = args.get("dataset", "default")
year = int(args.get("year", 2024))
# Or use argparse/simple-parsing
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("--dataset", default="default")
parser.add_argument("--year", type=int, default=2024)
args = parser.parse_args(sys.argv[1:])
```
## Health and Status Endpoints
monitor your deployed app:
```bash Health Check theme={null}
curl http://localhost:2718/health
# Returns: 200 OK
```
```bash Alternative Health Endpoint theme={null}
curl http://localhost:2718/healthz
# Returns: 200 OK
```
```bash Status Information theme={null}
curl http://localhost:2718/api/status
# Returns: JSON with server status
```
These endpoints are useful for:
* Load balancer health checks
* Monitoring and alerting
* Automated deployment verification
## Best Practices
**For Production Deployments:**
1. **Use authentication** with `--token-password` or custom ASGI middleware
2. **Set appropriate session TTL** based on your use case
3. **Configure CORS** to allow only trusted origins
4. **Use environment variables** for sensitive configuration
5. **Enable health checks** for monitoring
6. **Run behind a reverse proxy** (nginx, Caddy) for SSL/TLS
7. **Use `--headless`** to prevent browser launch on server
## Examples
### Public Dashboard
```bash theme={null}
marimo run dashboard.py \
--host 0.0.0.0 \
--port 8080 \
--headless \
--no-token \
--session-ttl 300
```
### Internal Tool with Auth
```bash theme={null}
marimo run analysis.py \
--host 0.0.0.0 \
--token-password-file /run/secrets/marimo_password \
--include-code \
--base-url /analytics
```
### Development Server
```bash theme={null}
marimo run app.py \
--watch \
--include-code \
--redirect-console-to-browser
```
## Next Steps
Deploy your app to cloud platforms and services
Execute notebooks as Python scripts
Deploy browser-based notebooks with WebAssembly
Advanced authentication and security