Session lifecycle
Open, pause, resume, and delete a retained environment.
A session persists until you delete it. Commands, agent runs, and SSH connections can finish while the VM and disk remain allocated.
| SDK operation | Behavior in the current implementation |
|---|---|
client.sessions.open({name}) | Create or locate the owner's named session and make it ready |
client.sessions.get(id) | Retrieve a session handle and current metadata |
session.pause() | Pause the VM while retaining its disk and session files |
session.resume() | Start or resume the VM and verify its filesystem mount |
session.delete() | Permanently delete the VM, session filesystem, and session record |
Opening and readiness
The runtime validates resource ownership, starts or resumes the VM when needed, and checks the session filesystem mount before returning from open or resume. An existing session name keeps its identity; requesting a different image for that name returns session_image_mismatch.
Each session uses one exclusive writable mount on its primary VM. Mount readiness checks establish where operations will run; they do not prove that later writes have been flushed to durable storage.
session.info is the last metadata received by the handle. Use await session.refresh() to obtain current state. The possible states are starting, running, paused, stopped, error, and deleting.
Idle compute
New VMs are configured with a 15-minute automatic pause interval, automatic stop disabled, and automatic deletion disabled. The VM runtime determines idle activity. Automatic idle pause and process survival require separate live checks against the selected VM images.
Managed commands, file operations, new SSH grants, and provided-agent requests require a running session. Resume first after an idle pause. Fetching a handle with sessions.get(id) retrieves metadata without resuming compute. Ending an output stream does not cancel a managed command: call execution.cancel() and then execution.wait() when you intend to stop it.
Concurrent access
Only one managed command can run in a session at a time. A running command also blocks file API writes and lifecycle changes with execution_busy.
A provided-agent request reserves the session for its whole conversation. Other managed commands, file API writes, and lifecycle changes are blocked until it finishes; agent_busy identifies that reservation. Read operations remain available.
SSH connections and the processes they launch are outside this managed-command coordination. Finish or stop those processes before pausing, deleting, or editing the same files from another harness.
Recovery
The service retains resource identities and checks them before reuse. If command completion becomes uncertain, its execution remains reserved until recovery confirms the process has stopped. The event stream reports execution_unsettled.
VM-local software needs a reproducible image or setup recipe, and the public API has no automatic replacement endpoint. Read Persistence before choosing what to store on each disk.
Coordinate shutdown or replacement with the service operator to retain project files. Writers must stop, application buffers must be flushed, and the operator's clean-unmount procedure must complete. The pause route keeps the mount attached; it does not perform that clean-unmount step or flush arbitrary application buffers.
Permanent deletion
session.delete() removes both compute and the backing session filesystem. There is no restore endpoint or retention window in this API. Use pause to retain a session for later.