App pools
Each notebook has a pool of app sandboxes. Each browser tab has independent marimo kernel state and consumes one visit slot, even within the same account. The router fills available sandboxes before starting more. An unused pool can scale to zero.
New visits receive the latest committed notebook version, including periodic editor saves. Existing visits keep their sandbox and version until departure or expiry.
Configuration
Configuration applies to every app in the deployment.
| Environment variable | Default | Purpose |
|---|---|---|
MARIMOHUB_APP_MAX_VISITS_PER_SESSION | Unset | Visit slots per sandbox. |
MARIMOHUB_APP_MAX_SESSIONS_PER_VERSION | Unset | Starting reservations and ready sandboxes per notebook's current version. |
Both settings accept positive integers. Unset means unlimited. With MARIMOHUB_APP_MAX_VISITS_PER_SESSION=2, three tabs from one account use two sandboxes. MARIMOHUB_APP_MAX_USERS_PER_SESSION is deprecated. It aliases to MARIMOHUB_APP_MAX_VISITS_PER_SESSION and logs a warning when used. If both are set, MARIMOHUB_APP_MAX_VISITS_PER_SESSION takes precedence.
Starting reservations occupy capacity before compute starts. Older versions drain and do not count toward the per-version limit. Expired starting reservations also stop counting while maintenance reclaims them. Project and starter-user limits still count all physical sandboxes, including draining versions. These limits can block a new version from starting. Full pools return HTTP 429 with Retry-After; the app page offers a retry action.
Presence and departure
Each open page sends periodic heartbeats, including while idle, and a departure request on navigation or closure. Clients use the advertised app_pool.heartbeat_interval_seconds, which defaults to 30 seconds. A persisted lease lasts 240 seconds. Heartbeats renew it at most once per minute. After each heartbeat, at least 180 seconds of the lease remain. Missed departures and browser crashes release slots through lease expiry.
Departure holds that visit's slot for 15 seconds of reconnect grace. Other tabs keep their own slots. Re-admitting the same visit ID during grace preserves its assignment. A new page load creates a new visit. After expiry, a visit must enter through admission again and receives the latest version.
Freeing a slot does not immediately retire its sandbox. The idle clock starts at the last lease or grace deadline. MARIMOHUB_SESSION_APP_IDLE_TIMEOUT_SECONDS controls retirement, subject to kernel connection protection and maintenance cadence. It inherits MARIMOHUB_SESSION_IDLE_TIMEOUT_SECONDS when unset, with a default of 1,800 seconds. Fresh visit leases protect occupied sandboxes even with stale session heartbeats. If a connection probe fails, maintenance also checks the last session heartbeat against the idle timeout. Credential expiry and provider lifetime limits still apply.
API and access
Independent API clients must supply distinct app_visit_id values. Retries reuse the same ID. Use the returned app_assignment for heartbeats and departure. Without an ID, callers share the legacy api visit for their account. The response fields users, max_users, and max_users_per_session retain their names but count visit slots.
In proxy exposure mode, kernel HTTP requests and WebSocket upgrades use /proxy/<token>/… and require an account assignment to the sandbox. Subdomain deployments use the direct sandbox URL. Kernel traffic does not renew leases or replace periodic heartbeats. A heartbeat failure must not trigger replay of a kernel mutation.
Proxy authorization checks the account assignment, not an exact visit and generation. A departed tab can retain access while another tab keeps the same sandbox assigned. Gateways that require per-request exact-visit validation must retain that check. Direct kernel URLs bypass managed-page admission, so occupancy counts managed visits rather than kernel connections.
Versions and operations
Synced notebooks load their immutable version workspace. Local notebooks load committed code and dependencies over existing auxiliary workspace files, which retain their mutable semantics. A missing version file fails startup.
Notebook rows show each sandbox's version, pool state, and visit occupancy. Stop and restart actions affect every visit on the selected sandbox. Restart reserves a replacement on the current version, then reclaims the old sandbox before starting compute. The replacement uses the selected sandbox's pool slot during teardown. Both remain recorded until reclamation finishes. Repeated restart requests reuse the replacement. Assignments to other sandboxes remain unchanged. Affected visits must enter through admission again. The hub does not transfer kernel memory or replay requests.
Cleanup
Run maintenance to recover interrupted provisioning and retry failed sandbox cleanup. Pool records and deletion tombstones remain until reclamation finishes; empty deletion tombstones remain permanently.
Storage cost
app_pool_admission records routing outcomes. app_pool.visits is one deployment-wide gauge of occupied visit slots, without project or notebook labels. Each app-pool sweep sets it after it scans every pool record. A listing error, or a pool-level error logged as app_pool_sweep_failed, skips that update. A member cleanup failure is logged as app_pool_cleanup_failed inside the pool's reconciliation and does not skip it. Monitor app_pool.cas.conflicts and app_pool.cas.exhausted as traffic grows: each notebook uses one CAS record. Its size grows with visits and sandbox members. See implementation and storage costs for read/write budgets and ownership rules.