Workspaces

Set or clear the workspace idle policy (automatic suspend)

idle_policy: adaptive (the learned timeout), never, or fixed:<seconds> (60..604800); null clears it so the template default (else adaptive) applies. Work signals always win: a running command, an attached session or a keepalive keeps the workspace running. Applies from the idle loop’s next evaluation. 409 session_lifetime for session workspaces (they end after their idle timeout), 409 not_supported_for_mode for file-first workspaces (never suspended), 409 workspace_deleted. Returns the workspace.

put/v1/workspaces/{workspace_id}/idle-policy

Request

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

Path parameters

workspace_idstring uuid required

UUIDv7, lowercase canonical form.

Request body

idle_policystring nullable required

adaptive (the learned timeout, default), never, or fixed:<seconds> (60..604800).

Response

Default Response

secret_redaction_requiredboolean

Bound secrets require tool-call capture redaction inside the guest before storage.

idstring uuid required

UUIDv7, lowercase canonical form.

organization_idstring uuid required

UUIDv7, lowercase canonical form.

project_idstring uuid required

UUIDv7, lowercase canonical form.

workspace_keystring required
labelsobject required

Searchable workspace metadata; not secrets. At most 50 labels.

template_version_idstring uuid required

UUIDv7, lowercase canonical form.

desired_state'running' | 'suspended' | 'deleted' required
observed_state'creating' | 'starting' | 'running' | 'suspending' | 'suspended' | 'resuming' | 'forking' | 'stopping' | 'failed' | 'deleting' | 'deleted' required
cell_idstring nullable required
cell_endpointstring nullable required

Cell gateway base URL when placed and resolvable.

ownership_epochinteger required
grantsobject nullable required

Actual grants reported by the cell; live memory allocation overrides the last successful start.

pending_reasonstring nullable required

Why the active operation is waiting (capacity_pending reason), else null.

forked_from_workspace_idstring uuid nullable required

UUIDv7, lowercase canonical form.

disk_layout'legacy' | 'layered' required

legacy: one disk (template copy + changes). layered: the template chain read-only plus a workspace layer holding only the changes. Immutable.

lifetime'persistent' | 'session' required

persistent: kept until deleted (default). session: discarded when the session ends (close(), idle timeout or draft discard;).

purpose'standard' | 'template_draft' | 'template_test' required

standard, template_draft (a template’s dev-mode draft) or template_test (a test instance of a draft state;).

idle_timeout_secondsinteger nullable required

Sessions only: the session ends after this long without activity (template default, else 600). Null for persistent workspaces.

ended_reason'closed' | 'idle_timeout' | 'draft_discarded' nullable required

How a session ended (closed, idle_timeout, draft_discarded); null otherwise.

dev_template_idstring uuid nullable required

UUIDv7, lowercase canonical form.

mode'processful' | 'file_first' required

processful (default): one VM keeps processes, memory and files between calls; it can be suspended, resumed and forked. file_first: the state is a versioned file tree (tree_revision); there is no VM between executions, each exec runs in a fresh VM and publishes the changed files as the next revision, nothing but files survives an execution. A file-first workspace is ready (running) from creation and is never suspended; suspend, resume, snapshot, fork, reset, save-as-template, volumes and idle policies are 409 not_supported_for_mode. Immutable.

tree_revisioninteger required

file_first: the latest revision of the file tree (0 = the empty tree the workspace starts with; each mutating file call or execution publishes the next one; cell file responses carry it as X-Tree-Revision). Always 0 for processful workspaces.

upgrade_pendingobject nullable

The pinned upgrade target awaiting its cold start.

created_atstring date-time required

RFC 3339 UTC timestamp with Z.

updated_atstring date-time required

RFC 3339 UTC timestamp with Z.

deleted_atstring date-time nullable required

RFC 3339 UTC timestamp with Z.

Changes

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