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.

feat: add MARIMO_SESSION_COOKIE_SECURE env var for Secure session cookie (#10117)

Myles Scolnick3a92f406803d
diff --git a/docs/guides/configuration/index.md b/docs/guides/configuration/index.md
index 54510bb956..351beddd93 100644
--- a/docs/guides/configuration/index.md
+++ b/docs/guides/configuration/index.md
@@ -124,6 +124,7 @@ marimo supports the following environment variables for advanced configuration:
| `MARIMO_STD_STREAM_MAX_BYTES` (deprecated, use `pyproject.toml`) | Maximum size of standard stream (stdout/stderr) output that marimo will display. Outputs larger than this will be truncated. | 1,000,000 (1MB) |
| `MARIMO_SKIP_UPDATE_CHECK` | If set to "1", marimo will skip checking for updates when starting. | Not set |
| `MARIMO_SQL_DEFAULT_LIMIT` | Default limit for SQL query results. If not set, no limit is applied. | Not set |
+| `MARIMO_SESSION_COOKIE_SECURE` | If set to `true`/`1`, marks the session cookie as `Secure` so browsers only send it over HTTPS. Enable when serving marimo behind TLS. | `false` |
### Tips
diff --git a/marimo/_config/settings.py b/marimo/_config/settings.py
index f0dd7aa529..fc70cd897f 100644
--- a/marimo/_config/settings.py
+++ b/marimo/_config/settings.py
@@ -2,9 +2,10 @@
from __future__ import annotations
import logging
-import os
from dataclasses import dataclass
+from marimo._utils.env import is_env_true
+
@dataclass
class GlobalSettings:
@@ -12,21 +13,21 @@ class GlobalSettings:
QUIET: bool = False
YES: bool = False
CHECK_STATUS_UPDATE: bool = False
- TRACING: bool = os.getenv("MARIMO_TRACING", "false") in ("true", "1")
+ TRACING: bool = is_env_true("MARIMO_TRACING")
PROFILE_DIR: str | None = None
LOG_LEVEL: int = logging.WARNING
- MANAGE_SCRIPT_METADATA: bool = os.getenv(
- "MARIMO_MANAGE_SCRIPT_METADATA", "false"
- ) in ("true", "1")
- IN_SECURE_ENVIRONMENT: bool = os.getenv(
- "MARIMO_IN_SECURE_ENVIRONMENT", "false"
- ) in ("true", "1")
+ MANAGE_SCRIPT_METADATA: bool = is_env_true("MARIMO_MANAGE_SCRIPT_METADATA")
+ IN_SECURE_ENVIRONMENT: bool = is_env_true("MARIMO_IN_SECURE_ENVIRONMENT")
+ # Mark the session cookie as `Secure` so browsers only send it over HTTPS.
+ # Enable when serving marimo behind TLS / a TLS-terminating proxy. Default
+ # "false" to preserve local (plain-HTTP) development.
+ SESSION_COOKIE_SECURE: bool = is_env_true("MARIMO_SESSION_COOKIE_SECURE")
# Disable authentication on the virtual file endpoint (`/@file/...`).
# Useful in sandboxed/embedded deployments where virtual file URLs need
# to be fetched in trusted contexts. Default "false", meaning auth is required.
- DISABLE_AUTH_ON_VIRTUAL_FILES: bool = os.getenv(
- "_MARIMO_DISABLE_AUTH_ON_VIRTUAL_FILES", "false"
- ) in ("true", "1")
+ DISABLE_AUTH_ON_VIRTUAL_FILES: bool = is_env_true(
+ "_MARIMO_DISABLE_AUTH_ON_VIRTUAL_FILES"
+ )
# Hide all external code-sharing affordances (shareable WASM links, molab,
# HTML sharing) across every notebook session. Enforced by
# SecurityConfigManager, which MarimoConfigManager merges after all other
@@ -37,10 +38,7 @@ class GlobalSettings:
# Note: this is a UI-hiding/policy control, not a server-side security
# boundary -- exported HTML still embeds source and endpoints still serve
# code. Pair with network egress filtering for defence-in-depth.
- RESTRICT_SHARING: bool = os.getenv("MARIMO_RESTRICT_SHARING", "false") in (
- "true",
- "1",
- )
+ RESTRICT_SHARING: bool = is_env_true("MARIMO_RESTRICT_SHARING")
GLOBAL_SETTINGS = GlobalSettings()
diff --git a/marimo/_server/main.py b/marimo/_server/main.py
index 20702dbdcb..bbfb92e962 100644
--- a/marimo/_server/main.py
+++ b/marimo/_server/main.py
@@ -10,6 +10,7 @@ from starlette.middleware import Middleware
from starlette.middleware.cors import CORSMiddleware
from marimo import _loggers
+from marimo._config.settings import GLOBAL_SETTINGS
from marimo._server.api.auth import (
RANDOM_SECRET,
CustomAuthenticationMiddleware,
@@ -71,6 +72,7 @@ def create_starlette_app(
Middleware(
CustomSessionMiddleware,
secret_key=RANDOM_SECRET,
+ https_only=GLOBAL_SETTINGS.SESSION_COOKIE_SECURE,
),
]
)
diff --git a/marimo/_utils/env.py b/marimo/_utils/env.py
index 36c78fac83..c416dad1e6 100644
--- a/marimo/_utils/env.py
+++ b/marimo/_utils/env.py
@@ -4,6 +4,18 @@ from __future__ import annotations
import os
+def is_env_true(key: str, default: bool = False) -> bool:
+ """Return True if the env var `key` is set to a truthy value ("true"/"1").
+
+ Comparison is case-insensitive and ignores surrounding whitespace. Returns
+ `default` when the variable is unset.
+ """
+ value = os.environ.get(key)
+ if value is None:
+ return default
+ return value.strip().lower() in ("true", "1")
+
+
def env_to_value(key: str) -> tuple[str | None | list[str] | bool] | None:
"""Return a typed value from environment variables."""
if key in os.environ:
diff --git a/tests/_server/api/test_auth.py b/tests/_server/api/test_auth.py
index 600aeaaa4c..1ffce1de1b 100644
--- a/tests/_server/api/test_auth.py
+++ b/tests/_server/api/test_auth.py
@@ -53,6 +53,20 @@ async def test_custom_session_middleware_call_with_port():
assert middleware.session_cookie == "session"
+def test_custom_session_middleware_secure_flag_default(app: Starlette):
+ # By default the session cookie is not marked Secure so it works over
+ # plain HTTP during local development.
+ middleware = CustomSessionMiddleware(app, "secret_key")
+ assert "secure" not in middleware.security_flags
+
+
+def test_custom_session_middleware_secure_flag_enabled(app: Starlette):
+ # https_only=True (wired from MARIMO_SESSION_COOKIE_SECURE) marks the
+ # session cookie as Secure.
+ middleware = CustomSessionMiddleware(app, "secret_key", https_only=True)
+ assert "secure" in middleware.security_flags
+
+
def _app_with_base_url(base_url: str) -> Starlette:
app = create_starlette_app(base_url=base_url, enable_auth=True)
get_starlette_server_state_init(base_url=base_url).apply(app.state)
diff --git a/tests/_utils/test_env.py b/tests/_utils/test_env.py
new file mode 100644
index 0000000000..83d3546538
--- /dev/null
+++ b/tests/_utils/test_env.py
@@ -0,0 +1,42 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+import pytest
+
+from marimo._utils.env import is_env_true
+
+KEY = "MARIMO_TEST_IS_ENV_TRUE"
+
+
+def test_is_env_true_unset_uses_default(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.delenv(KEY, raising=False)
+ assert is_env_true(KEY) is False
+ assert is_env_true(KEY, default=True) is True
+
+
+ "value",
+ ["true", "1", "TRUE", "True", " true ", "\t1\n"],
+)
+def test_is_env_true_truthy(
+ monkeypatch: pytest.MonkeyPatch, value: str
+) -> None:
+ monkeypatch.setenv(KEY, value)
+ assert is_env_true(KEY) is True
+ # An explicit truthy value overrides a True default too.
+ assert is_env_true(KEY, default=False) is True
+
+
+ "value",
+ ["false", "0", "no", "yes", "", "2", "on", "off"],
+)
+def test_is_env_true_falsy(
+ monkeypatch: pytest.MonkeyPatch, value: str
+) -> None:
+ monkeypatch.setenv(KEY, value)
+ assert is_env_true(KEY) is False
+ # A set-but-falsy value overrides a True default.
+ assert is_env_true(KEY, default=True) is False