Skip to Content
OpenInspect
Working in a session

Session lifecycle and statuses

What each session and sandbox status means, how a sandbox boots, and when work is saved.

Last reviewed View as MarkdownEdit on GitHubGive feedback

This page explains what a session's status tells you, what the separate sandbox status tells you, and what happens to your work when a sandbox boots, idles out, or fails.

Two levels of status

A session has two independent statuses:

  • The session status describes the conversation: whether a prompt is running, whether the last run succeeded, and whether the session is still open. It is durable and survives any number of sandboxes.
  • The sandbox status describes the current compute attached to the session. A session goes through many sandboxes over its life.

They do not line up one to one. A completed session can still have a live sandbox attached, and an active session can have none yet (for example, while the first sandbox is being created).

Session statuses

StatusLabel in the Sessions listMeaningCan accept a prompt
createdDraftThe session exists but no prompt has been dispatched yet.Yes
activeActiveA prompt is pending or processing.Yes (it is queued behind the running turn)
completedCompletedThe last run finished successfully and nothing is queued.Yes
failedFailedThe last run ended in an error and nothing is queued.Yes
archivedArchivedYou archived the session. It is hidden from the inbox.No, restore it first
cancelledCancelledThe session was cancelled. Unfinished prompts were closed.No

After every run the status settles by itself: back to active when more prompts are queued, otherwise completed or failed depending on the outcome. A session that was cancelled or archived in the meantime stays that way.

How these statuses reach the sidebar inbox is covered in Inbox, sessions list, and search. In short: an unread finished turn puts the session under Needs attention, an active session sits under In progress, and everything else is under Recent.

Sandbox statuses

The session header and right sidebar show the sandbox status with these labels:

StatusLabelWhat it means
pendingPendingWaiting for the sandbox to start.
warmingWarming...Preparing sandbox capacity.
spawningStarting...Creating or restoring the sandbox.
connectingConnecting...The runtime has connected and the boot is under way.
readyReadyThe sandbox is available and prompts dispatch.
snapshottingSaving...A sandbox snapshot is being saved.
stoppedStoppedThe sandbox stopped; the next prompt can restore or resume saved state.
staleUnresponsiveThe sandbox runtime stopped responding.
failedFailedThe sandbox could not start or recover.

Sandbox tools such as the terminal and code server are usable only while the sandbox is ready.

How a sandbox boots

A prompt sent during a boot waits and dispatches as soon as the sandbox is ready. The session header names the current phase while it runs: "Starting runtime", "Cloning repository", "Running setup.sh", "Starting services", "Installing skills", "Starting agent". Multi-repository sessions add the repository name, as in "Running setup.sh for acme/api".

New sandboxes have three boot paths. Persistent providers can instead resume a retained sandbox in place.

PathWhen it is usedPhases you see
Fresh startFirst sandbox for a repository with no prebuilt image and no snapshotCloning, setup.sh, services, skills, agent
Prebuilt imageThe repository or environment has a Ready image (see Prebuilt images)Cloning (an incremental sync), services, skills, agent. Setup already ran when the image was built
Snapshot restoreA later prompt in a session that already has a saved snapshotServices, skills, agent. The restored checkout, including uncommitted work, is kept and the session branch is fetched

Script failures behave differently by phase:

  • A non-zero exit from .openinspect/setup.sh is reported as a warning and the boot continues.
  • A .openinspect/start.sh failure in the session's first repository ends the boot. On a prebuilt image start, a failing start.sh fails the start immediately.
  • The header's status popover says which phase failed and, when available, which repository. Script output is not collected or shown.

See Lifecycle scripts for what the scripts can do.

Boot bounds

There is no fixed limit on how long setup.sh or start.sh may run. Three bounds apply instead:

BoundDefaultWhat it covers
Connect watchdog4 minutesFrom sandbox creation until the runtime first connects. This is the provider launching the container, not your scripts.
Boot budget30 minutesFrom sandbox creation until the sandbox is ready. Your operator can change it with SANDBOX_BOOT_TIMEOUT_MS.
Heartbeat90 secondsA runtime that stops sending heartbeats during boot is treated as dead.

When any of these trips:

  1. The sandbox is marked failed and its credentials are revoked.
  2. The prompt that was waiting fails, and the error names the phase that was running (for example, that the boot exceeded 30 minutes while running setup.sh).
  3. No snapshot is taken, so a half-provisioned workspace never becomes the restore point.
  4. Your next prompt starts a new sandbox.

Older snapshots

A snapshot from before phase reporting can restore only if its recorded runtime version is compatible. A snapshot with an unknown or incompatible version is retained and recovery is held rather than starting from a clean tree. Older compatible runtimes may report no phases and must connect within the 4-minute watchdog.

Inactivity and lifetime

Two timers end a sandbox that is not failing:

  • Inactivity. With no session-page WebSocket connected, idle sandboxes for automations (automation), GitHub bot runs (github-bot), and agent-created children (agent, including nested children) default to stopping after 2 minutes. User (user), Slack (slack-bot), and Linear (linear-bot) sessions keep the 10-minute default. Modal, modal-vm, and Vercel attempt to save state at confirmed shutdown; Daytona, E2B, and Boat stop, pause, or archive the retained sandbox. The sandbox shows Stopped; a follow-up prompt resumes the existing session and restores or resumes its sandbox rather than creating a new session.
  • Lifetime. Settings › Sandbox has a Session Timeout (minutes) field that requests a lifetime for each sandbox. Leave it blank to inherit a parent setting or the provider default. The field appears only for providers that honor it (Modal, modal-vm, Vercel, E2B, Boat; not Daytona).
  • Final snapshot buffer. Also under Settings › Sandbox, Final snapshot buffer (minutes) reserves time before provider expiry to stop work, preserve the filesystem, and retire the sandbox. Default 10 minutes, minimum 5.

Your operator sets the regular timeout with SANDBOX_INACTIVITY_TIMEOUT_MS (default 600000 ms) and the unattended timeout with SANDBOX_UNATTENDED_INACTIVITY_TIMEOUT_MS (default 120000 ms, minimum 60000 ms; lower values are rejected). Unattended sessions use the smaller of the two values, so setting the unattended value at or above the regular value disables the shorter timeout.

A connected session-page WebSocket keeps the existing timer extensions and receives warnings instead of an inactivity stop, including for unattended sessions. Direct terminal, VS Code, or VNC connections alone do not extend the timer. Runtime heartbeats renew activity while a prompt is processing, so quiet running turns are not treated as idle.

Settings › Sandbox values can be set globally and overridden per repository and per environment. See Sandbox settings.

When your work is saved

A snapshot may be taken:

  • after a turn completes (including failed execution) on providers that support per-turn snapshots,
  • during shutdown for inactivity or lifetime on snapshot-based providers,
  • when the control plane explicitly requests one.

A snapshot is never taken on a failed boot, and the runtime refuses a snapshot request while it is still booting. Vercel and modal-vm require shutdown to capture a snapshot, so they skip post-turn snapshots and save state at shutdown instead. Snapshot capture can fail; do not assume every turn has a saved copy.

Saved filesystem state includes installed dependencies, built artifacts, and uncommitted changes. A snapshot with an incompatible or unknown runtime version is retained but not restored; recovery is held rather than silently discarding that work.

Provider resume models

Not every provider restores from a saved filesystem:

ProviderResume model
Modal, modal-vm, VercelA saved filesystem snapshot can be restored into a new sandbox after shutdown. Modal can also snapshot after a turn; modal-vm and Vercel skip those captures.
Daytona, E2B, BoatThe retained sandbox resumes in place after being stopped (Daytona), paused (E2B), or archived to a disk snapshot (Boat).

The status labels are the same on both models. See Sandbox providers.

Sandbox warming

When you start typing in the new-session composer, OpenInspect begins warming a sandbox for the selected target and model, so it may already be ready by the time you send the prompt. Changing the target or model starts a new warm-up and retires the previous one. The sandbox shows Warming... while this happens.

Archive, restore, and cancel

  • Archive a session from its row menu in the sidebar. The dialog reads "Archive this session? You can restore archived sessions from Settings > Data Controls." Archived sessions leave the inbox and cannot be prompted.
  • Restore an archived session under Settings › Data Controls with Unarchive, or find it on the Sessions page with the Lifecycle filter set to Archived. Restoring requires lifecycle permission. Archived child sessions must also be restored before a parent can send them a follow-up.
  • Cancel is terminal. A cancelled session closes any unfinished prompts and does not accept new ones. To continue that work, start a new session.
  • Delete is not available: the web app has no delete control, so sessions are archived, not deleted, and an archived session can always be restored from Settings › Data Controls.

Troubleshooting

SymptomCauseFix
The prompt failed with a message naming a boot phaseThe boot budget, connect watchdog, or heartbeat trippedSend the prompt again; it starts a new sandbox. If setup.sh is slow, shorten it or enable a prebuilt image.
The Sessions page says Completed but the session header shows ReadySession and sandbox statuses are separate levelsNothing is wrong. The sandbox stays attached until it idles out.
The session shows StoppedThe sandbox idled past the inactivity timeoutSend a prompt. The sandbox restores from its last snapshot or resumes in place.
A follow-up is refused on an archived sessionArchived sessions do not accept promptsUnarchive it under Settings › Data Controls, then send the prompt.

Next steps

On this page