Detach a workspace
Saves the workspace's execution and stops it. Answers once the stop is under way; the lease is released when the snapshot commits. Idempotent.
Authorization
bearerAuth A RemoteHost API key (rh_sk_...) or a user session token.
In: header
Path Parameters
uuidResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/orgs/string/projects/string/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08/detach"{ "workspace": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa", "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8", "name": "string", "title": "string", "environmentId": "19f5cc2e-7657-437a-9268-83cd3d563563", "lifetimePolicy": "ephemeral", "expiresAt": "string", "gitBranch": "string", "cpuBaseline": "string", "vmm": "string", "currentCheckpointId": "58a17ea9-e017-4666-a39c-b13b4cc338f7", "status": "active", "lease": { "sandboxId": "5b4b1d3f-21e4-43f6-8ac1-b460b150f885", "epoch": "string", "expiresAt": "string", "live": true }, "createdBy": "25a02396-1048-48f9-bf93-102d2fb7895e", "createdAt": "string", "updatedAt": "string", "lastActivityAt": "string" }, "sandbox": { "id": "string", "org_id": "string", "project_id": "string", "name": "string", "agent": "claude", "status": "provisioning", "mode": "persistent", "region": "string", "persistence_policy": "throwaway_ephemeral", "sandbox_profile": "string", "machine_size": "small", "provider": "string", "vmm": "string", "allocated_vcpu": 0, "allocated_memory_gb": 0, "allocated_disk_gb": 0, "end_user_id": "string", "vm_lost_at": "string", "environment_id": "string", "disk": { "usedBytes": 0, "totalBytes": 0, "availableBytes": 0, "warning": 80, "sampledAt": "string" }, "created_at": "string", "updated_at": "string" }, "detached": "stopping"}Attach a workspace POST
Returns a running sandbox for the workspace: the one already running, the sleeping one woken, or a new one. One execution at a time: while another is starting or stopping the call answers 409 workspace_leased. When the host running it has stopped answering, the call answers 409 lease_expired; retrying with takeover: true moves the workspace to a new execution restored from its last saved snapshot, reports what was lost in `recovery`, and never happens while the old execution's host still lists it. A takeover needs sandbox.destroy as well as sandbox.create, is refused with restore_unavailable when the last snapshot never left the unreachable host, and immediately cuts the old execution off: its keys are revoked, and its open terminals, tunnels and preview sockets are closed.
Fork a workspace from a durable checkpoint POST
Creates a new workspace in the same project that starts as a copy of this one at a durable checkpoint: its disk and memory, uncommitted work included. checkpointId defaults to the workspace's head. The fork starts asleep with one stopped execution; the first attach wakes it. It gets its own git branch, remotehost/<name>; nothing is pushed. Needs sandbox.create and sandbox.destroy on the project, and only the workspace's owner may fork it (403 workspace_owner_only). A checkpoint that is not durable yet is refused with 409 checkpoint_not_durable, one of another workspace with 404 checkpoint_not_found, a checkpoint whose saved state is no longer in storage with 409 checkpoint_unavailable, a workspace that is not active or sleeping with 409 workspace_unavailable, and a workspace with no checkpoint at all with 409 nothing_to_fork. The fork keeps the source's lifetimePolicy and has no expiresAt. Off unless the server enables it; while off the route answers 404. A workspace with a work volume is forked with a copy of that volume. A running workspace's volume is committed first, so the copy holds every write made before the fork was asked; a commit that fails or does not answer in time is refused with 409 workspace_unavailable. A fork at a named checkpoint is refused with 409 checkpoint_volume_moved once the volume has changed since that checkpoint, as is a fork of a workspace that is stopping. A copy smaller than 4096 bytes is refused with 409 work_volume_too_small. The copy is refused as a volume create is (409 volume_limit_exceeded, 429 rate_limited, 404 not_found), and with 503 volume_service_unavailable when the volume service does not answer.