Monitoring Marimo with Vigilmon: Notebook Server Uptime, WebSocket Connectivity & SSL Certificate Monitoring

Marimo is the reactive Python notebook that replaces Jupyter for data science and ML teams — notebooks that re-execute automatically when upstream cells change, with a clean separation between notebook code and notebook state. When a self-hosted Marimo server goes down, analysts lose access to their notebooks, scheduled notebook runs fail, and interactive dashboards built on Marimo go dark. When the WebSocket connection that drives Marimo's real-time reactivity drops, notebooks stop updating even if the HTTP server appears healthy. Vigilmon gives you external visibility into Marimo's availability: the HTTP server, WebSocket connectivity indicator, and SSL certificate health, so outages are caught before they interrupt analysis workflows.

What You'll Build

• An HTTP monitor on the Marimo server to detect process crashes and pod failures
• A TCP monitor on Marimo's WebSocket port to catch connectivity failures before users notice
• An SSL certificate monitor for your Marimo domain
• Alerting that distinguishes server crashes from WebSocket-level connectivity failures

Prerequisites

• A self-hosted Marimo server deployed as a persistent service (via Docker, systemd, or Kubernetes)
• The Marimo server exposed via HTTPS (e.g., https://marimo.example.com)
• The server configured to run in --host 0.0.0.0 mode for external access
• A free account at vigilmon.online

Step 1: Understand Marimo's Server Architecture

When Marimo runs as a server (marimo edit --host 0.0.0.0 or marimo run), it exposes:

| Component | Default port | Role | |---|---|---| | HTTP server | 2718 | Serves the notebook UI, assets, and API endpoints | | WebSocket | 2718 (same port, /ws) | Drives real-time reactive cell execution and output streaming |

Both the HTTP server and WebSocket share the same port — Marimo uses a single server process (built on Starlette/ASGI) that handles both HTTP requests and WebSocket upgrades. External monitoring focuses on the HTTP layer (which can be checked via standard HTTP monitors) and the TCP port (which confirms the process is alive and accepting connections).

Step 2: Monitor the Marimo Server with an HTTP Check

Marimo's HTTP server serves a landing page or notebook list at the root URL. An HTTP check on the root confirms the server process is alive and the network path is clear:

curl https://marimo.example.com
# Returns HTML containing the Marimo notebook interface or notebook list

1. Log in to Vigilmon → Add Monitor → HTTP.
2. URL: https://marimo.example.com.
3. Check interval: 60 seconds.
4. Response timeout: 15 seconds.
5. Expected status: 200.
6. Keyword: marimo (appears in the page title and body of the Marimo UI).
7. Click Save.

This monitor catches:

• Marimo server process crashes or OOM kills
• systemd service failures or Docker container restarts
• Kubernetes pod failures for Marimo deployments
• Reverse proxy (nginx, Caddy, Traefik) failures blocking access to Marimo

Alert sensitivity: Set to trigger after 1 consecutive failure. When the HTTP server is down, all notebook access is blocked — users cannot open notebooks, view outputs, or run code.

Step 3: Monitor the Marimo Port via TCP Check

Marimo's server listens on port 2718 by default. A TCP check on this port confirms the process is running and accepting connections — including WebSocket upgrades that the reactive UI depends on:

# Test Marimo port connectivity
nc -zv marimo.example.com 2718
# or via HTTPS proxy port 443 if behind a reverse proxy

If Marimo is deployed behind a reverse proxy (nginx, Caddy), use the proxy port (443) for the TCP check. If Marimo is directly exposed, use 2718:

1. Add Monitor → TCP.
2. Host: marimo.example.com.
3. Port: 443 (if behind HTTPS reverse proxy) or 2718 (if directly exposed).
4. Check interval: 60 seconds.
5. Label: Marimo server port.
6. Click Save.

Why TCP monitoring alongside HTTP? Marimo's interactive reactivity runs over WebSocket on the same port. A TCP check confirms the port is reachable at the network level. The HTTP check confirms the application layer responds. Together, they cover cases where the port is open but the HTTP server returns errors (partial startup failure) or where the HTTP proxy passes requests but the underlying Marimo process has stalled.

Step 4: Monitor the Marimo Health or API Endpoint

If your Marimo deployment exposes a health endpoint (via a reverse proxy health check or a custom wrapper), add an HTTP monitor targeting it. For standard Marimo deployments, the notebook list API endpoint confirms the application layer is functional:

# List notebooks (Marimo server API)
curl https://marimo.example.com/api/files
# Returns JSON with the list of available notebook files

1. Add Monitor → HTTP.
2. URL: https://marimo.example.com/api/files.
3. Check interval: 2 minutes.
4. Response timeout: 10 seconds.
5. Expected status: 200.
6. Keyword: files (present in the JSON response from the files API).
7. Label: Marimo files API.
8. Click Save.

Note: The exact API path may vary depending on your Marimo version. Check your Marimo server's available endpoints with curl -s https://marimo.example.com/api/ or refer to the Marimo documentation for your deployed version.

Step 5: Monitor SSL Certificates

Marimo's WebSocket connection (wss://) is used for all reactive execution — when the SSL certificate expires, browsers refuse the WebSocket upgrade, and notebooks stop receiving cell execution updates even if the HTTP layer appears functional:

openssl s_client -connect marimo.example.com:443 2>/dev/null | openssl x509 -noout -dates

1. Add Monitor → SSL Certificate.
2. Domain: marimo.example.com.
3. Alert when expiry is within: 30 days.
4. Alert again: 14 days, 7 days, 3 days, 1 day.
5. Click Save.

WebSocket and TLS: Marimo's reactive UI uses wss:// (WebSocket Secure) in production. An expired certificate causes wss:// connections to be rejected by browsers with a TLS error, leaving notebooks in a broken state where the page loads but cells never execute or update. SSL monitoring prevents this silent failure mode.

Step 6: Configure Alerting

In Vigilmon under Settings → Notifications, configure your alert channels:

| Monitor | Trigger | Action | |---|---|---| | Marimo HTTP | Non-200 or marimo missing | Check server process; inspect systemd/Docker/pod logs; verify port binding | | Marimo TCP port | Connection refused | Process crashed or port binding failed; check server logs immediately | | Files API | Non-200 or files missing | Application layer degraded; check Marimo process memory and disk usage | | SSL certificate | < 30 days to expiry | Renew certificate; verify WebSocket connections work after renewal |

Alert after: 1 consecutive failure for the HTTP and TCP monitors. 2 consecutive failures for the API monitor to avoid noise from transient notebook execution load.

Common Marimo Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | Marimo process OOM killed | HTTP monitor fires; TCP port monitor fires; alert within 60 s | | systemd service failed to restart | TCP port and HTTP monitors fire; process not accepting connections | | Reverse proxy (nginx) crash | HTTP monitor fires; TCP port on 443 fires if nginx owns it | | SSL certificate expired | SSL monitor alerts at 30-day threshold; WebSocket (wss://) connections rejected | | Kubernetes pod evicted (disk/memory pressure) | HTTP and TCP monitors fire; pod not scheduled | | Marimo upgrade leaves server broken | HTTP monitor fires if new version fails to start | | Disk full (notebook directory) | Files API may return errors; HTTP monitor may catch server errors | | Network partition between proxy and Marimo | HTTP monitor fires; TCP port on Marimo direct may still respond | | DNS misconfiguration | All monitors fire simultaneously |

Monitoring Notebook Execution Health (Beyond Infrastructure)

Vigilmon monitors Marimo's server infrastructure — whether the process is alive, the port is reachable, and the certificate is valid. Notebook execution health is a separate concern:

• Cell execution failures: Marimo surfaces execution errors inline within the notebook interface. For scheduled notebook runs, configure logging to capture execution output.
• Scheduled notebooks: If you run Marimo notebooks on a schedule (via cron or a job scheduler), use Vigilmon's heartbeat-style monitoring alongside your scheduler to detect missed executions.
• Resource monitoring: For notebooks that process large datasets, monitor the host machine's CPU, memory, and disk via your infrastructure monitoring stack. Marimo does not expose Prometheus metrics natively.

Vigilmon catches server-level failures. Notebook execution errors require application-level logging and Marimo's inline error display.

Marimo is the reactive notebook server that data science and ML teams rely on for interactive analysis and live dashboards — when the server goes down, every analyst loses access to their notebooks simultaneously, and any scheduled or embedded Marimo dashboards go dark. Vigilmon gives you external visibility into Marimo's availability that doesn't depend on users reporting issues: HTTP uptime, TCP port health, and SSL certificate validity, so you know the moment the notebook server becomes unreachable and can restore access before it blocks the next analysis sprint or team standup.

Start monitoring Marimo in under 5 minutes — register free at vigilmon.online.