Session Lifetime

A session starts when created and ends when its timeout fires, when you explicitly close it, or when the server terminates it due to an error or inactivity. This page explains the full lifecycle.

timeoutSeconds

The timeoutSeconds field sets the maximum wall-clock time a session can run from creation. The minimum is 30 seconds, the maximum is 1800 seconds (30 minutes), and the default is 300 seconds (5 minutes).

When the timeout fires, the session machine stops and the filesystem is cleaned up (unless the session has a cellName, in which case the volume is preserved).

{
  "language": "python",
  "languageVersion": "3.12",
  "timeoutSeconds": 600,
  "autoSuspendMinutes": 15
}

{
  "language": "python",
  "languageVersion": "3.12",
  "timeoutSeconds": 600,
  "autoSuspendMinutes": 15
}

autoSuspendMinutes (idle stop)

autoSuspendMinutes configures idle-stop: if the session has no exec activity for this many minutes, it is suspended automatically. Set to 0 to use the plan default. The plan default itself depends on your plan tier and can be overridden per session.

Idle-stop is distinct from the timeout. A session that would timeout at timeoutAt but has been idle for autoSuspendMinutes will be suspended early. Resumed sessions continue from where they were suspended.

alwaysOn sessions

Sessions created with alwaysOn: true are never automatically destroyed when their timeout expires. Instead, they suspend and can be resumed at any time. They remain in the account indefinitely until explicitly closed or the volume is deleted.

Always-on sessions require a Growth or Scale plan and count against the per-org always-on session cap (default 2 concurrent per organization, configurable per plan).

{
  "language": "node",
  "languageVersion": "22",
  "alwaysOn": true,
  "autoSuspendMinutes": 30
}

{
  "language": "node",
  "languageVersion": "22",
  "alwaysOn": true,
  "autoSuspendMinutes": 30
}

cellName and persistent volumes

Named cells (sessions with a cellName) have a persistent volume attached to the workspace. The volume survives session end, allowing the next session with the same cell name to pick up where the previous one left off.

To permanently delete a cell's volume and all its data, call DELETE /sessions/:sessionId/volume. This is irreversible.

Session status transitions