Workspaces

Suspend the workspace if it stays idle for after_seconds from now (e.g. at the end of an agent turn)

Records a deferred suspend for the cell’s idle loop: once the workspace has been idle for after_seconds (0..3600; 0 = as soon as it is idle), it is suspended (within a few seconds of activity flush grace), at not_before (= now + after_seconds) at the earliest. A tool call after the request (the next turn) or a resume cancels it for good. Other work only defers it: a command still running, an attached exec/PTY stream or a keepalive postpones the suspend until after_seconds after it ends. It applies under every idle policy (never included) and only ever shortens the policy’s wait; a policy that suspends sooner still does. Repeating replaces the pending request (the new requested_at counts); DELETE cancels it; idle.suspend_request on the workspace shows it. 202 {workspace, operation: null, suspend_request}; when a suspend is already in progress, 202 {workspace, operation: that suspend, suspend_request: null} and nothing is recorded. The suspend, when it happens, is a system suspend operation with input.reason requested_after_idle (input.requested_at, input.after_seconds). Errors: 409 session_lifetime, workspace_deleted, operation_in_progress (another lifecycle operation is active), not_running, not_supported_for_mode (file-first). Supports Idempotency-Key.

post/v1/workspaces/{workspace_id}/suspend-when-idle

Request

  • Base URL: https://api.shardflux.dev
  • URL: https://api.shardflux.dev/v1/workspaces/{workspace_id}/suspend-when-idle
  • Auth: HTTP bearer

Path parameters

workspace_idstring uuid required

UUIDv7, lowercase canonical form.

Request body

after_secondsinteger required

Seconds from now the workspace must stay idle before it is suspended (0..3600; 0 = as soon as it is idle).

Response

suspend_request: the recorded request. operation: set (and suspend_request null) only when a suspend was already in progress.

Changes

No recorded changes to this operation across all 1 revision of this API.