Auto-Suspend & Resume

MoltShell automatically suspends your VM after a period of inactivity to save resources. When you come back, the VM resumes with everything intact.

How idle detection works

The terminal server sends a heartbeat to the MoltShell backend every 60 seconds while you have an active WebSocket connection. This updates the last_activity_at timestamp for your sandbox.

A cron job runs every 5 minutes and checks all running VMs. If a VM has not received a heartbeat for 60 minutes, it is suspended.

Activity is tracked based on WebSocket messages from your browser. Any terminal input (typing, resizing, scrolling) counts as activity. Simply having the terminal open in a browser tab keeps the VM alive, since the application-level ping/pong mechanism confirms the browser is still connected.

What triggers activity

• Typing in the terminal
• Resizing the terminal window
• Any WebSocket message from the browser

What does NOT prevent suspension

• A long-running process with no user interaction (unless the terminal tab is open in a browser)
• Having files saved on the VM
• A background SSH connection from elsewhere (VMs are only accessible through the MoltShell interface)

Dead connection detection

When you close your laptop or lose network, the WebSocket connection does not close cleanly. MoltShell uses two layers of detection:

1. Protocol-level ping: The server pings all WebSocket clients every 30 seconds. If no pong is received by the next ping, the connection is terminated.
2. Application-level ping: The server sends JSON { type: "ping" } messages through the WebSocket. The browser responds with { type: "pong" }. If no pong arrives within 90 seconds, the connection is killed.

The application-level ping exists because protocol-level WebSocket pings can be absorbed by reverse proxies (like Cloudflare) and never reach the browser. The JSON data frames always pass through.

Once dead connections are cleaned up, the heartbeat timer stops, and the VM becomes eligible for idle suspension.

What happens on suspend

GCP's suspend operation preserves the VM's RAM to disk. This means:

• All running processes freeze in place
• tmux sessions (and everything inside them) are preserved
• Environment variables, shell history, and open files persist
• Installed packages and system configuration remain

The VM stops consuming compute resources. Only disk storage is billed (~$0.60-1.20/month).

Resuming

When you click Start on the dashboard or navigate to the terminal, MoltShell resumes the VM. The resume process takes approximately 30 seconds. After resuming:

• All processes continue from where they were frozen
• Your terminal sessions are exactly as you left them
• The split pane layout is restored

Health checking

A health checker cron runs every 5 minutes alongside the idle checker. It detects VMs that are in a bad state:

• Frozen VMs: GCP reports the VM as RUNNING but the terminal server's /health endpoint does not respond. The health checker resets these VMs automatically.
• State drift: If the GCP status does not match the MoltShell database (e.g., the VM was manually stopped), the health checker syncs the state.

VMs started less than 15 minutes ago are excluded from health checks to avoid interfering with the boot process.