Session lifecycle and statuses
What each session and sandbox status means, how a sandbox boots, and when work is saved.
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
| Status | Label in the Sessions list | Meaning | Can accept a prompt |
|---|---|---|---|
created | Draft | The session exists but no prompt has been dispatched yet. | Yes |
active | Active | A prompt is pending or processing. | Yes (it is queued behind the running turn) |
completed | Completed | The last run finished successfully and nothing is queued. | Yes |
failed | Failed | The last run ended in an error and nothing is queued. | Yes |
archived | Archived | You archived the session. It is hidden from the inbox. | No, restore it first |
cancelled | Cancelled | The 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:
| Status | Label | What it means |
|---|---|---|
pending | Pending | Waiting for the sandbox to start. |
warming | Warming... | Preparing sandbox capacity. |
spawning | Starting... | Creating or restoring the sandbox. |
connecting | Connecting... | The runtime has connected and the boot is under way. |
ready | Ready | The sandbox is available and prompts dispatch. |
snapshotting | Saving... | A sandbox snapshot is being saved. |
stopped | Stopped | The sandbox stopped; the next prompt can restore or resume saved state. |
stale | Unresponsive | The sandbox runtime stopped responding. |
failed | Failed | The 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.
| Path | When it is used | Phases you see |
|---|---|---|
| Fresh start | First sandbox for a repository with no prebuilt image and no snapshot | Cloning, setup.sh, services, skills, agent |
| Prebuilt image | The 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 restore | A later prompt in a session that already has a saved snapshot | Services, 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.shis reported as a warning and the boot continues. - A
.openinspect/start.shfailure in the session's first repository ends the boot. On a prebuilt image start, a failingstart.shfails 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:
| Bound | Default | What it covers |
|---|---|---|
| Connect watchdog | 4 minutes | From sandbox creation until the runtime first connects. This is the provider launching the container, not your scripts. |
| Boot budget | 30 minutes | From sandbox creation until the sandbox is ready. Your operator can change it with SANDBOX_BOOT_TIMEOUT_MS. |
| Heartbeat | 90 seconds | A runtime that stops sending heartbeats during boot is treated as dead. |
When any of these trips:
- The sandbox is marked failed and its credentials are revoked.
- 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). - No snapshot is taken, so a half-provisioned workspace never becomes the restore point.
- 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:
| Provider | Resume model |
|---|---|
| Modal, modal-vm, Vercel | A 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, Boat | The 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
| Symptom | Cause | Fix |
|---|---|---|
| The prompt failed with a message naming a boot phase | The boot budget, connect watchdog, or heartbeat tripped | Send 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 Ready | Session and sandbox statuses are separate levels | Nothing is wrong. The sandbox stays attached until it idles out. |
| The session shows Stopped | The sandbox idled past the inactivity timeout | Send a prompt. The sandbox restores from its last snapshot or resumes in place. |
| A follow-up is refused on an archived session | Archived sessions do not accept prompts | Unarchive it under Settings › Data Controls, then send the prompt. |