Freeze and thaw sessions
Freeze stops one managed agent process while retaining its native conversation, account, launch profile, applied session settings and last terminal screen. Hide only changes presentation; Detach leaves the process running. Freeze is neither a memory snapshot nor a new blank conversation.
Select a session in Projects and press Shift+F, or use Freeze in web or desktop. Confirm the action. The controller captures the terminal before stopping the exact process, and finishes the workflow even after the client disconnects. The Frozen tab contains saved sessions, operations in progress and retryable failures. Empty Frozen, Hidden and Quota tabs are omitted; Quota remains last.
Open a frozen card to scroll its saved screen. Thaw resumes its original native conversation, agent, account and profile. An exhausted account is never silently replaced. Continue with another account / agent uses the existing import or saved-handoff workflow to create a separate continuation, retaining the original. Native conversation copying supports Claude and Codex; other clients need a supported saved handoff for cross-client continuation. Freeze requires verified native resume and an exact conversation ID.
Stops are bound to container ID, PID, UID, kernel start ticks, execution scope and process generation. Sibling processes are not killed. Automatic exit cleanup skips frozen sessions. Delete or thaw frozen sessions before deleting their project or container. Capture failures do not stop the process. Stop/resume failures retain the history.
Delete a frozen session permanently
Open a Frozen card and choose Delete permanently, or select the session and press k. The shared TUI, web and desktop confirmation names the session and states what remains. Press Shift+K or click the confirmation to delete. Enter does not confirm this action; Escape keeps the session.
Deletion removes the logical session, Frozen card, saved controller terminal
screen and Freeze recovery record. It works without thawing or starting an absent
container. It never stops siblings or queues a host shutdown. The server requires
the exact reviewed freezeId, a confirmed stopped provider, no observed matching
process and no pending Freeze/Thaw lifecycle work. A failed stop cannot be
discarded as though it succeeded. A failed Thaw requires its completion receipt
and fresh host inventory showing the provider is absent.
Repository files, account data, native transcripts, accounting and audit history remain. Host recovery staging and S3 workspace archives may contain sibling data and are retained under the existing storage retention policy. Delete permanently does not claim to erase those shared/native data. A durable, owner-scoped deletion receipt records these retained-data limits without keeping the controller terminal screen. Receipts are keyed by Freeze ID so reuse of a session name does not overwrite earlier archive-cleanup references.
Session sharing links are revoked. Pending permission deliveries, notices and session-bound commands receive trusted controller cancellation receipts; approvals and queued configuration plans are retired. Late host replies cannot restore an old permission or alter a replacement session. Old creation-request IDs remain conflict tombstones and cannot silently recreate the deleted session. Deletion also advances a durable credential epoch for that logical session ID. An old MCP token remains revoked if the name/account is reused. Tokens and broker namespaces stay stable for unrelated live sessions and for the replacement's own lifetime; no global key or running sibling session is rotated.
Temporary machines and S3
Sandbox compute and hosts explicitly enrolled as temporary for Overnight require storage configured in Integrations / Overnight. Missing archive storage or credentials must be resolved before the agent stops. The original storage revision and encryption key stay bound to the saved operation.
The host archives managed repositories/worktrees, interchange, native history, session home and terminal/session metadata. It briefly pauses the workspace and associated nested Docker only while creating the local encrypted snapshot. It releases the pauses before uploading to S3, and also on failure. Other agent processes are preserved. Existing archive rules exclude credential files and generated dependency caches.
This is not an entire-machine backup. External volumes, databases, container writable layers, background processes and RAM need their own persistence strategy. After the last active session freezes, the controller stops its workspace container, nested Docker and egress gateway. A session waiting for input still counts as active. The host rechecks native processes before an automatic stop; new launches wait for that stop to finish. Persistent workspace files are retained.
Thaw prepares the container before it launches the original conversation. It reuses a compatible retained container or creates one if the old container was removed. A legacy container that cannot enforce the current Internet policy is recreated only after every other session has stopped or frozen. Frozen session files are excluded from restart cleanup. Startup must be acknowledged by the host before the provider launch is queued. Failures retain the saved screen and native history for retry; no blank replacement conversation is started.
Large managed configurations use stdin during preparation, avoiding the shell argument-size limit. Preparation reports its stage on failure and keeps the frozen conversation available for retry. Resource-network migration retains existing bridges and chooses an available subnet for a restricted replacement. A retained legacy bridge can remain connected while the restricted bridge receives its own allocation.
Payloads use AES-256-GCM. The private recovery index is
<archive-prefix>/frozen/owners/<user-id>/index.json. It identifies encrypted
objects, sessions, workspace roots and checksums, without storage credentials or
terminal text. The controller independently verifies the object and index before
marking Frozen. Automatic sandbox completion cleanup waits for verification;
provider-imposed expiration remains independent of devctrl.
Thaw prefers retained local files when its journal and roots remain. Otherwise it authenticates the archive before promoting missing files. Newer files are retained; symlink/special-file destinations are rejected. Stop siblings before recovering files in their shared workspace. Reauthorize credentials after data loss.
For an S3-backed session, select another enrolled online host in the Freeze panel
or pass hostId to Thaw. All sessions in the source container must be S3-frozen,
with no observed live processes. Authorize the original account on the destination
first. Recovery retains the managed root mapping: storage paths and permissions
must be compatible. It does not provision a cloud VM or copy account secrets.
Freeze does not shut down the source host; Overnight and sandbox lifetimes retain
their own lifecycle rules. Configure S3 lifecycle retention for old archives.
CLI, API and MCP
devctrl session freeze '<session-id>'
devctrl session freeze-status '<session-id>'
devctrl session thaw '<session-id>'
devctrl session thaw '<session-id>' --host '<recovery-host-id>'
devctrl session delete-frozen '<session-id>' --freeze-id '<reviewed-freeze-uuid>' --confirm
devctrl session deletion-status '<session-id>'
POST /v1/sessions/:id/freeze, body{}: accept or retry Freeze.GET /v1/sessions/:id/freeze: summary and bounded terminal snapshot.DELETE /v1/sessions/:id/freeze: cancel a failed capture or rejected stop before the provider process has stopped. Saved freezes cannot be discarded this way.POST /v1/sessions/:id/thaw, body{}or{"hostId":"recovery-host"}: resume the original conversation.DELETE /v1/sessions/:id, body{"freezeId":"reviewed-freeze-uuid"}: permanently delete the Frozen record after explicit confirmation. The ordinary stopped-session cleanup path is preserved for sessions that are not frozen.GET /v1/sessions/:id/freeze/deletion: latest durable deletion/retained-data receipt; optionalfreezeIdquery selects an earlier Freeze receipt.
Only authenticated execution hosts can read their active archive lease. Console
snapshots contain the summary; terminal text loads separately, including through
the previews endpoint. Ownership checks apply to every action and snapshot.
Public session links cannot thaw or restart a session. Operator/Control Room MCP
discovers and invokes these routes through the existing operation catalog.
For permanent deletion, inspect GET /v1/sessions/:id/freeze, review the retained
data limits with the user, then pass its exact freeze.id in the DELETE body.
Ordinary project MCP gains no server-wide rights.
Tests cover exact stops, siblings, stop receipts, controller restarts, quotas, native resume failures, capture races, encrypted S3 round trips, index checks, retry journals, credential exclusion, newer files, owner boundaries and the shared TUI/browser controls.