--- title: "Open a workspace by key (create on first use, reconnect or resume afterwards)" method: POST path: "/v1/workspaces/open" tags: ["Workspaces"] --- # Open a workspace by key (create on first use, reconnect or resume afterwards) `POST /v1/workspaces/open` ## Request - Base URL: `https://api.shardflux.dev` - URL: `https://api.shardflux.dev/v1/workspaces/open` - Auth: HTTP bearer like names a live workspace ID or key in the caller’s project; a new key inherits its exact template version, caps, inputs, secrets, volumes, idle policy and agent options on a fresh disk. Explicit caps, inputs, secrets, volumes and policy override the inherited values. volumes supplied replaces the set, omitted retains it. Replacement returns 202 with one normal volume_attach/volume_detach operation at a time; after it succeeds repeat open with the same set and a fresh Idempotency-Key until ready. SDKs do this when waiting. New keys resolve `template` to its latest published version; reopening never changes or resets the workspace (the response reports the template version actually used). 200 when the workspace is already running and ready (with `cell_endpoint` and a tool token); otherwise 202 with the operation to poll. A running workspace whose startup failed (`startup.state` failed) is not ready: the open is 202 with an `open` operation (input.startup_retry) that runs the failed step again. Concurrent opens of one key share one workspace and one operation. `secrets` (optional) binds secret names injected into every exec/PTY start: it sets the binding of a new key and replaces it on an existing key (omitted = unchanged); an unknown or unusable name is 422 details.reason secret_not_available with details.names (nothing is created or changed). The template version’s secret inputs join the binding on create and whenever `secrets` is given; a required one this workspace may not use is 422 input_required (details.kind secret); a bound name equal to a template env key or text input is 422 env_collision (details.name). `inputs` (optional): the version’s text inputs {NAME: string}; stored on create (else the declared default) and replaced on an existing key (omitted = unchanged); 422 input_unknown, input_invalid or input_required (details.names). `lifetime`: omitted = the version’s default (else persistent); `session` workspaces are discarded when the session ends (close(), idle timeout), after which the key opens a NEW workspace; reopening a live key with another lifetime is 409 lifetime_mismatch. A new workspace is `layered` when its version supports it and layered opens are enabled (`disk_layout`). Errors: 404 template/key outside scope, 402 `entitlement_required`, 403 `quota_exceeded` (details.limit retained_state), 429 `quota_exceeded` (details.limit concurrent_workspaces; see below), 409 operation in progress, key whose deletion is still in progress (workspace_deleted) or lifetime_mismatch, 422 reserved_key_prefix (keys starting with sf:). Supports Idempotency-Key. Held open: with `Prefer: wait=` (at most 20) an open whose outcome is an operation is held until the operation is terminal or the wait elapses; success answers 200 with the running workspace, the succeeded operation and a tool token (`Preference-Applied: wait=`), anything else 202 with the fresh operation. Without `Preference-Applied` the server did not wait: poll the operation. `mode`: omitted = processful for a new key and the stored mode for an existing one; `file_first` creates a workspace whose state is a versioned file tree with no VM between executions: it is ready at once (200 with a tool token, `observed_state` running, `tree_revision` 0, no operation), needs a layered template version (409 layout_unsupported otherwise) and is persistent (`lifetime: session` or `idle_policy` with it are 422 not_supported_for_mode); each open of a file-first key re-resolves the size of its execution VMs from `caps`, the template and the plan. 422 mode_not_available while the deployment does not offer file-first workspaces; reopening a key with another mode is 409 mode_mismatch. `tool_token` is null when the principal’s tool-token rate limit is used up: the open still succeeds, and the client fetches a token from POST /workspaces/{id}/tool-tokens. Plan concurrency: a start the plan’s concurrent_workspaces limit refuses is queued on the request (up to 10 s) and admitted as soon as one of the organization’s workspaces frees; if none does, 429 `quota_exceeded` with `Retry-After: 2` (retryable; details limit concurrent_workspaces, limit_value, current, retry_after_seconds, plan). Nothing was created: retry after Retry-After, with the same Idempotency-Key or a new one. With `Prefer: wait` the queued time counts against the wait. Memory allocation: caps.allocation_mode elastic with caps.memory_mib_held; 422 validation_failed details.field caps.allocation_mode reason allocation_mode_not_available (the organization lacks elastic memory; nothing is created or changed), reason not_supported_for_mode (file_first); details.field caps.memory_mib_held reason requires_elastic (held without elastic) or exceeds_memory_mib (held above caps.memory_mib). ## Headers - `prefer` string ## Request body - object - `key` string, required: Stable workspace key, unique per organization (e.g. `${customerId}/${projectId}`). - `labels` object: Searchable workspace metadata; not secrets. At most 50 labels. - `template` string: Template slug or slug@version. A slug uses the latest published version; an exact reference selects that published, unarchived version for a new key. - `like` string: Stable workspace key, unique per organization (e.g. `${customerId}/${projectId}`). - `volumes` object: Guest mount path → project volume name or {name, mode}. Supplied replaces the set; omitted retains it. Volumes must be available. - `caps` object: Optional user caps; the ceiling is min(template, cap, plan). Absent fields add no restriction. Given caps replace the stored ones (a reopen keeps an elastic workspace’s mode when elastic is the organization’s default and allocation_mode is omitted). - `cpu_millis` integer - `memory_mib` integer: Fixed: size in MiB; omitted uses the template default (template defaults.memory_mib, else manifest default_caps.memory_mib_base, else 1024), bounded by plan and template. Elastic: maximum memory promise. - `disk_gib` integer: Disk (GiB) for the workspace's own changes, bounded by plan and template. A new workspace without it starts at the template's default disk (manifest default_caps.disk_gib, 20 GiB on the platform templates), or, opened from your saved machine or project template, at the disk of the workspaces it was saved from when that is larger; grow it later with a resize. A reopen without it keeps the disk. - `allocation_mode` 'fixed' | 'elastic': Memory allocation: fixed boots memory_mib (the template default when omitted) and holds it; elastic makes memory_mib a promise: the VM holds memory_mib_held while idle and is grown towards the promise when a command needs it. Needs the elastic memory entitlement (422 details.reason allocation_mode_not_available). A promise that does not exceed the held floor by at least 512 MiB is fixed at the promise (the response caps say which). Omitted: fixed, or elastic where that is the organization’s default (a reopen then keeps the stored mode). Takes effect at the next VM start. - `memory_mib_held` integer: Elastic only: memory held while idle (MiB, default 1024, at most memory_mib). - `project_id` string, uuid: UUIDv7, lowercase canonical form. - `agent_label` string: Attribution label; one agent session per (workspace, principal, label). - `tools` string[] - `secrets` string[]: Secret names bound to the workspace (max 50, unique): injected as environment variables into every exec and PTY start (terminal sessions included), together with the call’s own `secret_refs`. Each must name a live secret this workspace may use (its project, its id, and allowed_tools including exec and pty), else 422 details.reason secret_not_available with details.names. - `agent_credentials` boolean - `inputs` object: Open-time inputs of the template version: {NAME: string} for its declared text inputs. A new workspace stores each given value, else the declared default; on an existing key `inputs` replaces them all (omitted = unchanged). Secret inputs are not passed here: they bind the stored secret of the same name. 422 input_unknown (undeclared name, details.names), input_invalid (a secret input, a non-string, or a value over 4096 bytes or with CR, LF or NUL; details.names), input_required (details {names, kind}). - `lifetime` 'persistent' | 'session': persistent: kept until deleted (default). session: discarded when the session ends (close(), idle timeout or draft discard;). - `agent_idle_grace_seconds` integer - `agent_reachable_seconds` number: Deprecated; accepted and ignored. Claude conversations stay reachable without a time limit. - `idle_policy` string: adaptive (the learned timeout, default), never, or fixed: (60..604800). - `retention` object - `delete_after_idle_days` integer, required - `mode` 'processful' | 'file_first': 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. - `computer_use` boolean, nullable: : the workspace’s computer use switch (null follows the template); set on create, replaced on an existing key when given. ## Response `200` 200: running and ready (tool_token set). 202: poll `operation` (GET /operations/{id}). - object: 200: running and ready (tool_token set). 202: poll `operation` (GET /operations/{id}). - `workspace` Workspace, required - `secret_redaction_required` boolean: Bound secrets require tool-call capture redaction inside the guest before storage. - `agents` Agent[] - `id` string, required - `workspace_id` string, uuid, required: UUIDv7, lowercase canonical form. - `workspace_key` string, required - `app` union, required - 'claude' - 'codex' - `state` union, required - 'working' - 'waiting' - 'exited' - `since` string, date-time, required: RFC 3339 UTC timestamp with Z. - `title` string, required - `remote_control_url` string, required - `last_message` string, required: The session's latest message as one line of plain text: the agent's last reply when it waits or exits, its latest text while it works. Empty until it says one. - `labels` object, required - `conversation_id` string, nullable: The session's own conversation: the one whose harness session it is, else its computer's only live conversation. Several threads can share one computer, so prefer it over labels.shard_conversation, which names the computer's first conversation. Null when it cannot be told; absent before conversations exist. - `orchestrator_conversation_id` string, nullable - `orchestrator_input_id` string, nullable - `settled_reason` union: The conversation computer suspended or failed while a native turn was active. Null or absent does not establish completion. - 'computer_suspended' - 'computer_failed' - `credential_status` union - 'ready' - 'needs_sign_in' - `id` string, uuid, required: UUIDv7, lowercase canonical form. - `organization_id` string, uuid, required: UUIDv7, lowercase canonical form. - `project_id` string, uuid, required: UUIDv7, lowercase canonical form. - `workspace_key` string, required - `labels` object, required: Searchable workspace metadata; not secrets. At most 50 labels. - `retention` object, nullable - `delete_after_idle_days` integer, required - `delete_at` string, date-time, nullable, required - `template_version_id` string, uuid, required: UUIDv7, lowercase canonical form. - `template` object, required: The workspace’s current template base (changed only by an explicit upgrade), and the version its immutable paths show. - `version_id` string, uuid, required: UUIDv7, lowercase canonical form. - `template_id` string, uuid, required: UUIDv7, lowercase canonical form. - `slug` string, required - `version` integer, required - `immutable_version` integer, nullable, required: Immutable paths: the template version whose read-only content the workspace has mounted at the template’s immutable paths. It follows the template’s newest published version at a cold boot or a resume. null when the workspace mounts none (its version declares no immutable paths, a draft or a test instance, or not booted yet). - `desired_state` 'running' | 'suspended' | 'deleted', required - `observed_state` 'creating' | 'starting' | 'running' | 'suspending' | 'suspended' | 'resuming' | 'forking' | 'stopping' | 'failed' | 'deleting' | 'deleted', required - `cell_id` string, nullable, required - `cell_endpoint` string, nullable, required: Cell gateway base URL when placed and resolvable. - `ownership_epoch` integer, required - `caps` object, required: CPU and memory user caps (null = no user restriction), the effective disk cap, and the memory allocation mode. - `cpu_millis` integer, nullable, required - `memory_mib` integer, nullable, required - `disk_gib` integer, nullable, required: Requested disk cap (GiB), bounded by the admitted plan/template ceiling and acknowledged VM disk. Null means no user disk restriction. - `allocation_mode` 'fixed' | 'elastic', required: Memory allocation: fixed (default) boots memory_mib and holds it; elastic holds memory_mib_held while idle and is grown up to memory_mib (the promise) when a command needs it. The mode the next VM start uses: an elastic request whose promise does not exceed the held floor by at least 512 MiB is fixed at the promise. - `memory_mib_held` integer: Elastic only: the memory held while idle (MiB). - `memory` object, required: Memory of the workspace. - `allocation_mode` 'fixed' | 'elastic', required: The layout of the running VM, else the one the next start uses. - `promised_mib` integer, nullable, required: The memory the workspace may use (MiB): the running allocation, else the last admitted size; null before the first start. - `held_mib` integer, nullable, required: The memory held while idle (MiB): the elastic floor; equal to promised_mib for fixed. - `plugged_mib` integer, nullable, required: Elastic and running: the memory currently plugged above the held floor (MiB, from the host’s latest report); null otherwise. - `ceilings` object, nullable, required: Effective per-workspace ceilings computed at the last admission (start/resume/fork). - `cpu_millis` integer, required - `memory_mib` integer, required - `disk_gib` integer, required - `sources` object, required: Which input bounded each ceiling: min(template, user cap, plan cap). - `cpu_millis` 'template' | 'user' | 'plan', required - `memory_mib` 'template' | 'user' | 'plan', required - `disk_gib` 'template' | 'user' | 'plan', required - `resolved_at` string, date-time, required: RFC 3339 UTC timestamp with Z. - `grants` object, nullable, required: Actual grants reported by the cell; live memory allocation overrides the last successful start. - `storage_recovery` object: Files stored independently of compute. Resume restarts processes from the kept filesystem. - `state` 'stored', required - `reason` 'maintenance', required - `copy_id` string, uuid, required: UUIDv7, lowercase canonical form. - `files_kept` true, required - `message` string, required - `active_operation` Operation, required - `id` string, uuid, required: UUIDv7, lowercase canonical form. - `kind` 'open' | 'suspend' | 'resume' | 'fork' | 'snapshot' | 'restore' | 'delete' | 'move' | 'resize' | 'upgrade' | 'volume_create' | 'volume_attach' | 'volume_detach' | 'volume_delete' | 'reset' | 'layer_snapshot', required - `state` 'queued' | 'capacity_pending' | 'running' | 'succeeded' | 'failed' | 'canceled', required - `workspace_id` string, uuid, nullable, required: UUIDv7, lowercase canonical form. - `volume_id` string, uuid, nullable: UUIDv7, lowercase canonical form. - `created_at` string, date-time, required: RFC 3339 UTC timestamp with Z. - `updated_at` string, date-time, required: RFC 3339 UTC timestamp with Z. - `started_at` string, date-time, nullable: RFC 3339 UTC timestamp with Z. - `completed_at` string, date-time, nullable: RFC 3339 UTC timestamp with Z. - `state_reason` string, nullable: Closed reason code while waiting (e.g. capacity_pending: no_ready_host). - `input` object - `error` object - `result` object - `durable` boolean: suspend and fork: whether the capture is in durable storage. false while `durability.state` is pending (the suspend completed on its host) or lost; true once it committed. Absent on other kinds. - `suspend_path` string: suspend: `local_commit` when the suspend completed on its host and the durable copy followed in the background. - `durability` object - `state` 'pending' | 'durable' | 'lost', required: pending: sealed on its host, the durable copy is being written; durable: the copy committed; lost: the copy could not be made and the previous recovery point stays current. - `checkpoint_id` string: The checkpoint being made durable. - `generation_id` string: Its generation on the host. - `local_commit_at` string: RFC 3339: when the suspend (or fork) completed on its host. - `durable_by` string: RFC 3339: when the durable copy is expected to have committed (local_commit_at + the deadline). - `durable_at` string: RFC 3339 (state durable): when the durable copy committed. - `local_commit_to_durable_ms` number: State durable: local_commit_at to durable_at, in milliseconds. - `overdue_at` string: RFC 3339: set once durable_by passed while the copy was still pending; it keeps retrying. - `reason` string: State lost: why, e.g. host_lost. - `code` string: State lost: the error code of the failed copy. - `recovery_point_checkpoint_id` string, nullable: State lost: the durable checkpoint that stays the recovery point (null when there is none). - `lost_suspend` object - `checkpoint_id` string, required: The suspend checkpoint whose durable copy was lost. - `generation_id` string: Its generation on the host. - `reason` string: Why it was lost, e.g. host_lost. - `suspended_at` string: RFC 3339: when that suspend captured the workspace. - `restored_checkpoint_id` string: The earlier durable checkpoint this resume restored. - `state_as_of` string: RFC 3339: when the restored checkpoint committed; the workspace state is as of then. - `host_lost` object - `detected_at` string, required: RFC 3339: when the host failure was detected; the workspace was suspended then. - `restored_from` 'disk' | 'checkpoint': resume and open: disk when the workspace booted from its disk (files kept, processes and memory not); checkpoint when it was restored from its newest checkpoint (see state_as_of). Absent on a suspend. - `restored_checkpoint_id` string: restored_from checkpoint: the checkpoint this resume restored. - `state_as_of` string: restored_from checkpoint, RFC 3339: when that checkpoint committed; the workspace state is as of then. - `progress` SuspendProgress - `operation_id` string, uuid, required: UUIDv7, lowercase canonical form. - `state` 'queued' | 'capacity_pending' | 'running' | 'succeeded' | 'failed' | 'canceled', required - `workspace_state` 'creating' | 'starting' | 'running' | 'suspending' | 'suspended' | 'resuming' | 'forking' | 'stopping' | 'failed' | 'deleting' | 'deleted', required - `phase` string, required: Actual snapshot preparation/capture phase, or an explicitly unavailable control status. - `cancelable` boolean, required: True only while the host can acknowledge cancellation before its capture cut. - `supported` boolean, required - `safe_action` 'wait_for_terminal' | 'resume' | 'retry_tools' | 'inspect_failure', required - `phase_started_at` string, date-time: RFC 3339 UTC timestamp with Z. - `deadline_at` string, date-time: RFC 3339 UTC timestamp with Z. - `accepted` boolean - `pending_reason` string, nullable, required: Why the active operation is waiting (capacity_pending reason), else null. - `forked_from_workspace_id` string, 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_seconds` integer, nullable, required: Sessions only: the session ends after this long without activity (template default, else 600). Null for persistent workspaces. - `idle` object, nullable, required: Automatic suspend of a persistent workspace. Null for session workspaces. - `policy` string, required: The effective policy: adaptive, never or fixed:. - `source` 'workspace' | 'template' | 'default', required: Where the policy comes from. - `mode` 'adaptive' | 'fixed' | 'never', required - `timeout_seconds` integer, nullable, required: The timeout applied to the current idle period while the workspace runs (as of the idle loop’s last decision), else null. - `basis` string, nullable, required: What the timeout comes from, e.g. "learned from 37 idle periods (active-hours)", "template prior", "default". - `next_eligible_at` string, date-time, nullable, required: When the workspace becomes eligible for automatic suspend if nothing happens before (work signals always win). - `suspend_request` SuspendRequest, required: A pending suspend-when-idle request: once the workspace has been idle for after_seconds, it is suspended. A tool call after requested_at (the next turn) or a resume cancels it; other work only defers it. - `requested_at` string, date-time, required: When the request was made; a newer request replaces it. - `after_seconds` integer, required - `not_before` string, date-time, required: requested_at + after_seconds: the earliest suspend (within a few seconds of activity flush grace after it). A running command, an attached stream or a keepalive still active then defers the suspend until after_seconds after it ends. - `origin` union, required: Where the workspace’s disk came from; null for a workspace opened from its template. - object: Forked from workspace_id. - `kind` 'fork', required - `workspace_id` string, uuid, required: UUIDv7, lowercase canonical form. - object: A test instance of a draft state: the draft and the captured state (checkpoint_id is null until the cell placed an instance whose state is being captured). - `kind` 'draft_state', required - `template_id` string, uuid, required: UUIDv7, lowercase canonical form. - `draft_workspace_id` string, uuid, required: UUIDv7, lowercase canonical form. - `checkpoint_id` string, uuid, nullable, required: UUIDv7, lowercase canonical form. - `captured_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z. - object: A test instance of a template version, published or not: a fresh workspace on that version. - `kind` 'template_version', required - `template_id` string, uuid, required: UUIDv7, lowercase canonical form. - `version` integer, required - `ended_reason` 'closed' | 'idle_timeout' | 'draft_discarded', nullable, required: How a session ended (closed, idle_timeout, draft_discarded); null otherwise. - `dev_template_id` string, uuid, nullable, required: UUIDv7, lowercase canonical form. - `startup` WorkspaceStartup, required: Start commands and services of the workspace’s template version; null when the version has none. - `state` 'pending' | 'running' | 'ready' | 'failed', required: pending: a start is in progress and its startup has not begun (or never ran); running: start commands, services or readiness waits are running; ready: every step succeeded; failed: a step failed (the workspace still runs so it can be inspected; the next open runs the failed step again). - `trigger` 'create' | 'boot' | 'resume', nullable, required: create: a new workspace layer; boot: a cold boot; resume: a memory restore. null while pending. - `step` string, nullable, required: The start command (or `services`, `ready:`) running or failed. - `service` string, nullable, required: The service that failed or is awaited. - `exit_code` integer, nullable, required - `output_tail` string, nullable, required: Up to the last 4096 bytes of the failed step’s output (stdout and stderr interleaved). - `reason` string, nullable, required: Failure reason: startup_failed, service_not_ready, secrets_unavailable, secret_not_available or guest_feature_unavailable. - `operation_id` string, uuid, nullable, required: UUIDv7, lowercase canonical form. - `at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z. - `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_revision` integer, 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_available` object, nullable: Supported target dimensions of an opt-in upgrade; null dimension stays unchanged. - `memory_layout` integer, nullable, required - `guest_revision` integer, nullable, required - `template_version` integer, nullable, required - `upgrade_pending` object, nullable: The pinned upgrade target awaiting its cold start. - `computer_use` ComputerUse, required - `enabled` boolean, required: Effective: tool tokens carry the computer tool (the workspace’s value, else the template’s, and the version runs a desktop). - `workspace` boolean, nullable, required: The workspace’s own value; null follows the template. - `template` boolean, required: The template’s switch for its workspaces. - `available` boolean, required: The workspace’s template version can run a desktop (its guest agent has desktop.v1). - `created_at` string, date-time, required: RFC 3339 UTC timestamp with Z. - `updated_at` string, date-time, required: RFC 3339 UTC timestamp with Z. - `deleted_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z. - `operation` Operation, required - `id` string, uuid, required: UUIDv7, lowercase canonical form. - `kind` 'open' | 'suspend' | 'resume' | 'fork' | 'snapshot' | 'restore' | 'delete' | 'move' | 'resize' | 'upgrade' | 'volume_create' | 'volume_attach' | 'volume_detach' | 'volume_delete' | 'reset' | 'layer_snapshot', required - `state` 'queued' | 'capacity_pending' | 'running' | 'succeeded' | 'failed' | 'canceled', required - `workspace_id` string, uuid, nullable, required: UUIDv7, lowercase canonical form. - `volume_id` string, uuid, nullable: UUIDv7, lowercase canonical form. - `created_at` string, date-time, required: RFC 3339 UTC timestamp with Z. - `updated_at` string, date-time, required: RFC 3339 UTC timestamp with Z. - `started_at` string, date-time, nullable: RFC 3339 UTC timestamp with Z. - `completed_at` string, date-time, nullable: RFC 3339 UTC timestamp with Z. - `state_reason` string, nullable: Closed reason code while waiting (e.g. capacity_pending: no_ready_host). - `input` object - `error` object - `result` object - `durable` boolean: suspend and fork: whether the capture is in durable storage. false while `durability.state` is pending (the suspend completed on its host) or lost; true once it committed. Absent on other kinds. - `suspend_path` string: suspend: `local_commit` when the suspend completed on its host and the durable copy followed in the background. - `durability` object - `state` 'pending' | 'durable' | 'lost', required: pending: sealed on its host, the durable copy is being written; durable: the copy committed; lost: the copy could not be made and the previous recovery point stays current. - `checkpoint_id` string: The checkpoint being made durable. - `generation_id` string: Its generation on the host. - `local_commit_at` string: RFC 3339: when the suspend (or fork) completed on its host. - `durable_by` string: RFC 3339: when the durable copy is expected to have committed (local_commit_at + the deadline). - `durable_at` string: RFC 3339 (state durable): when the durable copy committed. - `local_commit_to_durable_ms` number: State durable: local_commit_at to durable_at, in milliseconds. - `overdue_at` string: RFC 3339: set once durable_by passed while the copy was still pending; it keeps retrying. - `reason` string: State lost: why, e.g. host_lost. - `code` string: State lost: the error code of the failed copy. - `recovery_point_checkpoint_id` string, nullable: State lost: the durable checkpoint that stays the recovery point (null when there is none). - `lost_suspend` object - `checkpoint_id` string, required: The suspend checkpoint whose durable copy was lost. - `generation_id` string: Its generation on the host. - `reason` string: Why it was lost, e.g. host_lost. - `suspended_at` string: RFC 3339: when that suspend captured the workspace. - `restored_checkpoint_id` string: The earlier durable checkpoint this resume restored. - `state_as_of` string: RFC 3339: when the restored checkpoint committed; the workspace state is as of then. - `host_lost` object - `detected_at` string, required: RFC 3339: when the host failure was detected; the workspace was suspended then. - `restored_from` 'disk' | 'checkpoint': resume and open: disk when the workspace booted from its disk (files kept, processes and memory not); checkpoint when it was restored from its newest checkpoint (see state_as_of). Absent on a suspend. - `restored_checkpoint_id` string: restored_from checkpoint: the checkpoint this resume restored. - `state_as_of` string: restored_from checkpoint, RFC 3339: when that checkpoint committed; the workspace state is as of then. - `progress` SuspendProgress - `operation_id` string, uuid, required: UUIDv7, lowercase canonical form. - `state` 'queued' | 'capacity_pending' | 'running' | 'succeeded' | 'failed' | 'canceled', required - `workspace_state` 'creating' | 'starting' | 'running' | 'suspending' | 'suspended' | 'resuming' | 'forking' | 'stopping' | 'failed' | 'deleting' | 'deleted', required - `phase` string, required: Actual snapshot preparation/capture phase, or an explicitly unavailable control status. - `cancelable` boolean, required: True only while the host can acknowledge cancellation before its capture cut. - `supported` boolean, required - `safe_action` 'wait_for_terminal' | 'resume' | 'retry_tools' | 'inspect_failure', required - `phase_started_at` string, date-time: RFC 3339 UTC timestamp with Z. - `deadline_at` string, date-time: RFC 3339 UTC timestamp with Z. - `accepted` boolean - `cell_endpoint` string, nullable, required - `tool_token` ToolToken, required - `token` string, required: Compact ES256 JWS; send as `Authorization: Bearer` to the cell gateway. - `token_type` 'Bearer', required - `expires_at` string, date-time, required: RFC 3339 UTC timestamp with Z. - `issued_at` string, date-time, required: RFC 3339 UTC timestamp with Z. - `kid` string, required - `audience` string, required - `workspace_id` string, uuid, required: UUIDv7, lowercase canonical form. - `agent_session_id` string, uuid, required: UUIDv7, lowercase canonical form. - `ownership_epoch` integer, required - `tools` string[], required - `cell_endpoint` string, required - `created` boolean, required: : true when this request created the workspace (a new key, or a key whose session ended), false when it reconnected to or resumed an existing one. Of concurrent opens of one new key exactly one says true; a replay with the same Idempotency-Key repeats it. ## Other responses - `202`: 200: running and ready (tool_token set). 202: poll `operation` (GET /operations/{id}). - `4XX`: Default Response - `5XX`: Default Response --- [API](https://skmtc.dev/shardflux/apis/shardflux-api.md) · [All operations](https://skmtc.dev/shardflux/apis/shardflux-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shardflux/apis/shardflux-api/revisions/ea685f7b39c4?raw)